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.
regex
Allows you to validate worker input against any arbitrary regular expression allowed in JavaScript. Because the regular expression is embedded in an HTML attribute, the following HTML entities will need to be escaped:
  • < → &lt;
  • > → &gt;
  • " → &quot;
The regex validator makes use of attributes to specify the regular expression, its flags, and its behavior:
  • data-validates-regex - The actual regular expression. Remember that the above three special characters need to be escaped as HTML entities.
  • data-validates-regex-flags - Any combination of the standard three regular expression flags. In the context of a validator, only "i" (case-insensitive matching) and "m" (multiline matching of ^ and $) are useful. "g" will have no real effect.
  • data-validates-regex-message - A custom "validation failed message". The default message is "This value didn't match the expected rules."
Examples:
<!-- Case-sensitive regular expression. Passes: "-123" -->
<cml:text label="Negative number" validates="regex" data-validates-regex="^-\d+" />
<!-- Case-insensitive regular expression. Passes: "<a>", "<FONT>" -->
<cml:text label="HTML tag" validates="regex" data-validates-regex="\&lt;[a-z]+&gt;"
    data-validates-regex-flags="i" />
<!-- Custom failure message.-->
<cml:text label="Vowel" validates="regex" data-validates-regex="^[aeiouy]$" 
    data-validates-regex-message="Please enter a vowel." />
<!-- Pass only if the regex *doesn't* match the worker input.-->
<cml:text label="Consonant" validates="regex:'nomatch'" 
    data-validates-regex="^[aeiouy]$" />

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.)
  • domainonly - Strips the entry of everything except the domain.
Example:
<cml:text label="Non-Google Site" validates="required url:['non-google']" />
<cml:text label="Domain Only" validates="required url:{domainonly:true}" />
The url validator submits the following additional data:
  • fieldname_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”
frAddress
Requires a valid address and returns French address components. Unlike the US address validator, the French address validator does not enforce a level of specificity in the address. (However, this can still be enforced via Gold). This validator uses the Google Maps API to return a valid, cleaned address in the French format: “123 Rue de Bercy, Paris, 75012, France”.
Although this address validator is specifically geared towards addresses in France, it does not prevent workers from entering addresses from other countries. Use Gold to ensure that workers don't give you non-French addresses.
In addition to the full normalized address, this validator submits the following components as separate fields (these appear as extra columns in your CSV reports):
  • fieldname_workerInput - raw worker input (before normalization)
  • fieldname_street - street address (eg. "123 Rue de Bercy")
  • fieldname_buildingLabel - building/unit label (eg. "Suite", "Unit")
  • fieldname_buildingNumnber - building/unit number (eg. "A", "1C")
  • fieldname_city - town / city (eg. "Paris")
  • fieldname_postcode - postal code (eg. "75012")
  • fieldname_country - country (eg. "France")
usAddress
The usAddress validator has been deprecated by usAddress2 and will be replaced in the near future.
usAddress2
Requires a valid, specific address and returns US address components. This validator requires the worker to enter an address that is specific to the building level. It uses the Google Maps API to return a valid, cleaned address in the US format: “455 Valencia St, San Francisco, CA, 94103, USA”.
Although this address validator is specifically geared towards US addresses, it does not prevent workers from entering addresses from other countries. Use Gold to ensure that workers don't give you non-US addresses.
In addition to the full normalized address, this validator submits the following components as separate fields (these appear as extra columns in your CSV reports):
  • fieldname_workerInput - raw worker input (before normalization)
  • fieldname_street - street address (eg. "455 Valencia St")
  • fieldname_buildingLabel - building/unit label (eg. "Suite", "Unit")
  • fieldname_buildingNumnber - building/unit number (eg. "A", "1C")
  • fieldname_city - town / city (eg. "San Francisco")
  • fieldname_state - two-letter state abbreviation (eg. "CA")
  • fieldname_zip - postal code (eg. "94103")
  • fieldname_country - country (eg. "USA")
ukAddress
Requires a valid address and returns UK address components. Unlike the US address validator, the UK address validator does not enforce a level of specificity in the address. (However, this can still be enforced via Gold). This validator uses the Google Maps API to return a valid, cleaned address in the UK format: “123 Brookdale, Enfield, Greater London, N11 1, United Kingdom”.
Although this address validator is specifically geared towards UK addresses, it does not prevent workers from entering addresses from other countries. Use Gold to ensure that workers don't give you non-UK addresses.
In addition to the full normalized address, this validator submits the following components as separate fields (these appear as extra columns in your CSV reports):
  • fieldname_workerInput - raw worker input (before normalization)
  • fieldname_route - street address (eg. "123 Brookdale")
  • fieldname_buildingLabel - building/unit label (eg. "Suite", "Unit")
  • fieldname_buildingNumnber - building/unit number (eg. "A", "1C")
  • fieldname_post_town - town / city (eg. "London")
  • fieldname_postcode - postal code (eg. "N11 1")
  • fieldname_country - country (eg. "United Kingdom")

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.
  • whitespace - Removes all whitespace from the input.
  • multipleWhitespace - Replaces all consecutive whitespace with a single space. (For example, multiple spaces and newlines in a row will get replaced with a single space.)
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


Why CrowdFlower?

How it Works What it Means Scalability CrowdEngine Innovation and Expertise

Documentation

Requester Interface Gold CrowdFlower API CML Channel API Image Moderation API

Solutions

eCommerce Online Media and Publishing Data Providers Daily Deals & Local Search Brand Management Self-Service

Products

read more...

Customers

read more...

About

Team Press Resources Jobs Contact

Social Media



Law Talk

Privacy Policy Terms of Service ©2011 CrowdFlower