Yeast Templates Basic concepts

Including the engine

To develop a Yeast Template you only need to include the Yeast engine in the template.

<script type="text/javascript" src="yst.js"></script>

Developing the template

From the point of view of designers, working with Yeast Templates involves creating the HTML page by focusing only on the navigation and look and feel. Designers must identify the dynamic part of the page (in the example of the above figure this dynamic part is made up of a user's name and a table of items). Then, they must define the variables that will hold the dynamic data within a script section that must be marked with the attribute yst with the value model. Variables are given a name and assigned a test value to them. Variables can be simple (of any JavaScript type), like userName in the example, or compound, like items in the example (an array of objects). These variables make up the so-called model section of the designer's model.

A key point is that the designer is free to structure its model as he wants. This is important for us because, up to certain extent, we do not want to force the designer to learn any particular syntax or to apply a unique way of doing things. E.g.: in the example of the above figure, object literal notation is used to populate the items array, but there exist other possibilities, such us to use constructor functions of an hypothetic JavaScript Item class, or to use two arrays of simple data (one for names and another for prices). Sometimes the designer will have to declare auxiliary data structures, e.g. constructor functions. This is the init section of the designer's model. For example, the previous designer's model would have been defined as follows. First the init section:

<script>
  function Item(name, price) {
    this.name = name;
    this.price = price;
  }
</script>

and then the model section

<script yst="model">
  items = [new Item('Umbrella',1), new Item('Suitcase',18)];
</script>

As we have commented, another possibility for the designer’s model is to use two arrays:

<script yst="model">
  names = ['Umbrella','Suitcase'];
  prices = [1, 18];
</script>

In this case the Yeast code in the template must be different:

<table border="1">
  <tr yst="apply" ystSet="names"><td>$e$</td><td>$prices[i]$</td></tr>
</table>

Therefore, the way the designer structures its designer's model determines the way the template must be developed. But all these decisions are taken by the same person: the designer. The template is self-contained. It does not depend on any application model detail, as it happens in other template systems. This is a consequence of the double model approach.

Yeast expressions

Wherever designers want to insert a data value, they place the name of the variable that holds the value between a couple of $ symbols (e.g., $userName$). A variable reference can appear alone or as part of a JavaScript expression, like in $price*0.9$. Therefore, designers have all the JavaScript power at their disposal, without the cost of learning a new programming language (JavaScript is usually familiar to HTML designers). Yeast expressions may appear as part of the value of HTML elements or attributes.

Yeast non-standard attributes

The way Yeast expressions are processed is determined by Yeast attributes. These attributes contain instructions for the template engine.

The most important Yeast attribute is yst indeed. Its value specifies the type of processing that the element that carries it must undergo. We call HTML elements marked with this Yeast attribute Yeast elements.

There are eight possible values for the yst attribute, which cover evaluations, conditionals, iterations and sub-template inclusions:

  • value: the Yeast expressions inserted in the Yeast element, or any of its children, must be evaluated and its value must replace the expression.
  • if: the Yeast element will be processed only if the value of the conditional expression contained in an auxiliary Yeast attribute named ystTest is evaluated to true. If the condition is evaluated to false, the Yeast element is removed from the final document. All Yeast expressions are evaluated as in value.
  • apply: the Yeast element must be replicated for each one of the values contained in the array specified in an auxiliary Yeast attribute named ystSet, or so many times as specified in the value of the ystUpTo attribute. All Yeast expressions are also evaluated as in value. There are three implicit variables associated to the underlying iteration process that can be used in the expressions: i, the iteration index, e the iteration value, and values, the iterated set.
  • compApply: like apply, but for a group of Yeast related elements. It also uses the auxiliary Yeast attributes ystSet (or ystUpTo) and ystTest. For each set value, all the Yeast elements in the compApply group are evaluated. Only those whose ystTest expression evaluates to true are included in the final result.
  • declare: used to define Yeast elements that act as sub-templates in the template. A sub-template is once declared, but may be many times included in the document. Yeast sub-templates are assigned an identifier and they can have invocation parameters.
  • include: used to include a certain template specified by its identifier. Values for the sub-template parameters must be provided.
  • ignore: to mark Yeast elements that are used as mock-ups during graphical design. These elements must not belong to the final HTML document, because they were used as an example to clarify the design.
  • ajax (or live): it is used to mark a certain element that must be reprocessed, e.g. as response to an AJAX interaction. In this interaction the document is supposed to get form the server new model values that alter the rendering of the element. You can read more about AJAX and Yeast Templates in the Yeast AJAX section.

In the samples of the demo section you can see how these Yeast attributes are used to build tables, forms, and so on.