Specifications for XHTML templates
==================================

* Comments
==========
  <!--# Comments are denoted like this #-->
  <!--#
    Such comments are not included
    in the XHTML file that is generated.
  #-->
  <!--
    Usual XHTML comments (like this one) are passed to
    the XHTML file that is generated from the template.
  -->


* Include elements
==================
  <Include file="{{MSG_BOX}}"/>

  <!---
    The <Include> element is used to include in templates
    parts that are the same in many templates. It also
    provides flexibility in the sense that the file that
    will be included may be a variable, so different files
    may be included in different cases.

    The file that is included will be processed as if it were
    in the place of the <Include> element (so it may contain
    elements, variables, etc).
  --->


* Repeat elements
=================
  <Repeat RS="art">
    <!--- IfEmpty is included in XHTML in case that recordset specified has no records --->
    <IfEmpty>
      <tr>
        <td>No articles found!</td>
      </tr>
    </IfEmpty>

    <!--- Here comes the part that is reapeated for each record in the recordset --->
    <tr>
      <td> {{TI}} </td>
      <td> {{AU}} </td>
      . . .
    </tr>
  </Repeat>

  <!---
    The <Repeat> element is connected with a recordset by the attribute
    "RS". Its content is processed for each row of the recordset. Before
    processing the content for a certan row, all the fields of the recordset
    are     declared as variables with values taken from the current row.

    In case that the recordset is empty, then the element <IfEmpty> is
    processed instead. (Subject to be discussed).

    Subject to be discussed: should we also include <Header> and <Footer>
    elements?
  --->


* <If> element
===============
  <If condition="!{{PUBLIC_LIBRARY}}">
    <!--- MyLibrary part comes here --->
    <!--- . . . . . . . . . . . . . --->
  </If>

  <!---
    The content of the <If> element is processed conditionally,
    if the value of the attribute "condition" is true, then it
    is processed, otherwise it is not processed.

    The value of the condition is calculated as a PHP expression
    (after the template variables are replaced).
  --->


* <Recordset> elements
=======================
  <Recordset ID="rsID">
    <Query> select {{R_NAME}} from table </Query>
  </Recordset>

  <!---
    Each recordset has a unique ID. Later, when we use
    this recordset (e.g. in a <Repeat> element) we refer
    to it by this ID. It also has a <Query> element, which
    is executed using the default database connection.
  --->


* Recordsets that are displayed over several pages
===================================================
  <Recordset ID="art" RowsPerPage="10">
    <Query>{{ART_QUERY}}</Query>
  </Recordset>
  <!---
    Recordsets that have a RowsPerPage attribute are
    recordsets that are displayed over several pages.
    In this case some additional variables are declared
    which show which records are being displayed, how many
    pages are there, and at which page we are currently.
    These variables can be used anywhere in the template.

    Such variables are: {{art_PrevPage}}, {{art_CurrentPage}},
    {{art_NextPage}}, {{art_NrPages}}, {{art_FirstRecord}},
    {{art_LastRecord}}, {{art_NrRecords}}, etc. (their names
    are generated using the id of the recordset).

    Some of them are also saved as session variables. In our
    example, {{art_CurrentPage}} is a session variable and is passed
    from this page to the next one.
  --->


* <Var> elements
=================
  <Var name="MSG_SEARCH">"Results of search for: {{SEARCH_TERM}}"</Var>
  <Var name="ROW_COLOR">($Cnt%2 ? 'class="tabgrey"' : 'class="tabwhite"')</Var>

  <!---
    <Var> elements declare variables that can be used anywhere in the
    template in the current scope and in the scopes inside it. They
    are identified by their name, and their value is calculated using
    their content. The value of a variable is calculated in this way:
    -first, any template variable inside them is found and replaced,
    -second, the resulting string is evaluated as a PHP expression,
    -finally, the resulting value is assigned to the variable.
    (This way of evaluation is subject to be discussed and refined.)

    A variable is evaluated at the time that it is processed, so that
    if a variable is inside a <Repeat> element, then it may have different
    values for different iterations.

    The scopes of the variables are determined by the elements <Repeat>,
    <If>, etc. (each of these elements defines a new scope). If two
    variables have the same name, then the one in the closer scope is
    used. If they are both in the same scope, then the one defined later
    overrides the other.
  --->


* Template variables
=====================
  <!---
    Anywhere in XML where we can put character data,
    we can also put {{variables}}, which are replaced
    by their string values at the time of template
    processing and convertion to XHTML.

    To find the value of a variable:
    -The current scope is searched for it.
    -If it is not found, then the scope above it is searched,
      and so on until it is found.
    -If it is not found in any scope, then session variables
      are searched for it.
    -If it not found among session variables, then global variables
      of PHP are searched for it.
    -If it still is not found then its name is taken as its value
      (e.g. {{var1}} is replaced by "var1").

    The order of search is subject to be discussed and refined.
  --->