Template : DooViewBasic

[RichardM]

Hi,

For those of you are unaware I have been working on a new DooPHP Template Engine. It is intended to enhance the default DooView class used by people right now and I will be trying to get this to become the default template engine for DooPHP from release 1.3 of DooPHP in which case you will need to
1) Update your templates to make use of the new syntax and functionality
2) Set the default controller to the existing DooView class

Why change it? Simply put it means new users would be using the new system from Day 1 and not the older system.

Anyway to start using the new template engine:

• Update to the latest revision of DooPHP (R343 or newer) from SVN
• Open your config.conf.php file
• Add the following line within your config file
  

  Code: Select all

  $config['TEMPLATE_ENGINE']='DooViewBasic';

• Save the changes

Note: Existing templates will likely need to be updated. See next post for details on current syntax

Richard

[RichardM]

Tags
The first big change in the new version is the Tags used to specify Output, Statements and Comments. These are by default set to:

• Variable Output - {{ and }}
• Statement Blocks - {% and %}
• Comments - {# and #}

You can change these by calling the following functions from your controller after the view has been initialised

Code: Select all

$this->_view->setVariableTags('<<', '>>');
$this->_view->setBlockTags('<!--', '-->');
$this->_view->setCommentTags('##', '##');


[RichardM]

Variable Output
In order to output the values of variables (and functions) you can use the variable tags within your template

I will assume you have a controller which defines a number of variables for use in your templates as below:

Code: Select all

<?php
Doo::loadCore('controller/DooController');
class MainController extends DooController {
   public function index() {
      $data = array();
      $data['var1'] = 12;
      $data['var2'] = "Hello, World";
      $data['var3'] = array("A", "B", "C", "D", "E");
      $data['var4'] = array('x' => 'value 1', 'y'=>'value 2', 'z'=>'value 3');
      $data['var5'] = new TestObj('Foo', 'Bar');
      $this->render('index', $data, NULL, true);
   }
}

class TestObj {
   public $a;
   public $b;
   public function __construct($a, $b) {
      $this->a = $a;
      $this->b = $b;
   }
}
?>


Now in your protected/view/index.html file do the following:

Code: Select all

{{var1}}<br />  <!-- Will output 12 -->
{{var2}}<br />  <!-- Will output: Hello, World -->
{{var3.2}}<br /> <!-- Will output: C -->
{{var4.y}}<br /> <!-- Will output: value 2 -->
{{var5->a}}<br /> <!-- Will output: Foo -->


Compiled Template will look like this:

Code: Select all

<?php echo $data['var1']; ?><br />  <!-- Will output 12 -->
<?php echo $data['var2']; ?><br />  <!-- Will output: Hello, World -->
<?php echo $data['var3'][2]; ?><br /> <!-- Will output: C -->
<?php echo $data['var4']['y']; ?><br /> <!-- Will output: value 2 -->
<?php echo $data['var5']->a; ?><br /> <!-- Will output: Bar -->


Update:
I have now added support to use a $data value as an index to another $data value. The code for this is:

Code: Select all

{{foo.[bar]}}
{{foo.[obj->type]}}


These compile down to

Code: Select all

<?php echo $data['foo'][$data['bar']]; ?>
<?php echo $data['foo'][$data['obj']->type]; ?>


Note: If you are using the safe variable access option then only the outer $data will be wrapped by the function and not both calls to $data. E.g.

Code: Select all

<?php echo DooViewBasic::is_set_or($data['foo'][$data['bar']]); ?>
<?php echo DooViewBasic::is_set_or($data['foo'][$data['obj']->type]); ?>


[RichardM]

Output Functions

This example is still based on the Controller we defined in the previous post. We will however define some other things we need.

Open the file /protected/plugin/TemplateTag.php and add the following code near the bottom

Code: Select all

class TemplateTag {
   public static function add($a, $b) {
      return $a + $b;
   }
   public static function sum($values) {
      $total = 0;
      foreach($values as $value) {
         $total += $value;
      }
      return $total;
   }
}


Now add the following to the MainController just before the $this->render(..); line

Code: Select all

      $data['var6'] = array(10, 20, 30, 40, 50);
      $data['var7'] = array('a'=> 10, 'b' => 20, 'c'=> 30);
      $data['var8'] = new TestObj(50, 100);


Now replace (or add) the following to your index.html file:

Code: Select all

{{add(var1, var1)}}<br /> <!-- 12 + 12 = 24 -->
{{add(var6.1, var6.3)}}<br /> <!-- 20 + 40 = 60 -->
{{add(var8->a, var8->b)}}<br /> <!-- 50 + 100 = 150 -->


This compiles down to:

Code: Select all

<?php echo TemplateTag::add($data['var1'],$data['var1']); ?><br /> <!-- 12 + 12 = 24 -->
<?php echo TemplateTag::add($data['var6'][1],$data['var6'][3]); ?><br /> <!-- 20 + 40 = 60 -->
<?php echo TemplateTag::add($data['var8']->a,$data['var8']->b); ?><br /> <!-- 50 + 100 = 150 -->


[RichardM]

Static Variable and Function output
This feature can be helpful if you are offering translated versions of your sites (and so far is the only real world example I can think of where this is useful).

Essentially it allows you to save time when rendering a template (note this is the process of applying your data to the compiled version of your template) by allowing you to call functions and variables and embed the response value into the template so they appear to be statically defined.

Assuming you have a language translation process setup and in place (DooPHP supports this and its documented elsewhere so I wont be repeating it here) we might have a language translation function defined in our TemplateTags.php file as follows:

Code: Select all

public static function T_($strToTranslate) {
    return MyApp::Translate($strToTranslate);
}


In the template you can now call this function as follows

Code: Select all

<a href="#">{{+T_('Home Page')}}</a>


The key part here is the introduction of the + straight after the {{ opening tags. This can be placed in for variables too {{+var1}}

When the template is compiled it will call this function during complication and place the resulting value directly into the compiled template as follows

Code: Select all

<a href="#">Home Page</a>


Notice that there are no php tags etc in this compiled template.

[RichardM]

Nested Functions
So far you have seen that you can embed a template tag like

Code: Select all

{{add(var6.1, var6.3)}}


However you can also nest functions inside functions like so:

Code: Select all

{{add(add(var6.1, add(var8->b, var7.b)), sum(var6))}}


This will be complied down to:

Code: Select all

<?php echo TemplateTag::add(TemplateTag::add($data['var6'][1],TemplateTag::add($data['var8']->b,$data['var7']['b'])),TemplateTag::sum($data['var6'])); ?>


The output of this being 290.

Note: This can be used anywhere where a single function might be usable

[RichardM]

Comments
Comments can be used to prevent code being processed during compilation and therefore avoid them being output in the rendered templates.

You can use them for single line comments and additionally to block out large blocks of text. Some examples are included below

Code: Select all

{# This is a single line comment #}

{#
    This comment
    will span across
    a number of lines
#}

{#
    This comment covers a few lines and prevents the below code running
    {{var1}}
    {{+var1}}
    {{add(var1, var1)}}
#}


The compiled version of this template (and therefore the one sent back to the browser would contain a couple of blank, new lines and that it. all the rest will have been filtered out

[RichardM]

Arrays
You can now define arrays to be used. Some more examples of there use will come later but for now I will just give a simple example using functions:

Code: Select all

// Simple Array
{{sum([1, 2, 3, 4])}}

// Associative Array
{{sum([a=10, b=20, c=30, d=40])}}

// Arrays can also be nested
{{funcA([10, 20, 30, [1, 2, 3], [5, 10, 15]])}}

// Mixed Array
{{funcA([a=10, b=[15, 30], 100, 25, c=45])}}


NOTE: We have not defined funcA so you will get errors if you try to run this...

These will compile down to:

Code: Select all

// Simple Array
<?php echo TemplateTag::sum(array(1,2,3,4)); ?>

// Associative Array
<?php echo TemplateTag::sum(array('a'=>10,'b'=>20,'c'=>30,'d'=>40)); ?>

// Arrays can also be nested
<?php echo TemplateTag::funcA(array(10,20,30,array(1,2,3),array(5,10,15))); ?>

// Mixed Array
<?php echo TemplateTag::funcA(array('a'=>10,'b'=>array(15,30),100,25,'c'=>45)); ?>


You can not currently do the following. I might add support for this later

Code: Select all

{{['hello', 'world'].1}}

[RichardM]

Set Variables
If you need to set a variable from within your template - Designers do sometimes need some template logic after all to make things look impressive - You can use the set command.

The syntax for this is as follows

Code: Select all

{% set a as 10 %}
{% set b as 'hello, world' %}
{% set c as [1, 2, 3] %}
{% set d as add(1, 2) %}
{% set e as var1 %}
{% set e as var5->b %}
{% set f as var4.y %}

<!-- Output some of the values -->
{{b}}<br />
{{e}}


This will compile down to:

Code: Select all

<?php $data['a'] = 10; ?>
<?php $data['b'] = 'hello, world'; ?>
<?php $data['c'] = array(1,2,3); ?>
<?php $data['d'] = TemplateTag::add(1,2); ?>
<?php $data['e'] = $data['var1']; ?>
<?php $data['e'] = $data['var5']->b; ?>
<?php $data['f'] = $data['var4']['y']; ?>

<!-- Output some of the values -->
<?php echo $data['b']; ?><br />
<?php echo $data['e']; ?>


Update: You can now use expressions like foo.bar as the variable to be set for example:

Code: Select all

{% set foo.bar as 10 %}
{% set foo->bar as 10 %}


and they will compile down to:

Code: Select all

<?php $data['foo']['bar'] = 10; ?>
<?php $data['foo']->bar = 10; ?>


[RichardM]

If, Elseif, Else, Endif
If statements can be used to add some logic to the rendering of your page. A simple example is below intended to give you an idea of how this works / what you can do.

Code: Select all

{% if var1 == 12 %}
   var1 does equal 12
{% elseif (add(var1, sum([1, 2, 3])) == 19) && (false == false) %}
   var 1 + sum of array equals 19 AND false does equal false
{% else %}
   Reached Else
{% endif %}


This will compile down to:

Code: Select all

<?php if($data['var1']==13): ?>
   var1 does equal 12
<?php elseif((TemplateTag::add($data['var1'],TemplateTag::sum(array(1,2,3)))==19)&&(false==false)): ?>
   var 1 + sum of array equals 19 AND false does equal false
<?php else: ?>
   Reached Else
<?php endif; ?>


You can have an unlimited number of elseif's and use && and || although its advised you make sure your brackets match up AND you leave a spaces either side of operators (!==, ===, ==, !=, ++ etc)