AZ Templates

Each AZ Template generally is a file, which will be processed by AZ Engine and become a PHP file. Such prepared PHP file contains a function with a body consists of all generated code. Anyway, that PHP file stays executable due a call of dispatch_template function, which executes prepared function too.

Basic Agreement

AZ Template contains any text, but only specific markers will be recognized and transformed into PHP code. Code within markers can be interpreted “as is” or in specific way.

<body>
This is a text placed on the left of the[[MARKER]] and on the right side of it.
</body>

Markers should be opened with [[ and closed with ]]. If you want to cancel default behavior of marker, you should change opening marker to [-[, so marker will be shown without processing.

<body>
This is a text shown [-[fully]].
</body>

The [-[ will be [[ on output, [--[ becomes [-[, and so on.

Basic structure of generated PHP file is shown below:

require_once('template-runtime.php');
$functions['_main_'] = function($cmd, $args = null, $params = null) {
  'user php code, defined in prolog helper'
  'user template code'
}
dispatch_template(main_argument(),  main_subarguments())

As a result of template definition, when you want interrupt template execution, call return.

Raw PHP

You can use all might of PHP within AZ Template, but with some syntax restrictions.

Syntax restrictions

When defining pure PHP code within marker, you can't use:

  • Tilda symbol ~, as it's used for output flow control
  • Dotted constructions like $x.a.b.c as they are used in query helper as field accessors
  • Colon symbol :, as it's used in query helper for defining SQL
  • Symbols { and } in constructions like $variable->{$propname} as they are used in query helper field helpers
  • “At” mark @, as it's used for placement helper

Expressions and statements

  • Expression is everything that returns value. Expression will output its value to stream
  • Statement is everything that doesnt return value. Statement wont output any value to stream
This is a statement [[foreach($arr as $key=>$value){]]
This is an expression. Value = [[$value]]
This is an expression too. Value + 1 = [[$value+1]]
This is a statement, that could be expression too. Add 1 to value. [[$value+=1;]] Nothing in output.
This is a statement too. The most tiny statement. [[}]]
[[if($value===FALSE) {]]
Some text printed when $value===FALSE
[[}]]

Syntax difference between expression and statement commonly is a presence of semicolon symbol ; in the end of statement.

Sometimes you will want to shut down any output of marker. You can do it by using output helper with adding “~” at the end of marker.

There is not output of $variable: [[$variable~]].

Functions, classes and other code

You can define custom PHP code using PROLOG marker. All text of that marker will be placed as PHP code in the beginning of main function.

[[PROLOG
  function func_name($v) {
    return $v;
  }
]]

Environment

Access to context of PHP script is given trough $cmd, $args and $params global variables, which are parameters of main function.

  • $cmd usually contains SQL expression of filter, or other output flow instructions.
  • $args usually contains values to SQL expressions placeholders ( “?” symbols).
  • $params contains URL parameters as properties of $params object. Accessed like $params->name.

Helpers

Output helper

Placement helper

Query helper

Column helper

You can externally define column set for your query helper in template. To use this feature, you must define special URL parameters and markup template with special column zones.

You may define additional columns for query helpers and its sub-query helpers.

Additional columns are distributed among several column sections. Each query helper can contain limitless number of those sections. Section name is unique only for it's query helper container and can be used to markup desired place in template for column output.

URL parameters

You must use xf[] as a parameter with [query helper name]:[section name]:[column path] value. Order of parameters in url defines order of columns in sections.

?xf[]=data:section2:a.rel.f1 & xf[]=subdata:section2:a.f2

Column zones

You must define column zone inside of it's query helper zone. Syntax of marker is $query_helper.{CE section_name}. In most cases, you will use column helper with placement helper @tag, because column helper marker generates loop.

Inside of column helper loop, column must be defined with output helper syntax $query_helper.{$section_name→alias}

<table>
  <tr>[[@tr $data : SELECT * FROM T1]]
    <td>[[@td $data.{CE section1}]][[$data.{$section1->alias}]]</td>
    <td>[[$data.a.f1]]    
    <td>[[@td $data.{CE section2}]][[$data.{$section2->alias}~e:]]</td>
  </tr>
</table>

Header zones

To output captions of columns, you can define header zone in any place of template, regardless of query helper placement, using column helper loop and output helper $section_name→caption

<table>
<thead>
  <tr><th>[[@th$data.{CE fields}]][[$fields->caption]]</th><th>f1</tr>
</thead>
<tbody>
  <tr>[[@tr $data : SELECT * FROM T1]]
    <td>[[@td $data.{CE fields}]][[$data.{$fields->alias}]]</td>
    <td>[[$data.a.f1]]</td>
  </tr>
</tbody>
</table>

Subtemplate helper

Define template section

You can define a section inside a template file using BEGIN:section_name and END:section_name markers. It may contain mixed script code, or even pure PHP.

<html>
[[BEGIN:my_section]]
  <div>[[@div $loop : SELECT * FROM T1 LIMIT 10]][[$loop.a.field_name]]</div>
[[END:my_section]]
</html>

Pure PHP:

<html>
[[BEGIN:my_code]][[
  $a = 1;
  $b = 2;
  echo $a+$b;
]][[END:my_code]]
</html>

Use template section

You can use that sections in such ways as:

  • Inplace, using CALL marker with syntax CALL section_name:file_name:cmd. Parameter file_name has deafault value of current template file, section_name default is main function
  • Reference on template section, using REF marker with same syntax as CALL marker

Pay attention of colon symbols - they have, as you can see, special meaning differs of, for example, BEGIN marker. So, proper use of CALL and REF markers are:

<html>Template file 'cities.php' 
  <span>[[CALL :file_name.txt]] outputs all file_name.txt template</span>
  <span>[[CALL sectionA:file_name.php]] outputs section 'sectionA' of a 'file_name.php' file</span>
  <span>[[CALL sectionB:]] outputs section 'sectionB' of current 'cities.php' file</span>
  <span>[[CALL sectionB::*WHERE idx=15]] outputs section 'sectionB' of current 'cities.php' file using cmd valued with string</span>
  <a href=[[REF :file_name.txt]]></a>
</html>

Parameters of template section

To pass some parameters to CALL, REF or CREF you may define:

  • $command_args array, which contains arguments for called template parameters and for passed to marker cmd
  • $call_params object, whose properties are accessible in called template.

Those definitions must be placed before CALL marker using them.

[[$command_args[]=123;$command_args[]='a';]]
[[CALL procedure:]]
[[BEGIN:procedure]]
  <div>'a' will be printed here:[[ $args[1] ]]</div>
[[END:procedure]]