GrazrScript Tutorial

Anatomy of an application

Let's look more closely at the Google News search from the first page of the tutorial. It is called news.xml, and you'll find that all of the examples in this tutorial have a .xml file extension. This extension isn't required, as Grazr will accept any text file name and extension.

http://docs.grazr.com/script/tutorial/news.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="Enter" /> 
  </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>

The basic format of a GrazrScript program is divided into the following sections:

Header

The GrazrScript language is based on the OPML format, which in turn is based on XML. Every GrazrScript file must start with the following two lines as a way of telling the world about these facts:

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

This tells any program that reads this file to follow the standards in XML 1.0 and OPML 2.0. It also says to expect additions to OPML that start with the word "grazr." The GrazrScript extensions to OPML are technically known as a namespace, because they are prefixed with a specific name. According to the XML and OPML standards, if a program doesn't know how to use a namespace, it is supposed to ignore it. This means that a GrazrScript program should work in any OPML browser as a normal OPML file, and the GrazrScript portions will not be displayed.

The second part of the header gives the file a title. This will be displayed in Grazr's title bar when the file is loaded.

<head>
  <title>News Search</title>
</head>

Body

At a minimum, the body of a GrazrScript file must contain three sections: form, template, and result. All three sections are connected by having the same value of the name attribute. You can also add any additional OPML to the file body, such as links to regular feeds, Web pages, or other OPML files.

Form

GrazrScript forms are written using standard HTML, and appear within Grazr wherever they are placed in the outline. The form section starts with the tag <grazr:form name="[name]">. You can use any name for a form, as long as it doesn't contain spaces. The ending of the form section is marked with the tag </grazr:form>. In between these two tags you can include any HTML tags used to create forms. Input fields in the form can be given any name, not including spaces.

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

Template

The template section starts with the grazr:formtemplate tag and contains the URL that should be sent to a remote server with the user's input. The URL is entered with the file attribute. Form fields are substituted into template URLs by name. In this example, the value of the field called subject is taken from the form and substituted in the template's URL. Field names that are substituted in the URL are indicated with a leading and trailing % character.

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

Result

The result section is entered with the grazr:formresult tag and shows where the results of the template's URL should appear. It contains an optional text attribute that is displayed as part of the results. The point where the results appear in Grazr is commonly called the result node, as node is the name for a line in an outline.

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

Putting it together

This page has packed in a lot of details, so let's review the working of a GrazrScript program:

When news.xml first loads, the form is displayed and the result node appears without any feed data.
When data is entered and the submit button is pressed, the user's input is substituted within the template. In this case, the value of the subject field takes the place of %subject% wherever it is found in the template.
The new URL with the user's input is retrieved from the remote data source, in this example it is Google News, and the data retrieved is displayed beneath the result node.