cml:taxonomy - Tree Search and Input Tool

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.

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="https://taxonomyzer.appen.com/taxonomies/1313/search/my_taxonomy.json"></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="//crowdflower-taxonomyzer-development.s3.amazonaws.com/my_taxonomy.js" type="text/javascript"></script>

Figure 5: Taxonomy tag in Instructions via Code View