cml:taxonomy - Tree Search and Input Tool


Renders a widget that allows contributors to search and browse through a hierarchical list of items (a taxonomy) and select an item (or multiple) to be submitted. Taxonomy data must be formatted according to the Taxonomy Data Format section below.


Additional Attributes


The taxonomy datasource; can be either a URL or the name of a Javascript variable defined in the custom Javascript portion of the Code Editor. Javascript variables containing taxonomy data should be in the global scope, i.e. they should be assigned without using the var keyword.

// In your job's cml 
<cml:taxonomy src="myTaxonomy" />

// In your job's javascript
= {
// Taxonomy data (see example data below)...

// WRONG!!! Don't use the 'var' keyword
var myTaxonomy = {
// Taxonomy data (see example data below)...

URLs must accept the parameter callback and return a JSONP response wrapped in the function specified by the callback parameter. For example, if the url that serves taxonomy data is, issuing a GET to should return the JSONP response

// My taxonomy data...


If set to "true", the taxonomy tool will only allow contributors to select top-level items, while still being able to search and browse the full taxonomy. This is useful when only a general category is desired. By default, only taxonomy endpoints are selectable.


If set to "true", the taxonomy tool will allow contributors to select multiple items. By default a contributor can only select one item. 



If set to "true", every taxonomy item will be selectable (normally only taxonomy endpoints are selectable).


Add taxonomy items as selectable in the tool (normally only taxonomy endpoints are selectable). Accepts a comma-separated list of taxonomy item IDs surrounded by square brackets, e.g. "[1,2,3,4]"


Accepts a comma-separated list of taxonomy item IDs to remove as selectable in the tool, e.g. "[5,6,7,8]"


Accepts a comma-separated list of taxonomy item IDs to show as top-level items in the widget. This will override the top-level items set in the taxonomy JSON.


Accepts a URL that accepts the parameters q and callback. It should return taxonomy search results for the query specified by the q parameter as JSONP wrapped in the function specified by the callback parameter. When this attribute is provided, a search box will be rendered below the taxonomy tool, allowing the contributor to search through the taxonomy.

For example, if the search url is, issuing a GET to should return a JSONP response like:

{'name': "Pet Supplies > Dog Dishes", "id": "1234"},
{'name': "Books > Doggies", "id": "5678"}

Search results should be an array of Javascript objects (as shown above) with the following attributes:

  • name (String, required): The name of the taxonomy item to display when search results are rendered.
  • id (String, required): The taxonomy item ID of the search result.

If set to "true", a field containing a comma-separated list of search queries will be returned with the contributor's judgment. This is useful when tuning search results. This attribute will be ignored unless search-src is set.

Taxonomy Data Format

Taxonomy data should be in the JSON format shown below. Each taxonomy item should be associated with a category id.

'topLevel': [1,2],
'taxonomyItems': {
'1': {
'title': 'Books',
'summary': 'Stuff you\'d find in a library',
'children': ['3','4']
'2': {
'title': 'Shoes',
'summary': 'Stuff you\'d find in a shoebox',
'children': ['5','6']
'3': {
'title': 'Good books',
'summary': 'Books you want to read, not {$4}',
'parent': '1'
'4': {
'title': 'Bad books',
'summary': 'Books that suck',
'parent': '1'
'5': {
'title': 'Women\'s shoes',
'summary': 'Shoes for dudettes',
'parent': '2'
'6': {
'title': 'Men\'s shoes',
'summary': 'Shoes for dudes',
'parent': '2'
An array of root-level item IDs for your taxonomy. The items with these IDs will be the first ones shown to the contributor when they see the taxonomy tool.
A Javascript object containing the actual taxonomy items, keyed by item ID. Each taxonomy item can have the following attributes:
  • title (String, required): The name of the taxonomy item that will show up in the tool.
  • summary (String, optional): A brief description of the taxonomy item. Links to other items can be included by enclosing the item ID preceded by a dollar sign in curly braces, e.g. {$4}
  • parent (String, required): The item ID of the item's parent. Required on items that are children of other items.
  • children (Array, required): An array of taxonomy IDs of the item's children. Required on items that are parents of other items.
  • related (Array, optional): An array of taxonomy IDs of items related to this item. Related items will be listed beneath the item description in the taxonomy tool.

CML Taxonomy and CML Logic

The cml:taxonomy widget does not presently work as a CML only-if logic dependency. For example, using the following CML,

<cml:taxonomy name="taxonomyResponse" src="myTaxonomy" />  
<cml:text name="textResponse" only-if="taxonomyResponse" />

the cml:text field would appear regardless of whether or not the cml:taxonomy field contained a value.

Was this article helpful?
1 out of 1 found this helpful

Have more questions? Submit a request
Powered by Zendesk