GrazrScript Tutorial

Field validation

Some of the URLs that you will use with field substitution have restrictions on the type of data that they will accept, so GrazrScript has a rule tag that lets you test the contents of form fields before they are substituted within a template. The validation rules created by this tag are tested after the form is submitted. If the user's data conforms to the validation rules, then the normal substitution is performed. If any of the entered data fails to pass the rules, then an error message is displayed and the form template is not run. The key is that this is an all or nothing process. All validation rules for all fields must be met before substitution is done.

Basic syntax

The simplest version of the rule tag takes the following form:

<grazr:rule field="[field_name]" [rule]="[value]" />

Here is a version of the familiar news application with a required rule added to reject blank user input. Note that the rule tag must be placed between the open and closing form tags.

http://docs.grazr.com/script/tutorial/newsrequired.xml

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0" xmlns:grazr="http://docs.grazr.com/script/spec/1.0">
<head>
  <title>News Search</title>
</head>
<body>
  <grazr:form name="newsform">
    News Search <input type="text" name="subject" /> 
    <input type="submit" value="Submit" /> 
    <grazr:rule field="subject" required="true" />
  </grazr:form>
  <grazr:formtemplate name="newsform"
    file="http://news.google.com/news?q=%subject%&amp;output=rss" />
  <grazr:formresult text="Google News:" name="newsform" />
</body>
</opml>

Let's examine this first rule tag more closely.

<grazr:rule field="subject" required="true"  />

This tag sets the value of the required rule to true for the subject field. The required rule can have several possible values. Setting it to true or 1 means that the field may not be blank, while values of false or 0 do allow blanks. The default value of the required rule is false, so you don't have to enter this rule if you don't need the user to fill in the field.

Custom error message

When the required rule fails, Grazr displays a default message: "Error: Field is required: [field name]." You can also add an error message to a rule with this syntax:

<grazr:rule field="[field_name]" [rule]="[value]" text="[Error message]" />

http://docs.grazr.com/script/tutorial/newsrequired2.xml

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0" xmlns:grazr="http://docs.grazr.com/script/spec/1.0">
<head>
  <title>News Search</title>
</head>
<body>
  <grazr:form name="newsform">
    News Search <input type="text" name="subject" /> 
    <input type="submit" value="Submit" /> 
    <grazr:rule field="subject" required="true" 
      text="Please enter keywords for a news search" />
  </grazr:form>
  <grazr:formtemplate name="newsform"
    file="http://news.google.com/news?q=%subject%&amp;output=rss" />
  <grazr:formresult text="Google News:" name="newsform" />
</body>
</opml>

Additional rules

numeric - When set to true or 1, this rule only accepts valid numeric values. You can enter decimal points using the American style period or the European style comma. A minus sign in front of the number is also acceptable. The default values of this rule are false or 0, which accept any characters.
```
<grazr:rule field="subject" numeric="true"  />
```
max - This restricts a field value to an upper numeric limit. The max rule is only applied if the field is also given a numeric rule with a value of true.
```
<grazr:rule field="subject" numeric="true" max="100" />
```
min - This restricts a field value to a lower numeric limit. Just as with max, the min rule is only applied if the field is also given a numeric rule of true.
```
<grazr:rule field="subject" numeric="true" min="0" />
```

Multiple rules per field

As shown by the examples for max and min above, you can apply multiple rules to a single field. This can be done with a single rule tag, or by splitting up the rules across multiple tags. Both of the following code snippets will give the same result:

<grazr:rule field="subject" numeric="true" max="100" min="0" />

<grazr:rule field="subject" numeric="true" />
<grazr:rule field="subject" max="100" />
<grazr:rule field="subject" min="0" />

Here is an application that applies all the ideas we've seen so far about rules. Since the goal is to just test the rules, the template section simply prints out the results in a text node.

http://docs.grazr.com/script/tutorial/validation.xml

<?xml version="1.0" encoding="UTF-8"?>
<opml version="1.1" xmlns:grazr="http://docs.grazr.com/script/spec/1.0">
<head>
  <title>Form Processing</title>
</head>
<body>
  <grazr:form name="testform">
    Required: <input type="text" name="required_test" /> <br />
    Numeric: <input type="text" name="numeric_test" /> <br />
    Min (0): <input type="text" name="min_test" /> <br />
    Max (10): <input type="text" name="max_test" /> <br />
    Multiple Test: <input type="text" name="multiple_test" /> <br /> 	
    <input type="submit" value="Submit" /> 
    <grazr:rule field="required_test" required="true" />
    <grazr:rule field="numeric_test" numeric="true" />
    <grazr:rule field="min_test" numeric="true" min="0" />
    <grazr:rule field="max_test" numeric="true" max="10" />
    <grazr:rule field="multiple_test" required="true" numeric="true" min="0" max="10" />
  </grazr:form>

  <grazr:formtemplate name="testform">
    <outline text="Required: %required_test%" />
    <outline text="Numeric: %numeric_test%" /> 
    <outline text="Min: %min_test%" />
    <outline text="Max: %max_test%" />
    <outline text="Multiple: %multiple_test%" />
  </grazr:formtemplate>
		
  <grazr:formresult text="Test results:" name="testform" />

</body>
</opml>

Default rules

GrazrScript has a special field name of _default that applies to all fields in the current form. This allows you to set a validation rule for multiple fields with a single tag.

<grazr:rule field="_default" required="true" />

You are able to override this rule by applying different rule settings to specific fields.

http://docs.grazr.com/script/tutorial/defaultrule.xml

<?xml version="1.0" encoding="UTF-8"?>
<opml version="1.1" xmlns:grazr="http://docs.grazr.com/script/spec/1.0">
<head>
  <title>Form Processing</title>
</head>
<body>
  <grazr:form name="testform">
    Required: <input type="text" name="required_test" /> <br />
    Numeric: <input type="text" name="numeric_test" /> <br />
    Min (0): <input type="text" name="min_test" /> <br />
    Max (10): <input type="text" name="max_test" /> <br />
    Multiple Test: <input type="text" name="multiple_test" /> <br /> 	
    <input type="submit" value="Submit" /> 
    <grazr:rule field="_default" required="true" />
    <grazr:rule field="numeric_test" numeric="true" />
    <grazr:rule field="min_test" required="false" numeric="true" min="0" />
    <grazr:rule field="max_test" required="false" numeric="true" max="10" />
    <grazr:rule field="multiple_test" numeric="true" min="0" max="10" />
  </grazr:form>

  <grazr:formtemplate name="testform">
    <outline text="Required: %required_test%" />
    <outline text="Numeric: %numeric_test%" /> 
    <outline text="Min: %min_test%" />
    <outline text="Max: %max_test%" />
    <outline text="Multiple: %multiple_test%" />
  </grazr:formtemplate>
		
  <grazr:formresult text="Test results:" name="testform" />

</body>
</opml>

Validation error text

Once you start using validation rules, you'll probably want to gain more control over the error messages displayed. There are a number of error text behaviors that you should keep in mind:

When a form is submitted, GrazrScript tests each field against its rules in the order that the fields appear on the form. When the first error is encountered, validation stops and the error message for that field and rule is returned. This prevents the user from being flooded with multiple error messages. So if you have a form with 5 required fields and they are all left blank, only the first field generates an error.
Substitution of user entries can be done within the error text. This allows you to repeat the invalid entry in the error message.
A field can have a separate error message for each rule. For example, if a field has both a numeric rule and a max rule, each rule can have a different message.

Here is an example that demonstrates just how much flexibility GrazrScript provides for reporting errors.

http://docs.grazr.com/script/tutorial/errortext.xml

<?xml version="1.0" encoding="UTF-8"?>
<opml version="1.1" xmlns:grazr="http://docs.grazr.com/script/spec/1.0">
<head>
  <title>Form Processing</title>
</head>
<body>
  <grazr:form name="testform">
    Required: <input type="text" name="required_test" /> <br />
    Numeric: <input type="text" name="numeric_test" /> <br />
    Min (0): <input type="text" name="min_test" /> <br />
    Max (10): <input type="text" name="max_test" /> <br />      
    Multiple Test: <input type="text" name="multiple_test" /> <br /> 
    <input type="submit" value="Submit" /> 

    <grazr:rule field="_default" text="Unable to process form" />
    <grazr:rule field="required_test" required="true" 
      text="Error: A required field may not be left blank" />
    <grazr:rule field="numeric_test" numeric="true" 
      text="Error: Only numbers allowed in Numeric field" />
    <grazr:rule field="min_test" numeric="true" 
      text="Error: Only numbers allowed in Min field" />
    <grazr:rule field="min_test" min="0" 
      text="Error (%min_test%): Minimum is zero" />
    <grazr:rule field="max_test" numeric="true" 
      text="Error: Only numbers allowed in Max field" />
    <grazr:rule field="max_test" max="10" 
      text="Error (%max_test%): Maximum is ten" />
    <grazr:rule field="multiple_test" required="true" numeric="true" min="0" max="10" />
  </grazr:form>

  <grazr:formtemplate name="testform">
    <outline text="Required: %required_test%" />
    <outline text="Numeric: %numeric_test%" /> 
    <outline text="Min: %min_test%" />
    <outline text="Max: %max_test%" />
    <outline text="Multiple: %multiple_test%" />
  </grazr:formtemplate>

  <grazr:formresult text="Test results:" name="testform" />

</body>
</opml>