Guide to: CML Logic

CML logic allows you to populate questions based off a contributor’s answer to a previous question. This allows you to make a more streamlined flow as contributors won't be prompted to answer questions that may not be relevant. Here we will go over the basics of simple and advanced applications of CML logic. 

Basic only-if Statements

Logic using values:

The most common method of using only-if logic is to specify the name of the question and the value or answer choice that should trigger the secondary logic dependent question. This syntax also works with cml:checkboxes.

In this example, the cml:text question will be shown only if the cml:radio question was selected as “Yes”:

<cml:radios label="Can you find a official business URL?" name="url_found"> 
  <cml:radio label="Yes" value="yes" /> 
  <cml:radio label="No" value="no" /> 
</cml:radios> 

<cml:text label="Enter the official URL" only-if="url_found:[yes]" validates="required" />

Note: If the answer values are numberic, the only-if logic will need to reference the index instead of the answer option. See the next section for additional details. 

Logic using index:

You can also use the index number instead of the question’s name or value. The index value is 0-based. The first answer is "0", the second is "1", and so on.

Here's an example of using the index of the answer option with CML logic:

<cml:radios label="Does this tweet mention an Airline?" name="tweet_relevance"> 
  <cml:radio label="Yes"/> 
  <cml:radio label="No"/>
</cml:radios>

<cml:text label="How many likes does this tweet have?" only-if="tweet_relevance:[0]" validates="required" />

This example shows that the cml:text question, "How many likes does this tweet have?", will only be shown if the cml:radio, “Does this tweet mention an Airline?”, is selected as ‘Yes’. This is because the first answer option has the index value of ‘0’.

Logic by text input:

<cml:text label="How many likes does this tweet have?" name="likes" validates="required integer" /> 

<cml:radios label="What was the sentiment of the tweet?" only-if="likes" validates="required" >
   <cml:radio label="Positive" />
   <cml:radio label="Neutral" />
   <cml:radio label="Negative" />
</cml:radios>

In this example, the "What was the sentiment of the tweet?" question will display only if the "How many likes does this tweet have?" question passes all of its validators (requires an integer).

Logic by single checkbox:

Logic can also be used with a single cml:checkbox.

<cml:radios label="What is the sentiment of this tweet?" validates="required" name="sentiment" only-if="not_available:unchecked">
 <cml:radio label="Positive" /> 
 <cml:radio label="Neutral" />
 <cml:radio label="Negative" />  
</cml:radios>
<cml:checkbox label="Tweet is not available" name="not_available"/>

Note: For a single cml:checkbox do not use the logical "not" operator ! when writing your cml only-if statement. While this does work in job preview, it does not work on launched jobs. The proper syntax is shown in the example above where only-if='not_available:unchecked'.

Below is an example of the incorrect syntax.

<cml:radios label="What is the sentiment of this tweet?" validates="required" name="sentiment" only-if="!not_available">
 <cml:radio label="Positive" /> 
 <cml:radio label="Neutral" />
 <cml:radio label="Negative" />  
</cml:radios>
<cml:checkbox label="Tweet is not available" name="not_available"/>

Advanced only-if statements

Advanced only-if statements can be used alone or in combination with other statements 

"Or"

"Or" logic can be used in indexed only-if selectors. Use two pipe characters "|" to specify an "or" relationship between values:

<cml:radios label="What is the sentiment of this tweet?" name="tweet_sentiment" > 
  <cml:radio name="Very Positive" value="very_positive"/> 
  <cml:radio name="Slightly Positive" value="slightly_positive"/> 
  <cml:radio name="Neutral" value="neutral"/> 
  <cml:radio name="Slightly Negative" value="slightly_negative"/> 
  <cml:radio name="Very Negative" value="very_negative"/> 
</cml:radios> 

<cml:text label="How many likes did the tweet have?" only-if="tweet_sentiment:[very_positive]||tweet_sentiment:[slightly_positive]" validates="required" />

In this example, we only want to collect the number of likes when the sentiment of the tweet is positive.

“And”

“And” logic follows the same rules and uses two ‘++’ characters to specify it.

<cml:radios label="What category does the product belong in?" name="item_relevance" >
  <cml:radio label="Electronics" value="electronics"/> 
  <cml:radio label="Household" value="household"/> 
  <cml:radio label="Clothing" value="clothing"/>
  <cml:radio label="Food" value="food"/> 
</cml:radios>

<cml:radios label="Is this item in stock?" name="in_stock" validates="required">
  <cml:radio label="Yes" value="yes"/>
  <cml:radio label="No" value="no"/>
</cml:radios>

<cml:radios label="Are there accessories included?" name="item_accessories" only-if="item_relevance:[electronics]++in_stock:[yes]" validates="required">
  <cml:radio label="Yes" value="yes"/>
  <cml:radio label="No" value="no"/>
</cml:radios>

In this example, the cml:text question will only be asked if “Electronics” from the first question and “Yes” from the second question are both chosen.

“Not”

“Not” logic will be used if you want to display another question only-if the answer to the question is not a specific answer.

<cml:radios label="How does the result match the query?" validates="required" name="search_relevance">
  <cml:radio label="Off Topic" value="off_topic"/>
  <cml:radio label="Poor" value="poor"/>
  <cml:radio label="Acceptable" value="acceptable"/>
  <cml:radio label="Excellent" value="excellent"/>
</cml:radios>

<cml:text label="Are there any colors mentioned in the result?" validates="required" only-if="!search_relevance:[off_topic]" ></cml:text>

In this example, the cml:text question will only be asked if the result of the search query is not “Off Topic”.