RTML Tutorial > How to read templates

How to read templates

The built-in templates

Yahoo! Store comes with built-in templates. Before we go into changing or creating new templates it is helpful to understand the built-in ones. There are a few dozen such built-in templates, and because there are no instructions as to what these templates do, it can be a little intimidating at first to try to tackle them. Fortunately you don’t need to understand every single template before you can make some impressive changes or create your own templates.

If your store uses editor V2.0, you can click "Templates", and then look at the home. template for example. That template generates the home page. Without much RTML knowledge, you will be able to see some familiar pieces in that template. It starts out like this:

HEAD 
  WHEN NONEMPTY @keywords
    META name "Keywords"
         content @keywords
  TITLE IF test NONEMPTY @page-title
           then @page-title
           else @title
  TEXT @head-tags

So, as you may have guessed, the above piece is responsible for generating the <head>...</head> section of the home page. It creates the keywords meta tag, then adds the <title>...</title> tag, finally, it outputs the contents of the head-tags variable. The rest of the template may seem a bit foreign, but it too is full of things you may recognize, such as the BODY tag, top or side navigation bar generation, etc.

If your store is based on editor V3.0, click on "Templates" and then look at the storetemplate. template. This template is responsible for generating all the pages in your store. Although this template looks different than version 2's home. template for example, here too, you will come across some familiar pieces. There is a HEAD section here is well, for instance:

        HEAD 
          TITLE IF test NONEMPTY @page-title
                   then @page-title
                   else IF test NONEMPTY @name
                           then @name
                           else @title
          WHEN NONEMPTY @description
            META name "Description"
                 content @description
          WHEN NONEMPTY @keywords
            META name "Keywords"
                 content @keywords
          CALL :css.
          TEXT @head-tags

Here, too, you see the <title>...</title> tag being generated, then a description and keyword meta tag, then there is a call to the css. template (to insert links to the built-in CSS style sheets), and finally to output the head-tags variable.

As we said earlier, RTML templates are evaluated from top to bottom. You can see how the store properties and variables are used in the templates – look out for the “@” in front of property names. You will also come across constants – those with a “:” colon in front; these usually refer to the value from a dropdown list of a variable, or pass an attribute to a RTML expression (such as left, right or center).

Templates are evaluated within the context of page (or object) in the store. Every page in Yahoo! Store has a unique id (which is also the name of the published HTML file). So when you see something like TEXT @name, this means to output the name of the current page. It's the same template, but the output will be different from page to page. Within a template it is possible to change the context and switch to another id, or in other words, to impersonate a different page and use its properties. This is a very important concept because it allows you to pull information from other pages automatically.

Another important characteristics of RTML is nesting. You will see that some expressions are indented within others. Unlike in other programming languages, where indentation is typically used to make code easier to read, in RTML indentation is extremely important. Here, nesting defines the scope of an instruction. Take the following example:

TABLE border 0				
      cellspacing 0
      cellpadding 0
      width wid	
  TABLE-ROW valign :top
    TABLE-CELL
      ORDER-FORM

This will generate the following HTML:

<table border=0 cellspacing=0 cellpadding=0 width=xyz>
<tr>
<td>
...
</td>
</tr>
</table>

whereas this:

TABLE border 0
      cellspacing 0
      cellpadding 0
      width wid
TABLE-ROW valign :top
TABLE-CELL
      ORDER-FORM

generates the following incorrect HTML:

<table border=0 cellspacing=0 cellpadding=0 width=xyz></table>
<tr></tr>
<td>
...
</td>

Calling other templates

You can see very quickly when and where other templates are called. Look out for the “CALL” expression and the red rectangle next to it. The rectangle hyperlinks to the called template.

The same template can be called by several other templates. Take for example the side-nav. template. The side-nav. template, as is implied by its name, puts together the side navigation. It makes sense that the side-nav navigation is called by several templates because the side navigation has to be displayed on most pages.

You cannot edit the in-built templates. You can only create your own templates from scratch or copy the built-in templates. This is also your safeguard: if you mess up your new templates you know you can always revert back to the built-in templates.

What our customers say: