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 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, 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.
ss-required
Unlike required validation (described above), which verifies a contributor has submitted an answer by using the Javascript in your job, ss-required validation verifies the answer has reached the server. For more on how and when to use ss-required, please take a look at this article.
 

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 contributor 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}"/>
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"
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']"/>
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: "-123" --> 
<cml:text label="Input text here" validates="regex" data-validates-regex="^[A-Za-z\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

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 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.

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 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")
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 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")
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.
Examples:
<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']' - 'cleans' the answer, making it uppercase
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.

Was this article helpful?
0 out of 0 found this helpful


Have more questions? Submit a request
Powered by Zendesk