Research Activity Lookup Widget

What is this widget?

The ANDS Research Activity Lookup Widget is a jQuery plugin that provides the ability to lookup, search for and display activity records from Research Data Australia. The widget is built upon the Research Activities API.

Some use cases for the Registry Object Search Widget include:

  • Implement a lookup function in data capture forms/processes to facilitate the linking of research outputs to any grants that funded the activity which produced them.
  • Supplement your site’s search results with research activity search results from Research Data Australia
  • Provide your users with a listing of research activities related to a specific subject

Demo

This example shows how to embed the Activity Lookup widget into your webpage. In this example a search has been automatically run upon load for all of the activities of type ‘grant’ funded by the ‘Department of the Environment’.

  • if you already know your Grant id, put it into the text field  at the top and it will be automatically looked up and displayed if found.
  • if you don’t know your Grant id, you can use the search to find your grant. Upon clicking a search result the grants PURL will be populated into the text field and it will be automatically looked up and displayed.

How to use this widget

Before you start! While optional, ANDS recommends that you register for a free API key to be used with this widget. Registering will allow us to keep you informed of changes and planned outages to our services, as well monitor the system for quality purposes.

Note that if you have previously registered for an API key you do not need to register again. Your ANDS API key is reusable with any of our widgets and services.

Getting Started

Install using bower

bower install ands-registry-widget

Include jQuery dependency

<script src="node_modules/jquery/dist/jquery.min.js"></script>

Include the provided distribution file

<script src="dist/jquery.ands.registry-widget.min.js"></script>

Instantiate the plugin with

$("#registry_widget").registryWidget({
    // options
});

ANDS Registry Widget comes with out of the box support for Twitter Bootstrap styling and Mustache templating engine. Include them to get the same functionality as the available demo page

<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.min.css">
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap-theme.min.css">
<script src="bower_components/bootstrap/dist/js/bootstrap.min.js"></script>
<script src="bower_components/mustache.js/mustache.min.js"></script>

Configuration

Parameter Description
apiKey The API Key that this widget will use to access the ANDS Registry API
mode Use this parameter to set the mode of the widget. Available modes:
lookup-activity - This mode configures the widget to display a single input text field which attempts to lookup and display an activity based on the entered PURL identifier.
search-activity - This mode configures the widget to display both an input text field which attempts to lookup and display an activity based on the entered PURL identifier and also the search form.
display-activity -  This mode configures the widget to display the details of a single activity with no input or search. See the relevant example below for more details.
searchOptions This parameter is used to configure how the search functionality in the widget displays and functions. The searchOptions parameter must be a JSON object of name/values pairs. See the list below for the field names and values.
autoSearch:true|false

Use this option to tell the widget if it should automatically execute a search with the configured params option on load.

autoLookup:true|false

Use this option to tell the widget if it should automatically do an activity lookup on values entered into the <input> text field.

returnType:purl|title|id

This option configures the field value which is returned into the <input> text field upon selecting a search result. By default it is set to purl.

facets:institutions|funders|type|fundingScheme|status

Use this option to configure which filters should be displayed with the search.

Combine this with the params option to set default values for the filters.

facetSort:index|count

This option is used to determine the sort order of the facets

openIn:bootstrap-modal

This option can be used to enable a popout Bootstrap modal for the search. By default it is set to nothing and the search displays below the <input> text field

params

Use this option to configure the search parameters for the widget. By default only the limit (30), pp (30)All good and offset (0) parameters are set.

For a full list of available search parameters see the Research Activities API.

Example:
{
type: 'grant',
funder: '"Department of the Environment"',
limit: 5,
pp: 5
}

An example use case for this option would be limit the search functionality to only activities from a specific funder. To configure this pass through a funder parameter in the params option with a specific value, and ensure that the funders option is not provided in the facets parameter.

Search Parameters can also be embed into the target via the HTML data attribute. For example
<div id="display-activity" data-purl="http://purl.org/au-research/activitys/arc/DP140100435"></div>

searchQueryOptions Use this parameter to configure the search query options displayed in the drop-down with the search bar (e.g. All, Title, etc) .

By default it’s set to all of the available options as shown below.

[
{ value: "q", display: "All" },
{ value: "title", display: "Title" },
{ value: "description", display: "Description" },
{ value: "researcher", display: "Researcher" },
{ value: "principalInvestigator", display: "Principal Investigator" },
{ value: "id", display: "Identifier" },
{ value: "subject", display: "Subject" }
]

 

Development

If you wish the extend the widget you will need to install the following dependencies

npm install
bower install

Running automated tests

grunt karma

Leave a Reply

Your email address will not be published. Required fields are marked *

five × 4 =