cml:taxonomy - Tree Search and Input Tool

Note: cml:taxonomy will be deprecated and replaced with a new Taxonomy tool. Please see this article for instructions on how to use the new 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. 

Figure 1: cml:taxonomy via Preview

Additional Attributes


The taxonomy datasource will be a URL defined in the CML. 

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

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.

Taxonomy Data Format

Taxonomy data should be in a CSV file formatted as shown below.


Figure 2: Taxonomy Data Format in a CSV

Each row represents a category and its parent category. Headers must include

  • category_1  through category_n: category_1 is the top level category, followed by any number of sub-categories
  • notes: Any information displayed in the taxonomy to help contributors.
  • category_id: This is an alphanumeric id that indicates the current category. Each row should have a unique cataegory_id. 

Example taxonomy tool with the file above


Figure 3: cml:taxonomy via Preview given example file above

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.

Where to Place Taxonomy Tags

Once the taxonomy has been created, two tags will be provided.  One tag is to be pasted into the CML Code Editor. 

The CML tag will look something like this and can be placed directly in the CML Field:

<cml:taxonomy only-if="" src="myTaxonmyzer" name="taxonomy_name" label="" aggregation="agg" validates="required" gold="true" search-src=""></cml:taxonomy>


Figure 4: Taxonomy tag in CML

The instructions tag will look something like this can be placed into the Instructions Editor via Code View:

<script src="//" type="text/javascript"></script>


Figure 5: Taxonomy tag in Instructions via Code View

Was this article helpful?
6 out of 11 found this helpful

Have more questions? Submit a request
Powered by Zendesk