Draft Specification for GrazrScript 1.0

Effective: 3/19/07

Overview

This specification describes the GrazrScript language, a product of Grazr Corp. (http://grazr.com). GrazrScript is used for the display and manipulation of data in various formats, including: RSS, RDF, Atom, and OPML. Programs written in GrazrScript run in the Grazr client, but may also run in any product that is compatible with this language specification. For details on creating GrazrScript compatible products, see the copyright section at the end of this document.

GrazrScript is an extension of the OPML 2.0 specification (http://www.opml.org/spec2). As required by that document, GrazrScript's extensions are implemented in the form of a new namespace, indicated with the prefix "grazr:". No changes have been made to the underlying OPML 2.0 format. In addition to conforming to this specification, valid GrazrScript programs must be valid OPML 2.0 files.

GrazrScript is also based on the XML 1.0 specification (http://www.w3.org/TR/REC-xml/). Valid GrazrScript programs must be valid XML 1.0 files.

This specification is a draft and is likely to change before it is considered final. To participate in discussions of GrazrScript's future, please visit the Grazr Corp. forum (http://forums.grazr.com).

The purpose of this specification is to list the syntax of the GrazrScript language as clearly as possible. It is not meant to teach the use of the language. The GrazrScript Tutorial is available (http://docs.grazr.com/script/tutorial) as a training tool.

This document may be freely copied and republished, but it may not be modified in any way. The most current version of this document can always be found at http://docs.grazr.com/script/spec/1.0.

Sections of a GrazrScript Program

A GrazrScript program is divided into 4 sections: header, form, template, and result. The header must appear at the top of the file. The remaining 3 sections must be placed within the body of the OPML file. Here is a sample GrazrScript program that retrieves a feed from Google News based on user input.

Principle of Operation

GrazrScript is based on the principle of accepting input from an HTML form, and substituting that form's data into URLs that retrieve data from remote servers. The retrieved data is then displayed as a feed or outline. Form fields are represented within the template section using a field template as follows: %field_name%. For example, a form field called subject would be represented in the template as %subject%.

The basic functions of a GrazrScript program follow three phases:

Form Display: When a GrazrScript program first loads, the form is displayed and the result node appears with no data beneath it.
Template Processing: When the form is filled out and the submit button is clicked, the data from the form fields is substituted in place of the matching fields in the template section. If the template is written using the inline format, the template's URL is retrieved to obtain the resulting data from a remote server. If the template uses the outline format, the substitution is made using the field values, and the substituted template is appended to the result section.
Result Display: The results of the template processing are appended to the result message and displayed.

The template processing and result display steps are repeated each time the form's submit button is pressed.

Details of the Header section

The header section makes up the first 2 lines of a GrazrScript program, and takes the following form:

<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0" xmlns:grazr="http://docs.grazr.com/script/spec/1.0">

Details of the Form Section

The form section is started with the grazr:form tag. Each form must be assigned a name whose value matches its corresponding template and result sections.The complete format for the opening form tag is:

<grazr:form name="[form_name]">

The form section is closed with the following version of the grazr:form tag:

</grazr:form>

Between the form opening and closing tags any valid XHTML can be used. All XHTML form tags are supported. In addition, CSS style tags may be used to control the appearance of the form.

A sample form would be entered as follows:

<grazr:form name="newsform">
  News Search <input type="text" name="subject" />
  <input type="submit" value="Enter" /> 
</grazr:form>

Form Field Validation

The form section may contain field validation rules using the grazr:rule tag. This must appear between the form open and close tags.

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

Field validation is performed when a form is submitted. If any form rules are violated, the template section is not executed, and a default error message is displayed. Any number of rule tags may appear in a form section and may be associated with any subset of the available form fields. Rule tags may appear in any order within the form section, and may be placed before or after the associated field definitions. When the form is submitted, processing is done in the order in which fields appear in the form. If multiple rules are violated, only the first error is reported to the user.

GrazrScript has a built-in error message for each rule, but a custom error message may be included with the definition of the field rule.

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

Here is a sample form section with a rule requiring user entry:

<grazr:form name="newsform">
  News Search <input type="text" name="subject" />
  <input type="submit" value="Enter" /> 
  <grazr:rule field="subject" required="true" text="Please enter a query" />
</grazr:form>

GrazrScript currently provides the following field rules. They can be used in any combination, but the max and min limits are only obeyed if the numeric rule for that field is also set to true or 1.

Rule	Values
max	[maximum value]
min	[minimum value]
numeric	true\|1, false\|0
required	true\|1, false\|0

Each field can have multiple rules, and the rules can be entered in a single tag or spread across multiple tags.

<grazr:rule field="amount" numeric="true" max="100" min="-100" />

<grazr:rule field="amount" numeric="true" />
<grazr:rule field="amount" max="100" />
<grazr:rule field="amount" min="-100" />

Error messages can be applied to multiple rules in a single tag, or they can be used with separate rule tags to give each rule its own message.

<grazr:rule field="amount" numeric="true" max="100" min="-100" text="Invalid entry" />

<grazr:rule field="amount" numeric="true" text="Entry must be numeric />
<grazr:rule field="amount" max="100" text="Maximum value is 100" />
<grazr:rule field="amount" min="-100" text="Minimum value is -100" />

GrazrScript has a special field name of _default that can be used to apply one or more rules to all the fields in a form.

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

A _default rule can be overridden for individual fields.

<grazr:rule field="_default" required="true" text="Entry is required" />
<grazr:rule field="subject" required="false" />

Details of the Template Section

There are two possible formats for the template section: inline and outline. The inline format is used to perform substitutions in a single RSS feed URL, while the outline format can be used with any number of OPML nodes of any type.

An inline template is given this name, because the URL is placed directly in the grazr:formtemplate tag using the file attribute:

<grazr:formtemplate name="[form_name]" file="[URL]" />

Any number of form fields can be substituted within the URL using the %field_name% format. When the form is submitted, GrazrScript substitutes the form fields in the URL, and then retrieves the matching feed from the remote server. The retrieved data is displayed beneath the result node that has a matching form name. Here is an example of an inline template for Google News:

<grazr:formtemplate name="newsform"
    file="http://news.google.com/news?q=%subject%&amp;output=rss" />

For ease in reading, an inline template can be written across two lines.

Outline templates use a block format, with an opening and closing tag. The opening tag is written as:

<grazr:formtemplate name="[form_name]">

The closing tag is:

</grazr:formtemplate>

Any number of any type of OPML nodes can be placed between the opening and closing template tags. In fact, a multi-level outline structure can be placed in an outline template. Form fields can be substituted both within the URL and the text attribute of an OPML node. Here is an example of an outline template with 3 RSS nodes:

<grazr:formtemplate name="newsform">
  <outline type="rss" text="Google News" 
    xmlUrl="http://news.google.com/news?q=%subject%&amp;output=rss" /> 
  <outline type="rss" text="MSN.com" 
    xmlUrl="http://search.msn.com/news/results.aspx?q=%subject%&amp;format=rss&amp;FORM=RSNR" />
  <outline type="rss" text="Yahoo.com" 
    xmlUrl="http://news.search.yahoo.com/news/rss?ei=UTF-8&amp;p=%subject%" /> 
</grazr:formtemplate>

The OPML syntax uses the xmlUrl attribute for the URL value, which is obviously different from the file attribute in an inline template. Another difference between an outline template and an inline template, is that only substitution is done with the outline template. The resulting substituted URLs and text are then displayed beneath the result node. The data is not retrieved until the user clicks an individual node in the result.

Both types of templates must be given a name attribute whose value matches its corresponding form and result.

Embedding JavaScript within the Template Section

GrazrScript allows the embedding of JavaScript code using a model that is analogous to embedding JavaScript within HTML. A block of JavaScript code may be placed within the template section using an opening tag of:

<grazr:script>

The script block is closed with the tag:

</grazr:script>

Some of the JavaScript code may be considered invalid XML, and therefore invalid OPML. To make sure the resulting GrazrScript application is valid XML, it is recommended that all script blocks start and end with XML comment markers. The basic format for a complete script block is thus:

<grazr:script>
<!--
[JavaScript code]
-->
</grazr:script>

Within the script block all of core JavaScript 1.5 is available. The JavaScript is run on the GrazrScript server, so there is no access to browser functionality. JavaScript integration is done by calling the Mozilla intepreter, so complete details on the available JavaScript commands are in Mozilla's documentation.

There is no limit on the number of script blocks allowed within a template section, and the entire template section is scoped as a global namespace. Memory variables created in one script block are available in a separate script block in the same template. Each template section is a separate namespace, so there is no sharing of memory variables between templates. Form fields and memory variables in script blocks are interchangeable, so a form field may be tested and modified within a script block, and then used for substitution in OPML nodes.

Here is a simple use of a script block to test and replace the value of a form field before it is used in a substitution:

<grazr:form name="teamform">    
  <strong>Baseball Search</strong>      
  <input type="submit" value="Ok" /><br />    
  Favorite team: <select name="team">    
  <option value="Red Sox">Red Sox</option>          
  <option value="Yankees">Yankees</option>          
  </select>    
  Choose another team: <input type="text" name="other" />  
</grazr:form>  
<grazr:formtemplate name="teamform">  
  <grazr:script><!--    
  if (other != "") {
    team=other;    }   
  --></grazr:script>  
  <outline type="rss" text="%team% News"     
    xmlUrl="http://news.google.com?q=baseball+%team%&output=rss" />  
</grazr:formtemplate>  
<grazr:formresult text="Latest stories:" name="teamform" />

This specification only attempts to document the core functionality of GrazrScript. Extensions to the JavaScript commands available in script blocks, such as custom objects, will be added in the future, but will not be documented in this spec. More complete documentation of these extensions is available in the GrazrScript tutorial.

Details of the Result Section

The result section is entered with the grazr:formresult tag. Each result section must be given a name attribute whose value matches its corresponding form and template. The simplest format is:

<grazr:formresult name="[form_name]" />

When this format is used, a default message is displayed of "Search results:". An optional text attribute may be used to display a different message:

<grazr:formresult text="[message]" name="[form_name]" />

Before the form is submitted, the result message appears with its own icon. After the form is submitted, the data returned from the remote server is appended beneath the result message. If the form is submitted again, the previous results are erased and replaced with the new result data.

Here is a typical use of the result tag:

<grazr:formresult text="Google News:" name="newsform" />

Additonal Notes

1. Any number of forms may appear in a GrazrScript program. Each form must have a matching template and result section. The form, template and result sections are related through a common value in the name attribute.

2. The form, template and result sections do not have to be contiguous. They may be distributed freely within an OPML file.

3. The form, template, and result sections do not have to appear in any specific order within the file. For example, the result section may appear above the form.

4. The form, template, and result sections do not have to appear at the top level of an OPML outline. They may be freely nested within other outline nodes. If a form section is nested within an outline, it will not be displayed until its parent node is expanded. If the result section is nested within an outline, the result data will not be displayed until its parent node is expanded.

5. GrazrScript programs must be valid XML, which means that all uses of & must be written as the matching entity &.

6. There is no required extension for a GrazrScript file, although .xml is a common convention.

7. Form names, field names, tags, and attribute names are all case sensitive.

8. Form names and field names may not contain spaces.

9. Indentation is not required within an OPML file, but is recommended for increased readability.

Copyright and disclaimer

Grazr Corp. is referred to in the following as "the Company."

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works.

This document may not be modified in any way, such as by removing the copyright notice or references to the Company or other organizations. Further, while these copyright restrictions apply to the written GrazrScript specification, no claim of ownership is made by the Company to the format it describes. Any party may, for commercial or non-commercial purposes, implement this format without royalty or license fee to the Company. The limited permissions granted herein are perpetual and will not be revoked by the Company or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE COMPANY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.