Login

Login

Overview

CML is CrowdFlower Markup Language. CML is made up of a set of helper tags, which makes defining forms to collect information from our labor pools quick and painless.

The interactive form builder automatically generates most of these helper tags. If you need more control over your forms, or you simply prefer interacting with CrowdFlower through the API, CML is for you.

Why CML?

CML has 4 main advantages over raw HTML:

  1. CML automatically namespaces form elements. Because we display multiple forms in a single page, all form elements must be properly namespaces. CML takes care of that for you.
  2. CML lets you write less markup. There is no need to wrap your form elements in containers or add labels, CML writes all the extra markup for you.
  3. CML stores meta information specific to the CrowdFlower platform. Gold specification and directives for how you want your data aggregated are specified directly on the form elements.
  4. CML makes input validation simple. Add validates="required numeric" to any CML tag, and we’ll be sure you’ll get only numbers back.

Base tags

CML currently consists of the following base tags:

<cml:text />
A single line text field.
<cml:textarea />
A multiline text field.
<cml:checkbox />
A single checkbox.
<cml:checkboxes />
A group of checkboxes.
<cml:radios />
A group of radio buttons.
<cml:select />
A dropdown menu.
<cml:hidden />
A hidden field.
<cml:meta />
Meta information used to describe gold or aggregation information for custom non-CML fields.
<cml:group />
A wrapper used to group multiple fields together. This is most useful when used in conjunction with the only-if attribute.

Child tags

CML currently consists of the following child tags: These tags must be a child of one of the tags mentioned above.

<cml:checkbox />
A member of a checkbox group.
<cml:radio />
A member of a radio group.
<cml:option />
A member of a select group.
<cml:instructions />
A member of any base tag, used to specify extra instructions to the user.
<cml:gold />
A member of any base tag, used to define a base tag’s gold specification.

Common attributes

label
Every CML base tag (along with the cml:checkbox and cml:radio child tags) can have a label attribute. This will be displayed next to the generated form element. If no name attribute is specified on a base tag, this will be converted into a name by removing alpha-numeric characters and replacing spaces with an underscore.
name
Every CML base tag (except cml:group) along with the cml:checkbox and cml:radio child tags can have a name attribute. This must be unique across all base tags. The name should not contain capital letters, spaces, or non alpha-numeric characters. This will become a column header in your generated CSV.
value
The primary use for this attribute is setting cml:hidden tag values. In the case of cml:option, cml:checkbox and cml:radio, label will become the value if none is specified. If you want to have a default value for cml:text or cml:textarea, we suggest using the default attribute as this provides a better experience for the user.
default
When specified on cml:option, this becomes the first element in the dropdown and has a value of "". When used on cml:textrea or cml:text, this provides an example input for the user and disappears once the user selects the form element. Default values will not be submitted.
instructions
Every CML base tag can have an instructions attribute. This will be displayed next to the generated form element to help clarify the desired input. If both an instructions attribute and a <cml:instructions /> tag is specified, only the value of the attribute will be used.
only-if
Every CML base tag can have an only-if attribute. The value of this attribute should be the name of the field a user must complete before this field or group of fields will be displayed. See logic for more details.
validates
Every CML base tag can have a validates attribute. This attribute enforces the specified validations to occur on this form element. See validations for more details.
aggregation
Every CML base tag can have an aggregation attribute. This attribute tells us how to aggregate your data once it has been collected. The value of this attribute can currently be avg, agg, or all. See aggregation for more details.
gold
Every CML base tag except cml:group can have a gold attribute. If set to "true" this will link the form element with the data specified in the form_element_name_gold column of your uploaded spreadsheet. If it is not set to “true,” it will link the form element with the column specified. See gold for more details.

Base tag examples

cml:text

<cml:text label="My text box" />

cml:textarea

<cml:textarea label="My textarea" />

cml:checkbox

<cml:checkbox label="My checkbox" />

cml:checkboxes

<cml:checkboxes label="Symptoms">
  <cml:checkbox label="Shortness of breath" />
  <cml:checkbox label="Hair loss" />
</cml:checkboxes>
Symptoms

cml:radios

<cml:radios label="Are you sure?">
  <cml:radio label="Positive" />
  <cml:radio label="Not really" />
</cml:radios>
Are you sure?

cml:select

<cml:select label="Basic">
  <cml:option>One</cml:option>
  <cml:option>Two</cml:option>
  <cml:option>Three</cml:option>
</cml:select>

cml:hidden

<cml:hidden name="secrets" value="Too many" />

cml:meta

<cml:meta name="custom" gold="true" aggregation="avg" />

cml:group

<cml:group only-if="symptoms">
  <cml:checkbox label="My checkbox" />
  <cml:text label="My text box" />
</cml:group>

CML Docs