The template engine in BitOwl Application Suit allows for a safe subset of scripting capabilities to be available to the template author. It is designed to allow the template information to be completely separated from the scripts themselves. The syntax of the templates is not particularly based on any previous langauge.
To add small pieces of scripts you must enclose the template code into HTML comments like so:
<!-- // Code goes here -->As seen above, the only form of commenting available are single line
comments. These are formed by prepending //
to the line in which
you do not wish to be included in the final output.
Commands can be broken by a semicolon or simply by a new line. Do note that the opening and closing statements are considered commands and must be separated by a semicolon if they are used in the same line.
In some cases it may be needed to have a block of code be outputted without
being parsed by the template engine. Using <!---
as the opening
statement means that anything inside should be printed as is.
Variables are simply identifiers that are not reserved by the language
itself. They access an array in the PHP code with each dot separated identifier
being an index in the array. For example somevar.element
would
go to $template_engine->variables['somevar']['element']
.
In addition certain keywords in the first element are reserved to access
other variables. language.STRING
will access the specified string
from the currently in use language file. get.variable
will access
the global $_GET['variable']
. And lastly post.variable
will get the value from $_POST['variable']
.
Some times it is needed to make an element the value of another variable. To
do this enclose the variable in parenthesis. For example somvar.(i)
would translate to $template_engine->variables['somevar'][$template_engine->variables['i']]
.
This is particularly useful when a for loop is used.
Variables can be printed from outside of a template block. To do this
encode the variable in braces ({
and }
). For example
{variable}
.
The following functions are available for use in templates.
include(str template)
Includes the specified template file. This requires the full path relative to the script root.
set(var variable, int value)
Sets the variable to the specified value. It has little use out side of keeping track of what has happened.
print(var variable)
Prints the value of the variable. This is equivalent to doing
{variable}
outside of a scripting block.
showPagination(var variable)
Prints a pagination object.
recurse(var save, var dest, var src)
Recurses the template storing the value of save onto a stack. The value of dest is then set to src. Use for displaying sub trees in comments.
A limited set of conditional statements are available. These must be
terminated with the end
keyword. See the following example for
reference.
[else]if(boolean statement)
Evaluates the boolean statement and executes the code following if true.
elseif
should be used instead of else if
if more
than one conditionals are used.
else
Executes the following code if none of the previous if clauses are true.
for(var iterator; boolean statement; int step)
Sets the iterator variable to 0 then loops until the boolean statement
becomes false. It increments by step each loop. This is useful if the
numerical index is needed, but for most cases foreach
is the better option.
foreach(var values, var copy)
Iterates through every element in values storing the value into copy.
forlinkedlist(var list, var copy)
Iterates through a linked list (such as for comments) storing the value of each node into copy.
if[n]def(var variable) Deprecated
Checks if the variable has been set and executes the following code if
so. This has been deprecated in favor of using if([!]isset(variable))
which translates identically when compiled.
The template engine allows a limit set of operators to be used in boolean
expressions (if statments). These operators include <, >, /, *, +, -, %,
!=, ==, <=, >=, or, ||, &&, and, xor, ===, !==, isset(variable),
empty(variable), is_numeric(variable), is_string(variable), is_array(variable),
is_null(variable), and count(variable).
Integers, strings, and variables
can be used in the comparisons.
The template engine is initialized in index.php and init.php. For parts of
the main control panel you can access it from $template_engine
.
For parts on the end-user's website the template engine is at
$_bitowl['templates']
.
To set the value of a variable in a template simply set the proper array
index in the variables
property in the template engine object.
For example: $template_engine->variables['myvar'] = 'test';
would
set myvar
to the string 'test'.
To display a template from the control panel you may use the
template(str $template)
function the the template engine object,
but from end-user scripts it is preferable to use the
showTemplate(str $template, bool $fullpath=false)
function (this is a global
function not part of the template engine). This function loads the proper
template based on what was selected in the system cp.
loggedinuser
Either 0 or an array with the user's information.
loggingin
Possible values are 'false', 'true', or 'failed'.
registration
Possible values are 'false', 'true', 'passwords_dontmatch', 'username_inuse', or 'empty'.
query
comments
Complete comment tree. Use forlinkedlist to traverse.
forlinkedlist(comments, comment)comment.id
comment.author
comment.comment
comment.date
comment.subject
comment.sub
Only needed for recursing the template.
recurse(comment, comments, comment.sub);author
Either 0 or an array with the article's author's information.
article
article.id
article.author
article.comments
article.date
article.recent
article.shortstory
article.story
article.thumbnail
image
image.description
image.file
image.title
nav
nav.next
nav.prev
trace
An array representing the path to the image. For example:
<!-- foreach(trace, traceStep) if(!isset(traceStep.last)) --><a href="/Gallery/{traceStep.id}"><!-- end; print(traceStep.name); if(!isset(traceStep.last)) --></a> » <!-- end; end; -->album
album.id
album.images
album.images.i.description
album.images.i.title
album.images.i.thumbnail
numimages
pagination
trace
See gallery_image.html::trace.
subalbums
Array of albums which are children of the current.
paginationid
Variable to pass in the URL to change pages.
paginationnext
The value of the next page or -1.
paginationprevious
Same as paginationnext, but for the previous page.
paginationpages
An array consisting of all the pages to display. Each element should
be in the form of array('start' => int, 'number' => int, 'active' => bool)
or it will be NULL in which case ellipses should be printed.