Follow

Guide to: Validators

CML supports a number of pre-made validation methods to ensure data integrity. Some validators normalize the input, making it possible to create test questions 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 stateAbbr"/>

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 stateAbbr and run that validation.

All validators run on blur and submit events, which means clicking out of a text field will run the set of validators. 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 
<cml:radios label="Sample radio buttons:" validates="required">
  <cml:radio label="Radio 1" />
  <cml:radio label="Radio 2" />
  <cml:radio label="Radio 3" />
</cml:radios>

Number Validators

integer
Requires an integer value, e.g., 10, -5
<cml:text label="A number" validates="integer"/>
positiveInteger
Requires a positive integer value, e.g., 10, 5
<cml:text label="A positive integer" validates="required positiveInteger" />
numeric
Requires an integer or floating-point value, e.g., 10, 1.5, -2.4
<cml:text label="A numeric number" validates="required numeric" />
digits
Allows only numbers and punctuation, e.g., "10:10-99", "100(2)"
<cml:text label="A number" validates="required digits" />
integerRange
Ensures that the contributor inputs an integer within a given range. This should only be used in combination with the integer validator. Note: The values are inclusive.
<cml:text label="A number between 1 and 100, inclusive" validates="integer integerRange:{min:1,max:100}"/>
internationalPhoneNumber
Requires that a phone number is entered in for the correct country and the number is formatted correctly
<cml:text name="phone" validates="required internationalPhoneNumber" />
Which is the same as:
<cml:text name="phone" validates="required internationalPhoneNumber:{country:'CH',formatOnInput:false,outputFormat:'itnl'}" />
The options for this validator are as follows, with default values in parentheses:
  • country ('US') validate for this country's phone number conventions, accepts a two-letter country code or the string 'detect'. If 'detect' is specified, the validator will attempt to auto-determine the country for the given phone number, but the number must be in loose e164 format, including country code, e.g. "+1 (510) 123-4567", "15101234567", "1 510-123-4567".
  • formatOnInput (true): auto-format the number as it is typed into the text input, as with a cell phone dialer. Valid values are true and false (no quotation marks).
  • outputFormat ('local'): how to format the valid phone number for output upon successful validation. Accepted values are local, itnl, e164, or a two-digit country code. A summary of these options follows:
    • local: format the number as it would be dialed from within the specified country, e.g. "(510) 123-4567"
    • itnl: format the number for international dialing, e.g. "+1 510-123-4567"
    • e164: format the number in international E164 format. e.g. "+15101234567"
    • CH, CA, FR, etc: format the number to be dialed from the country specified by a two-digit country code. If we were validating US numbers and used outputFormat CH, the output would be formatted for dialing a US number from Switzerland, e.g. "00 1 510-123-4567"

 

Text Validators

alpha
Requires only letters, e.g., "ABCabc"
<cml:text label="Enter name here" validates="alpha"/>
alphanum
Allows only numbers and letters, e.g., "ahfd723nd"
<cml:text label="Enter text and numbers" validates="required alphanum" />
date
Requires a date in MM/DD/YYYY format, e.g., "01/21/2010"
<cml:text label="Enter date here" validates="required date"/>
minLength and maxLength
Constrain the minimum or maximum number of characters allowed in the user's response. Note these validators can be used on their own or with other validators.
<cml:text label="4 or more characters" validates="minLength:4"/>
<cml:text label="32 or fewer characters" validates="maxLength:32"/>
When using these validators, the character count is displayed above the text box while the contributor is working, and the contributor will receive an error on submission if the validator is triggered by their input.

rangeLength

Ensures that the user's character input is within a given length range. Note that the values are inclusive.
<cml:text label="5 to 32 characters long" validates="rangeLength:{min:5,max:32}"/>
When using this validator, the character count is displayed above the text box while the contributor is working, and the contributor will receive an error on submit if their response falls outside the specified range.

wordCountMin and wordCountMax

Used to check that contributors are submitting the right amount of words. A word is defined as any text delimited by whitespace. Note these can be used with other validators, or on their own.

In this example, the text input will require at least 3 characters and no more than 10 characters in length:

<cml:text label="Enter some text" validates="required wordCountMin:3 wordCountMax:10" />

When using these validators, the word count is displayed above the text box while the contributor is working, and the contributor will receive an error on submit if their response falls outside the specified range.

currencyDollar
Allows only a dollar amount, e.g., "$153.40"
<cml:text label="Enter dollar amounts here" validates="required currencyDollar" />
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']"/>
regex
Allows you to validate contributor 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+" />
<!-- Regular expression for any alphanumeric characters and spaces. Passes: "AI is neat" --> 
<cml:text label="Input text here" validates="regex" data-validates-regex="^[A-Za-z\d\s]+$" />
<!-- 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 contributor input.--> 
<cml:text label="Consonant" validates="regex:'nomatch'" data-validates-regex="^[aeiouy]$"

Learn regular expressions with simple, interactive examples online at RegExOne.com

When writing regex for test question answer follow the Regular Expression Rules: 

The "^" means 'must start with'

The ".*" means 0 or more instances of any character

The ".+" means 1 or more instances of any character

The "$" means 'must end with'

 

Web Validators

email
Requires a valid-looking email address, e.g., "bob@example.com"
<cml:text label="Enter email here" validates="required email" />
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 test question creation but also submits the user's original input. The normalization includes removing "www.", 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, Ask, Lycos, and AOL Search.)
  • domainonly - Strips the entry of everything except the domain.
Examples:
<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}_contributor_input - the raw contributor 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 contributor's input.
<cml:text label="Enter image URL here" validates="required urlImage" />

Address Validators

stateAbbr
Requires a valid US state abbreviation, e.g., "CA", "NY"
<cml:text label="Enter state abbreviation here" validates="required stateAbbr" />
zipcode
Requires a valid US zip code, e.g., "94103"
<cml:text label="Enter US zipcode here" validates="required zipcode" />
frAddress
Requires a valid address and returns French address components. The French address validator does not enforce a level of specificity in the address. (However, this can still be enforced via Test Questions). 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 contributors from entering addresses from other countries. Use Test Questions to ensure that contributors 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}_contributorInput - raw contributor input (before normalization)
  • {fieldname}_street - street address (eg. "123 Rue de Bercy")
  • {fieldname}_buildingLabel - building/unit label (eg. "Suite", "Unit")
  • {fieldname}_buildingNumber - building/unit number (eg. "A", "1C")
  • {fieldname}_city - town / city (eg. "Paris")
  • {fieldname}_postcode - postal code (eg. "75012")
  • {fieldname}_country - country (eg. "France")
Example:
<cml:text label="Enter French address here" validates="required frAddress" />
ukAddress
Requires a valid address and returns UK address components. The UK address validator does not enforce a level of specificity in the address. (However, this can still be enforced via Test Questions). 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 contributors from entering addresses from other countries. Use Test Questions to ensure that contributors 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}_contributorInput - raw contributor input (before normalization)
  • {fieldname}_route - street address (eg. "123 Brookdale")
  • {fieldname}_buildingLabel - building/unit label (eg. "Suite", "Unit")
  • {fieldname}_buildingNumber - 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")
Example:
<cml:text label="Enter state UK address here" validates="required ukAddress" />
clicked and validates-clicked
Requires the URL link or button to be clicked before submitting. This ensures that the contributor has visited the link provided.
This validator is applied to cml:html and the a tag.
<cml:html class="clicked">
<a class="clicked validates-clicked btn btn-info" href="{{link}}">Info Page</a>
</cml:html>

Special Validators

clean
Cleans the contributor's input. The contributor 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.
Example:
<cml:text label="Please enter the correct location in 2-letter format." 
validates="required maxLength:2 clean:['uppercase']" />
In this example, the validator will check:
  • 1. 'required' - that the field is not blank
  • 2. 'maxLength:2' - that the field only contains 2 characters (i.e. UK)
  • 3. 'clean:['uppercase','whitespace']' - "cleans" the answer, making it uppercase
You may define multiple cleaners under one clean validator.
In this example, the validator will "clean" the answer, making it lowercase and removing any whitespaces:
<cml:text label="Enter text here" validates="clean:['lowercase','whitespace']" />
user_agent
    This simply sets the input's value to the contributor'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:hidden label="Some text" validates="required user_agent" />

 

Note: For more validators using Machine Learning Assisted Text Utterance Collection, please see the following articles:


Was this article helpful?
5 out of 7 found this helpful


Have more questions? Submit a request
Powered by Zendesk