Login

Login

Validations

CML supports a number of pre-made validation methods to ensure data integrity. Some validators normalize the input, making it possible to create gold for complex data like phone numbers, addresses, and URLs. You can add validators by specifying a validates attribute on your CML form element:

<cml:checkboxes label="Pick one" validates="required">
  <cml:checkbox label="This one is the best" />
  <cml:checkbox label="The first one is lying" />
</cml:checkboxes>
<cml:text label="My text box" validates="required usAddress"/>

Validators are run from left to right, stopping on the first failure. For example, the above cml:text field would validate required first and then, if that validator passes, move on to usAddress and run that validation.

All validators run on blur and submit events. The required validator, however, runs only on submit. Failed validators block submission of the form.

Hidden fields (both of type hidden and those contained in elements with display: none; styling are not validated.)

General Validators

required
On a free text input, at least one non-whitespace character must be present. On a multiple choice or drop-down field, it enforces at least one item to be selected.

Number Validators

integer
Requires an integer value, e.g., 10, -5
positiveInteger
Requires a positive integer value, e.g., 10, 5
numeric
Requires an integer or floating-point value, e.g., 10, 1.5, -2.4
digits
Allows only numbers and punctuation, e.g., “10:10-99”, “100(2)”
integerRange
Ensures that the worker inputs an integer within a given range. Note: The values are inclusive.
<cml:text label="A number between 1 and 100, inclusive" validates="integerRange:{min:1,max:100}"/>

Text Validators

alpha
Requires only letters, e.g., “ABCabc”
alphanum
Allows only numbers and letters, e.g., “ahfd723nd”
date
Requires a date in MM/DD/YYYY format, e.g., “01/21/2010”
minLength
Ensures that the user's input is at least a certain number of characters long.
<cml:text label="4 or more characters" validates="minLength:4"/>
maxLength
Ensures that the user's input is, at most, a given number of characters long.
<cml:text label="32 or fewer characters" validates="maxLength:32"/>
rangeLength
Ensures that the user's input is within a given length range. Note: The values are inclusive.
<cml:text label="5 to 32 characters long" validates="rangeLength:{min:5,max:32}"/>
currencyDollar
Allows only a dollar amount, e.g., “$153.40”
currency
Allows only monetary amounts with a valid currency symbol or currency code. e.g. “£1.500,57”, “1,200 DKK”. Both commas and periods are accepted as valid digit group delimiters and most international currency codes and symbols are recognized. Currency amounts are normalized to “¥1,200” or “1,200.00 JPY” -style formatting. If a list of currency codes and/or symbols is provided, valid currency types are restricted to those provided.
<cml:text label="Valid currency amount" validates="currency"/>
<cml:text label="Valid USD or GBP amount" validates="currency:['$','£','USD','GBP']"/>
usPhone
Requires a valid US phone number, e.g. “555-123-4567” This validator normalizes the worker input, removing the US country code, and formatting it as ###-###-####. This validator allows the user to enter an extension number as a separate field.

Web Validators

email
Requires a valid-looking email address, e.g., “bob@example.com”
url
Requires a valid-looking URL, e.g., “http://crowdflower.com.” This validator performs some normalization of the entered URL to make it more useful for gold-digging but also submits the user's original input. The normalization includes removing “www.”, changing “https://” to “http://”, removing index pages such as “index.html” and “home.html,” and adding a trailing slash when needed. The url validator accepts the following optional restrictions:
  • google - Requires a google.___ domain
  • non-google - Forbids a google.___ domain.
  • non-search - Forbids most major search domains (Google, Bing, Yahoo, Yelp, etc.)
Example:
<cml:text label="Non-Google Site" validates="required url:['non-google']" />
The url validator submits the following additional data:
  • field_name_worker_input - the raw worker input.
urlImage
Requires a URL for a valid image. This validator executes an asynchronous request to validate that the URL points to a valid image. This validator does no “cleaning” of the worker’s input.

Address Validators

stateAbbr
Requires a valid US state abbreviation, e.g., “CA”, “NY”
zipcode
Requires a valid US zip code, e.g., “94103”
usAddress
Requires a specific, valid US address. This validator uses the Google Maps API to return a valid, cleaned US address in the following format: “455 Valencia St, San Francisco, CA 94103, USA”.
The usAddress validator submits the following additional data:
  • field_name_workerInput - the raw worker input (before normalization).
  • field_name_street_component - the normalized street component.
  • field_name_city_component - the normalized city component.
  • field_name_state_component - the normalized state component (two-character code).
  • field_name_zip_component - the normalized zip code component.
  • field_name_country_component - the normalized country component.

Special Validators

clean
Cleans the worker's input. The worker can never "fail" this validator as it does not actually validate anything, it simply cleans their input. You can use any combination of the following cleaners:
  • trim - Removes leading and trailing whitespace.
  • titlecase - Capitalizes all words that are not all uppercase nor most conjunctions.
  • uppercase - Replaces all lowercase letters with uppercase letters.
  • lowercase - Replaces all uppercase letters with lowercase letters.
Cleaners are processed in the order that they are defined.
<cml:text label="Titlecase" validates="required clean:['titlecase']" />
<cml:text label="Trimmed and Lowercased" validates="required clean:['trim','titlecase']" />
user_agent
This simply sets the input's value to the worker's user-agent string. This is useful for debugging. For example, if you're asking users to evaluate your site, you can use this validator to help diagnose complaints about broken pages.
This should be used only in cml:hidden tags.

CML Docs