Controlled Vocabulary Widget V2

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.

The widget has been written in the style of a jQuery plugin, allowing complete control over styling and functionality with just a few lines of javascript. The widget also ships with some UI helper modes for:

  • 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:

<script src='//'></script>
<script type="text/javascript" src="//"></script>
<link rel="stylesheet" type="text/css" href="//" />



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:

  • narrow mode usually expresses a direct parent-child relationship in the vocabulary (such as skos:narrower).
  • collection is 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 repository: you must provide values for such options. Incorrectly configured plugins will result in a javascript ‘alert’ box being displayed, describing the nature of the configuration problem.

Options are passed into the plugin using a Javascript hash/object, such as

$("#vocabInput").vocab_widget({cache: false});

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.

Note: ‘tree’ mode has no specific configuration other than the widget’s common options.


Property Defaults Description
mode '' required Vocab widget mode: searchprovides an autocomplete widget on an HTML input element, while narrow or collectionpopulate an HTML select element with appropriate data. advanced mode exposes the core widget with no UI helpers.
repository '' required The SISSvoc repository to query (e.g.anzsrc-for, rifcs)
api_key 'public' Your pre registered api key which will uniquely identify the widget user
max_results 100 At most, how many results should be returned?
cache true Cache SISSvoc responses?
error_msg "ANDS Vocabulary Widget service error." Message title to display (via a js ‘alert’ call) when an error is encountered. Set to false to suppress such messages
endpoint "" Location (absolute URL) of the (JSONP) SISSvoc provider.


Property Defaults Description
min_chars 3 How many characters are required before a search is executed?
delay 500 How long to wait (after initial user input) before executing the search? Provide in milliseconds
nohits_msg "No matches found" Message to display when no matching concepts are found. Set to false to suppress such messages
list_class "vocab_list" CSS ‘class’ references for the dropdown list. Separate multiple classes by spaces
fields ["label", "notation", "about"] Which fields do you want to display? Available fields are defined by the chosen repository.
target "notation" What data field should be stored upon selection?


Property Defaults Description
mode_params '' requiredFor narrow mode, mode_params defines the vocabulary item upon which to narrow.
fields ["label", "notation", "about"] 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.
target "notation" What data field should be stored upon selection? In narrow mode, this field is used as the valueattribute for the select list options

Advanced Configuration


Invoking the plugin with no ‘mode’ argument exposes core functionality, without having to use form input (text, select) elements or the like. Instead, you hook into javascript Events, building the UI as best fits your needs. A very basic example is shown below: it constructs a list of RIFCS identifier types.

This form section is using the widget with no helpers; it outputs a list of known rifcs identifier types

Core usage exposes 3 functions

  • search
  • narrow
  • top

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)
object {uri:'...', callee:'...'}
‘uri’ works as the plain string description above, and should be set false.
‘callee’ defines the object that will fire the subsequent javascript event. Defaults to the containing element (what you invoked the widget on)


When run in advance mode, events are fired to allow you to hook into the workflow and implement your customisations as you see fit.

Plugin events are placed in the vocab.ands namespace
Event Name Parameters Description
  1. JS Event object
  2. SISSVOC data object
Hook into the plugin’s search core function;data is the search response.
  1. JS Event object
  2. SISSVOC data object
Hook into the plugin’s narrow core function;data is the search response.
  1. JS Event object
  2. SISSVOC data object
Hook into the plugin’s top core function; datais the search response.
  1. JS Event object
Fired when a tree item is clicked. The selected item is the event target. The target will have a ‘vocab’ data object, containing all the details found in a SISSVOC data object.
  1. JS Event object
  2. XMLHttpRequest*
This event is fired whenever there is a problem communicating with the plugin’s endpoint.
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

Leave a Reply

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

fourteen − thirteen =