What is this widget?
The ANDS Vocabulary Widget allows you to instantly add Data Classification capabilities to your data capture tools through the ANDS Vocabulary Service.
- Searching for vocabulary terms
- Creates a navigable “autocomplete” widget, with users able to search for the appropriate controlled vocabulary classification when inputting data.
- Narrowing on a (hierarchical) vocabulary item
- Populates a select list (or autocomplete textbox) with items comprising a base vocabulary classification URI.
- Browsing a (hierarchical) vocabulary set as a tree
- Creates a tiered term tree (such as that used in the RDA “Browse” screen)
It is also possible to use the widget in a more programmatic manner; refer to the ‘core usage’ section below for more details.
How do I use this plugin?
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.
The widget requires jQuery; load this, and the plugin itself (and associated CSS styles) in your document’s <head></head> segment:
Search a vocabulary for matching terms, provided in an autocomplete-style list:
Narrow or collection mode can be attached to a
select element to provide a drop-down, or a text
input box for an autocomplete-style list:
narrowmode usually expresses a direct parent-child relationship in the vocabulary (such as skos:narrower).
collectionis used to express less strong groupings of concepts in a vocabulary (such as skos:Collection or even rdf:list).
Tree mode constructs a clickable vocabulary tree for a given repository. Bind to the
treeselect.vocab.ands event to handle user selection.
The plugin accepts a suite of options, detailed below. Please note that some options are required, and don’t have default values (such as
Be sure to quote strings, and separate multiple options with a comma (
Alternatively, options can be set after initialisation using the following form:
$(...).vocab_widget('[option name]', [option value]);
This works for all options except
mode, which must be specified at initialisation (or omitted for core usage).
Some options are specific to the chosen mode; the tables below are grouped in a way that makes this easy to comprehend. Core usage of the widget exposes all “common” options.
||required Vocab widget mode:
||required The SISSvoc repository to query (e.g.
||Your pre registered api key which will uniquely identify the widget user|
||At most, how many results should be returned?|
||Cache SISSvoc responses?|
||Message title to display (via a js ‘alert’ call) when an error is encountered. Set to
||Location (absolute URL) of the (JSONP) SISSvoc provider.|
“SEARCH” HELPER OPTIONS
||How many characters are required before a search is executed?|
||How long to wait (after initial user input) before executing the search? Provide in milliseconds|
||Message to display when no matching concepts are found. Set to
||CSS ‘class’ references for the dropdown list. Separate multiple classes by spaces|
||Which fields do you want to display? Available fields are defined by the chosen repository.|
||What data field should be stored upon selection?|
“NARROW” OR “COLLECTION” HELPER OPTIONS
||requiredFor narrow mode,
||In narrow mode, this option must be overridden to be a single-element array of string . This selection defines the label for the select list options.|
||What data field should be stored upon selection? In narrow mode, this field is used as the
This form section is using the widget with no helpers; it outputs a list of known
rifcs identifier types
Core usage exposes 3 functions
These take a single additional parameter, which can look like any of the following
- plain string
- Search term (for search call) or narrow URI (for narrow call)
- ‘uri’ works as the plain string description above, and should be set
When run in advance mode, events are fired to allow you to hook into the workflow and implement your customisations as you see fit.
||Hook into the plugin’s
||Hook into the plugin’s
||Hook into the plugin’s
||Fired when a tree item is clicked. The selected item is the
||This event is fired whenever there is a problem communicating with the plugin’s
Note: If the error occurred during an AJAX call, the object will be a bona fide XMLHttpRequest / xhr. Otherwise, a dummy plain object with ‘status’ and ‘responseText’ properties will be available.
The SISSVOC data object returned by the above events (and also attached to the ‘treeselect’ event’s ‘vocab’ data object) is a plain javscript object with the following properties:
- ‘OK’ if all good, something else (most likely ‘ERROR’ if not)
- description of the underlying system call by default, or information on status when something went wrong
- the maximum number of records requested
- an array of SISSVOC vocabulary items:
- item description
- item label
- item definition / URL
- parent term (if it exists)
- child terms (if they exist, otherwise boolean false)
- fequency of use among ANDS registry objects (experimental; works best on ANZSRC-FOR, not so well on RIFCS)
- the number of items returned