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

* Comments
==========
        <!--# Comments are denoted like this #-->
        <!--# diesis at the beginning, diesis at the end #-->
        <!--#
                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.
        --->


* <RSVars> elements (Recordset Variables)
==========================================
        <RSVars RS="rsID" row="1"/>

        <!---
                This element declares several variables at once. Their names are
                the     names of the fields from the specified recordset. Their values
                are calculated from the values of the specified row of the recordset.
                They are calculated the same way as the value of the <Var> elements.

                In the case of the <Repeat> element, such a declaration is done by
                default for the current row of the iteration over the recordset and
                it is not necessary to do it explicitely.
        --->


* 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.
        --->



* Recordsets with a specified connection (long-term objective)
===============================================================
        <Recordset ID="rsID">
                <Query> select {{R_NAME}} from table </Query>
                <Connection>
                        <Server>192.168.1.114</Server>
                        <Port>1234</Port>
                        <Username>db_user</Username>
                        <Password>passwd</Password>
                        <Database>db_name</Database>
                </Connection>
        </Recordset>

        <!---
                If we want to use another connection, then we should specify it.
                The elements used in the example above are subject to be discussed
                and refined (both their names and their conntents).
        --->


* Static recordsets (long-term objective)
==========================================
        <Recordset ID="rsID">
                <Table>
                        <THead>
                                <Column>field1</Column>
                                <Column>field2</Column>
                        </THead>
                        <TBody>
                                <TRow>
                                        <TData>val11</TData>
                                        <TData>val12</TData>
                                </TRow>
                                <TRow>
                                        <TData>val21</TData>
                                        <TData>val22</TData>
                                </TRow>
                                <TRow>
                                        <TData>val31</TData>
                                        <TData>val32</TData>
                                </TRow>
                        </TBody>
                </Table>
        </Recordset>

        <!---
                We can also specify a static recordset (not filled by
                a query), like in the example above. The names of the
                elements used in the example above are subject to be
                discussed and refined.
        --->

