Follow

cml:taxonomy - Tree Search and Input Tool

cml:taxonomy

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

src

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
myTaxonomy
= {
// 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 http://www.myserver.com/taxonomy, issuing a GET to http://www.myserver.com/taxonomy?callback=myCallback should return the JSONP response

myCallback( 
// My taxonomy data...
)

root-select

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.
 

multi-select

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

 

select-all

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

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]"

nonselectable

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

top-level

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.

search-src

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 ishttp://www.myserver.com/taxonomy_search, issuing a GET tohttp://www.myserver.com/taxonomy_search?callback=myCallback&q=dogs should return a JSONP response like:

myCallback( 
[
{'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.
log-search

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'
}
}
}
topLevel
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.
taxonomyItems
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