Gosudar.com.ru

Manual. English

The template engine in R3-born uses portions of the eXtreme Styles MOD, plus some other enhancements/optimisations of my own. Therefore R3-born is compatible with most of the features provided by the eXtreme Styles MOD. This includes...

Fast templates compilation algorythm
Fast templates execution (even if not cached)
Cache system doesn't use the database
PHP code in templates. PHP code should start with <?php or  and end with ?> or  Short tags are not allowed.
Unlimited  switches in one line.
Include other tpl files with
Variable {LANG} that corresponds to current language. Can be used to create truly multi-lingual templates (you can use this in urls: "images/lang_{LANG}/icon_blah.gif").
Variable {PHP} that corresponds to file extension with session data. Can be used to avoid modding when you need to add some url (like "somescript.{PHP}" or "script.{PHP}test=1") Variable contains "?" or "&" at the end so you could easily add arguments to url.
Variable {TEMPLATE} that corresponds to current template directory (like "templates/subAndreas/"). Can be used to avoid filenames case confusion.
Simple template cache management
Tokens IF, ELSEIF, ELSE, ENDIF, DEFINE, UNDEFINE
Support for BEGINELSE

Variables

All template variables should be named appropriately (using underscores for spaces), language entries should be prefixed with L_, system data with S_, urls with U_, javascript urls with UA_, language to be put in javascript statements with LA_, all other variables should be presented 'as is'.

L_* template variables are automatically trie to map to the corresponding language entry. if the code does not set (and therefore overwrite) this variable specifically. For example {L_USERNAME} maps to $lang['USERNAME']. The LA_* template variables are handled within the same way as L_* variables, but properly escaped to be put in javascript code. This should reduce the need to assign loads of new lang vars in Modules and Blocks.

Including files

We now have INCLUDE. This takes the simple form:



In R3-born the template designer can output what they like. Note that you can introduce new templates (i.e. other than those in the default set) using this system and include them as you wish without the need to modify loads of files as wwas the case with phpBB 2.0.x.

Basic Loops

To recap, loops in templates start with  and ends with .

Код:

markup, {loopname.X_YYYYY}, etc.

To use a variable inside current loop use $loopname_item['VARIABLE_NAME
'] where 'loopname' is name of last loop.

To get number of items in current loop use $loopname_count, to get current item in loop use $loopname_i

Extended Blocks/Loops
Loops have been extended with an extension to begin, called BEGINELSE:

Код:

markup

markup

This will cause the markup between BEGINELSE and END to be output if the loop contains no values. This is useful for forums with no topics (for example) ... in some ways it replaces "bits of" the existing "switch_" type control (the rest being replaced by conditionals).

Another way of checking if a loop contains values is by prefixing the loops name with a dot:

Код:

markup


markup

You are even able to check the number of items within a loop by comparing it with values within the IF condition:

Код:

markup


markup

Nesting loops cause the conditionals needing prefixed with all loops from the outer one to the inner most. An illustration of this:

Код:

{firstloop.MY_VARIABLE_FROM_FIRSTLOOP}


{firstloop.secondloop.MY_VARIABLE_FROM_SECONDLOOP}

Sometimes it is necessary to break out of nested loops to be able to call another loop within the current iteration. This sounds a little bit confusing and it is not used very often. The following (rather complex) example shows this quite good - it also shows how you test for the first and last row in a loop (i will explain the example in detail further down):

Код:

<strong>{l_block1.L_TITLE}</strong>
   

      
      
         
            <ul class="nav">
         

         <li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>

         
            </ul>
         
      

   

   <ul class="nav">
   
      <li>
         
            <strong>{l_block1.l_block2.L_TITLE}</strong>
         
            <a href="{l_block1.l_block2.U_TITLE}">{l_block1.l_block2.L_TITLE}</a>
         
      </li>
   
   </ul>

   <a class="nav" href="{l_block1.U_TITLE}">{l_block1.L_TITLE}</a>

Let us first concentrate on this part of the example:

Код:

markup

<a class="nav" href="{l_block1.U_TITLE}">{l_block1.L_TITLE}</a>

Here we open the loop l_block1 and doing some things if the value S_SELECTED within the current loop iteration is true, else we write the blocks link and title. Here, you see {l_block1.L_TITLE} referenced - you remember that L_* variables get automatically assigned the corresponding language entry? This is true, but not within loops. The L_TITLE variable within the loop l_block1 is assigned within the code itself.

Let's have a closer look to the markup:

Код:

.
.


   
      
         <ul class="nav">
      

      <li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>

      
         </ul>
      
   


.
.

The  statement clearly checks a global variable and not one within the loop, since the loop is not given here. So, if S_PRIVMSGS is true we execute the shown markup. Now, you see the  statement. The exclamation mark is responsible for instructing the template engine to iterate through the main loop folder. So, we are now within the loop folder - with  we would have been within the loop l_block1.folder automatically as is the case with l_block2:

Код:

.
.
<ul class="nav">

   <li>
      
         <strong>{l_block1.l_block2.L_TITLE}</strong>
      
         <a href="{l_block1.l_block2.U_TITLE}">{l_block1.l_block2.L_TITLE}</a>
      
   </li>

</ul>
.
.

You see the difference? The loop l_block2 is a member of the loop l_block1 but the loop folder is a main loop.

You can also do comparison on S_FIRST_ROW and S_LAST_ROW. If you haven't guessed already - it is checking for the first iteration of the loop with S_FIRST_ROW and the last iteration with S_LAST_ROW.

Код:

<ul class="nav">


<li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>


</ul>

This can come in handy quite often if you want to open or close design elements, like the above list. Let us imagine a folder loop build with three iterations, it would go this way:

Код:

<ul class="nav"> 
<li>first element</li> 
<li>second element</li> 
<li>third element</li> 
</ul>

As you can see, all three elements are written down as well as the markup for the first iteration and the last one. Sometimes you want to omit writing the general markup - for example:

Код:

<ul class="nav">

</ul>

<li><a href="{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>

would result in the following markup:

Код:

<ul class="nav"> 
<li>second element</li> 
</ul>

Just always remember that processing is taking place from up to down.

Conditionals/Control structures

The most significant addition to the R3-born template engine are conditions or control structures, "if something then do this else do that". The system is very similar to Smarty. This may confuse some people at first but it offers great potential and great flexibility with a little imagination. In their most simple form these constructs take the form:

Код:

markup

expr can take many forms, for example:

Код:

markup

This will output the markup if the S_ROW_COUNT variable in the current iteration of loop is an even value (i.e. the expr is TRUE). You can use various comparison methods (standard as well as equivalent textual versions noted in square brackets) including (not, or, and, eq, neq, is should be used if possible for better readability):

== [eq]
!= [neq, ne]
<> (same as !=)
!== (not equivalent in value and type)
=== (equivalent in value and type)
> [gt]
< [lt]
>= [gte]
<= [lte]
&& [and]
|| [or]
% [mod]
! [not]
+
-
*
/
,
<< (bitwise shift left)
>> (bitwise shift right)
| (bitwise or)
^ (bitwise xor)
& (bitwise and)
~ (bitwise not)
is (can be used to join comparison operations)

Basic parenthesis can also be used to enforce good old BODMAS rules. Additionally some basic comparison types are defined:

even
odd
div

Beyond the simple use of IF you can also do a sequence of comparisons using the following:

Код:

markup

markup
.
.
.

markup

markup

Each statement will be tested in turn and the relevant output generated when a match (if a match) is found. It is not necessary to always use ELSEIF, ELSE can be used alone to match "everything else".

So what can you do with all this? Well take for example the colouration of rows in viewforum. In R3-born row colours are currently predefined within the source as either row1 or row2. However, it is possible to move this to the template, it may look a little daunting at first but remember control flows from top to bottom and it's not too difficult:

Код:

<table>

<tr class="row1">

<tr class="row2">

<td>HELLO!</td>
</tr>
</table>

This will cause the row cell to be output using class row1 when the row count is even, and class row2 otherwise. The S_ROW_COUNT parameter gets assigned to loops by default. Another example would be the following:

Код:

<table>

   <tr bgcolor="#FF0000">

   <tr bgcolor="#00FF00">

   <tr bgcolor="#0000FF">

   <tr bgcolor="#FF00FF">

<td>hello!</td>
</tr>
</table>

This will output the row cell in purple for the first two rows, blue for rows 2 to 5, green for rows 5 to 10 and red for remainder. So, you could produce a "nice" gradient effect, for example.

What else can you do? Well, you could use IF to do common checks on for example the login state of a user:

Код:

markup

This could replace the existing (fudged) method in R3-born 0.1.1 using a zero length array and BEGIN/END.

DEFINE
You can define your own variables within the context of the .tpl by using something similar to the example below.

Код:

Once you have defined a variable you can then use it conditional structures, such as...

Код:

markup

How to use PHP in templates.

This a contentious feature, but the ability to use PHP within the template has been introduced. This is achieved by enclosing the PHP within relevant tags.

NOTE! It is requested that template designers do not use PHP in their templates. The ability to include raw PHP was introduced primarily to allow end users to include banner code, etc. without modifying multiple files, it was not intended for general use. Therefore none of the official R3-born templates will use PHP.

You can use php in any tpl file except for bbcode.tpl (bbcode.tpl is parsed differently by R3-born so you can't use php in it).

PHP code should start with <?php or  and must end with ?> or . Short php tags (<? and <?=) are not allowed.

Код:

echo "hello!";

How to use PHP variables in templates

The Template class is included inside function, so if you want to use global variables inside php in a .tpl you must declare it as global before using it.

If you want to use global variables like $userdata, $lang or $images you must declare it global before using it.

Код:

<?php
global $userdata;
echo $userdata['username'];
?>

How to include other PHP files in templates

To include local php file you can use usual include(); function. Path to file is relative to the root directory. Use the $root_path variable to make sure that path is always relative to R3-born root path.

If R3-born is installed in the directory '/R3-born/' and you want to include the file '/my_website/header.php' you should use this code in the .tpl:

Код:

<?php
global $root_path;
include($root_path . '../my_website/header.php'); ?>

If you want to include remote file via http you should use the readfile(); function.

Код:

<?php @readfile('http://somewhere/somefile.php'); ?>

Remote files are treated as html files, not as php files. And you'd better add @ before function to suppress warning in case if remote file is temporary unavailable.

How to use template variables, switches and loops in PHP

Template variables like {VAR1} and {postrow.VAR1} cannot be used in php inside templates directly.

To use root level variable like {VAR1} you should use this:

Код:

<?php
echo 'variable VAR1 is ', $this->vars['VAR1'];
?>

To use loop variables like {postrow.VAR1} you should use this:

Код:

<?php
echo 'variable postrow.VAR1 is ', $postrow_item['VAR1'];
?>

To use more complex variable like {loop1.loop2.loop3.VAR1} you should use only last loop item like this:

Код:

<?php
echo 'variable loop1.loop2.loop3.VAR1 is ', $loop3_item['VAR1'];
?>

References