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 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 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.
Taxonomy Data Format

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

Screen_Shot_2018-08-03_at_10.38.47_AM.png

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

Screen_Shot_2018-08-03_at_10.39.00_AM.png

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?
4 out of 5 found this helpful


Have more questions? Submit a request
Powered by Zendesk