
Variables
==========

Variables are used in templates to insert a dynamic string in it.
Its value is not known at the time that the template is designed,
it is given by the php part of the application or by the framework
(e.g. by getting it from the DB or by calculating it according to 
a certain logic). Their value is always a string, which replaces
the variable when the template is processed by the framework.


How they are denoted
---------------------
Template variables are denoted like this: {{#var_name}}. 
'var_name' inside the curly braces may contain any character except
braces ({}) and EOL (end of line, each variable must be in one line).
Double curly braces is chosen because single curly braces sometimes 
may occur in a template, e.g. in JavaScript code. They are case 
sensitive.

If the value of a variable contains single quotes (') and we want 
them escaped (\'), then, instead of using the notation {{#var}}, 
we can use the notation {{#'var'}}. Similarly, to escape double quotes
we can use the notation {{#"var"}. This is sometimes useful when we
want to use a variable inside a JavaScript, as part of a string, 
like this: str = 'js str {{#var}} js str'. If the {{#var}} value 
contains single quotes, this would break the consistency of the string
and would generate JavaScrip error. However, if we use it like this:
str = 'js str {{#'var'}} js str', then {{#'var'}} is replaced by a string
in which single quotes have been escaped, and this doesn't break the
code.

If you don't mean something like this {{#...}} to be a variable, but
instead you want it to be displayed with double curly braces (for
example when you explain its usage, like in this manual), then a
diesis (#) can be used like this: {{##...}}, or {{#...##}}, or {{##...##}}.
Otherwise the framework will treat it as a variable and will remove
the curly braces. 


How they are declared 
----------------------
A template variable is declared in the php code of the application,
in the php code of the weboxes, in the <Var> template tag, in the
<Repeat> template element (implicitly), or gets its value from 
a session variable, from a global php variable or from a php constant
that has the same name as the {{#variable}}.

In the php code (of the application or of the weboxes) the variables
are declared using these functions:
 - WebApp::addVar(var_name, var_value)
 - WebApp::addVars(var_assoc_array)
 - WebApp::addGlobalVar(var_name, var_value)
 - WebApp::addGlobalVars(var_assoc_array)
You can also get the value of a variable, using the function:
 - WebApp::getVar(var_name)
 
A variable is declared by the <Var> element like this:
    <Var name="var_name">expression</Var>
and it adds a new variable in the current scope.
'expression' is a php expression that may contain other {{#variables}}. 
First, any {{#variable}} inside it is found and replaced, then 
the resulting string is evaluated as a PHP expression. 
For more details about <Var> elements see 'templates.txt'.

The <Repeat> element does not declare any variables explicitly, but
they are declared implicitly (by the framework). Each time that the
body of the <Repeat> is rendered for another record of the recordset,
the framework declares as variables of the current scope each field
of the current record (which contain data from the database). These 
variables can be used then in the body of the <Repeat>, and they may
have different values each time that it is repeated. 
For more details about <Repeat> elements see 'templates.txt'.

 
The scopes of the variables
----------------------------
The variables have scopes. Each of the template tags <WebBox>, 
<Repeat>, <If> etc. defines a new scope, and there is also a global
scope that contains everything in the application. A variable declared
in a certain scope, e.g. in a certain <WebBox>, can be used only inside
the template of this webox (and in the templates included to it or
inside it), outside of this webox it doesn't exist. If a variable with
the same name is declared in two different scopes that are inside 
each-other, then they are two different variables, and in the inner 
scope is used the second variable and in the outer scope is used the
first variable. If two variables with the same name are added in the
same scope then they are the same variable and the second value 
overrides the first value.

The templates are processed by the framework in this way: first they
are read, parsed and loaded in memory in certain objects and structures,
then, using this object representation of the templates, the HTML code
of the page is rendered (generated) and sent to the browser. There are
two different scope stacks corresponding to this two processes, one
is the loading stack and one is the rendering stack. So, a variable
added during the loading process, in the onParse() function of a webox
for example, is used only during the loading of this webox, and cannot
be used during the rendering process (e.g. in the template of this
webox) because it has been lost by this time. It should be added in the
onRender() function, in order to be used in the template. Only the
global scope is the same for both processes, because it encompasses
all the page and breaks the boundaries of all the scopes. So, if you
want to add a variable during the loading and use it during the 
rendering, or when you are in a scope and want to add a variable that
will be used in a different scope, then use WebApp::addGlobalVar() to
add it as a global variable. However, it is recommended to use the 
global variables reluctanly and very rarely, only when they are really
necessary, for the same reasons that you should not use them in
programming languages. 

The session can be thought as an even wider scope, a scope that
contains all the pages of the application from the time that the user 
opens the application until it closes it. Actually, the session 
variables correspond to the global variables of the non-web 
applications (e.g. VB applications). Since the session spans all the
pages, it can be used to keep variables that should not be lost from
one page to another, such as states of the application, states of the
weboxes, etc. For more details read 'session.txt'.


How the framework finds the value of a variable
------------------------------------------------
The framework finds the value of a {{#variable}} like this:
1 - First the current scope is searched for it.
2 - If it is not found, then the scope above it is searched,
    and so on until it is found.
3 - If it is not found in any scope, then session variables
    are searched for it.
4 - If it not found among session variables, then global 
    variables of PHP are searched for it.
5 - If it is not found there, then constants of PHP are searched.
6 - If it still is not found then its name is taken as its value
    (e.g. {{#var1}} is replaced by "var1").



* - Variables can be nested, like this: {{checked_{{id}}}}
    First the innermost variable is replaced, then the outer variable.
    If {{id}} has the value "2" and {{checked_2}} has the value "true",
    then the whole variable above will be replaced by "true";

    If the value of a variable contains another variable inside,
    it will be replaced as well. E.g, if the variable {{nr}} has the 
    value "5" and the variable {{msg}} has the value
    "This is message number {{nr}}.", then using {{msg}} inside a
    template will produce the string: "This is message number 5."
