edit

MicroUI Templates

Skytells MicroUI Template Engine For PHP

Skytells template engine designed to support for if/loops/filters integrated with Skytells PHP Framework.

It is aimed to be a small string TemplateEngine to meet e-Mailing or small html-Template demands. It is not meant to be a replacement for pre-compiled full featured TemplateEngines like Smarty or Twig.

Skytells Template Engine uses Regular-Expressions for text-Parsing. No code is generated or evaluated - so this might be a secure solution to use in no time-critical situations.

Whilst most template-engines rely on eval'ing generated code and filesystem-access, Skytells Template Engine uses a
set of regular-expressions to parse the template. Nor any intermediate code is generated nor any code is eval'ed. So TextTemplate should be more secure than Smarty or Twig by design.

Skytells Template Engine supports infinite-nested loops and sequences.

Table of Contents

Initialization

This Engine will be loaded only if you choose the Template Engine (MicroUI) from Settings.php configuration file.

File Extension

This engine will work only if your view's extension contains (.ui) before (.php) for example, (myview.ui.php), that way the template engine will be initialized.

Configuration

Please make sure to add the right configuration in order to use this template engine.

Configuration

If you have not configured the Template Engines's settings file
Please Click here to learn more

Adding Parses

Before rendering a page to the viewer, you need to make an array to include your parses. As Example :

1
2
3
4
<?php

$Parses = array('name' => 'Hazem', 'age' => 27); // Preparing parses array.
View::render('Home/index.php', null, (array)$Parses); // Including the Array upon Rendering the UI.

Rendering UI

Since you're using now a Template Engine, so your call to the Viewer must include your parses array. As Example :

1
2
3
<?php
$Parses = array('name' => 'Hazem', 'age' => 27); // Preparing parses array.
View::render('Home/index.php', null, (array)$Parses); // Including the Array upon Rendering the UI.

Basic Examples

Say we have a UI in the views folder includes the following details.

1
2
3
4
5
6
7
<html>
 <title>{= PAGE_TITLE}</title>
 <body>
   Welcome, {= name}
   Your age is {= age}
 </body>
 </html>

The rendering results will be :

1
2
3
4
5
6
7
<html>
 <title>Website title! (Comes from Language Parses)</title>
 <body>
   Welcome, Hazem
   Your age is 27
 </body>
 </html>

So, the engine will include and render your Language parses located in ( Application/Library/Languages ).

Value Injection

Use the value Tag

1
{= varName}

To inject a value to the Code. Any variables will be htmlspecialchars() encoded by default. To output the RAW content use the raw-Filter: {=htmlCode|raw}

To access array elements or objects use "." to access sub-elements:

{= users.0.name}

Filters

The Skytells TemplateEngine supports filters, So you can Apply your filter to variables by adding a splitter | and the filter name.

EXAMPLES

Before Filtration

1
2
3
<?php
Hi, {= username}
// This is non-filtered string, So the output should be : Hi, Hazem

After Applying a Filter

1
2
3
<?php
Hi, {= username | uppercase}
// This is a filtered string, So the output should be : Hi, HAZEM

Predefined Filters

Our engine includes a predefined filters all ready to use.

Name Description
raw Display raw data (skip default escaping)
singleLine Transform Line-breaks to spaces
inivalue like singleLine including addslashes()
html htmlspecialchars()
uppercase Converts output to uppercase
lowercase Converts output to lowercase
usfirst Converts the first chr to uppercase

Adding Filters

You can add custom filters or overwrite own filters.

Warning

Adding Or Replacing Filters designed For Advanced Programmers ONLY!.

Adding a new Filter when the engine being called:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?php
$this->load->engine('TemplateEngine'); // Importing Engine to the Controller.
$Parses = array('name' => 'Hazem', 'age' => 27); // Preparing parses array.
$Filters = array('UPPER' = > function($callback)
                                  {
                                    return strtoupper($callback);
                                  });
View::render('Home/index.php', null, null, (array)$Parses, (array)$Filters);
// Including the Array upon Rendering the UI.

// Output : HAZEM because we've made a filter to convert output to uppercase.

Use this filter inside your template

1
{= name | UPPER }

Replacing the default-Filter

By default and for security reason all values will be escaped using the "DEFAULT"-Filter. (except if "raw" was selected within the filter section)

Warning

Adding Or Replacing Filters designed For Advanced Programmers ONLY!.

If you, for some reason, want to disable this functionality or change the escape function you can overwrite the DEFAULT-Filter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?php
$this->load->engine('TemplateEngine'); // Importing Engine to the Controller.
$Parses = array('name' => 'Hazem', 'age' => 27); // Preparing parses array.
$Filters = array('_DEFAULT_' = > function ($input) {
    return strip_tags ($input);
});
View::render('Home/index.php', null, null, (array)$Parses, (array)$Filters);
// Including the Array upon Rendering the UI.

// Output : HAZEM because we've made a filter to convert output to uppercase.

This example will replace the htmlspecialchars() escaper by the strip_tags() function.

Built-In Functions

Loops

You can insert loops:

1
2
3
{for curName in names}
Current Name: {= curName}
{/for}

Inside each loop, there are to magick-values @index0 (index starting with 0) and @index1 for a index starting with 1.

1
2
3
{for curName in names}
Line {= @index1 }: {= curName}
{/for}

Conditions (if)

You can use if-conditions:

1
2
3
{if someVarName == "SomeValue"}
Hello World
{/if}

Limitation: Logical connections like OR / AND are not possible at the moment. Maybe in the future.

Importing Files to the View

Our engines supports including RAW and executable files to your current Template view.

Usable Functions :-

These are the available function used to perform these actions.

Import
Include
Require
Include Once
Require Once

The default path for all these function is (Application/Views) folder.

The tags passed into these functions must have the file attribute which contains the template resource path. As example, Say we have all these files in our Views Folder, And we want to perform once of the functions listed above.

1
2
3
4
5
| Application/
| -- Views/ ------------------> All functions listed above will look at your files here.
| ----- Home/
| -------- file.php
| -------- index.php

The deferent between {= include} and {= include_once}. - {= include} - This function will include your file more than one time, as it performs (include) PHP function. - {= include_once} - This function will include your file in your UI ONCE, as it performs (include_once) PHP function.

The deferent between {= include} and {= include_once}. - {= require} The {= require} function performs require (PHP Function) And its identical to include except upon failure it will also produce a fatal E_COMPILE_ERROR level error. In other words, it will halt the script whereas include only emits a warning (E_WARNING) which allows the script to continue.

  • {= require_once} The {= require_once} function performs require_once (PHP Function) And The require_once statement is identical to require except PHP will check if the file has already been included, and if so, not include (require) it again.

Import

You can import a file (RAW FILES ONLY) using a command named {= import}.

1
{= import file.tpl}

Output : the RAW content for your file.

Important Notice

This function will not perform, execute, or even display a PHP file, if you want to include an executable file like (* .PHP ) So Please refer to the following functions.

Include
Require
Include Once
Require Once

Include

The {= include} tags are used for including other files in the current template. Any variables available in the current template are also available within the included template.

The default path for {= include} tag is (Application/Views) folder.

The {= include} tag must have the file attribute which contains the template resource path.

The targeted file ( MUST BE IN THE MAIN VIEWS FOLDER ).

So, Lets include the (file.php) located in the (Application/Views/Home).

1
{= include Home/file.php}

Other Example :- Say we have this code in our (index.php) file located in (Application/Views/Home). And we want to include a file named (file.php).

1
2
3
4
5
6
7
8
9
<html>

<body>
{= include file.php}

{* body of template goes here *}

</body>
</html>

Well, Done. Thats it.

Include Once

The {= include_once} tags are used for including other files in the current template. Any variables available in the current template are also available within the included template.

The default path for {= include_once} tag is (Application/Views) folder.

The {= include_once} tag must have the file attribute which contains the template resource path.

The targeted file ( MUST BE IN THE MAIN VIEWS FOLDER ).

So, Lets include the (file.php) located in the (Application/Views/Home).

BUT, As mentioned above, this function will NOT include your file if you included it before, which means it will include the selected file ONCE.

1
{= include_once Home/file.php}

Other Example :- Say we have this code in our (index.php) file located in (Application/Views/Home). And we want to include a file named (file.php).

1
2
3
4
5
6
7
8
9
<html>

<body>
{= include_once file.php}

{* body of template goes here *}

</body>
</html>

Well, Done. Thats it.

Require

The {= require} tags are used for requiring other files in the current template. ( IF REQUIRED ) Any variables available in the current template are also available within the included template.

The default path for {= require} tag is (Application/Views) folder.

The {= require} tag must have the file attribute which contains the template resource path.

The targeted file ( MUST BE IN THE MAIN VIEWS FOLDER ).

So, Lets require the (file.php) located in the (Application/Views/Home).

1
{= require Home/file.php}

Other Example :- Say we have this code in our (index.php) file located in (Application/Views/Home). And we want to require a file named (file.php).

1
2
3
4
5
6
7
8
9
<html>

<body>
{= require file.php}

{* body of template goes here *}

</body>
</html>

Well, Done. Thats it.

Require Once

The {= require_once} tags are used for requiring other files ONCE IF REQUIRED in the current template. Any variables available in the current template are also available within the included template.

The default path for {= require_once} tag is (Application/Views) folder.

The {= require_once} tag must have the file attribute which contains the template resource path.

The targeted file ( MUST BE IN THE MAIN VIEWS FOLDER ).

So, Lets include the (file.php) located in the (Application/Views/Home).

BUT, As mentioned above, this function will NOT include your file if you included it before, which means it will include the selected file ONCE.

1
{= require_once Home/file.php}

Other Example :- Say we have this code in our (index.php) file located in (Application/Views/Home). And we want to include a file named (file.php).

1
2
3
4
5
6
7
8
9
<html>

<body>
{= require_once file.php}

{* body of template goes here *}

</body>
</html>

Well, Done. Thats it.

Debugging the Parameters

To see all Parameters passed to the template use:

1
{= __CONTEXT__ | raw}

It will output the structure of the current context.

Limitations

The logic-Expression-Parser won't handle logic connections (OR / AND) in conditions.

Benchmark

Although the parser is build of pure regular-expressions, I tried to avoid too expensive constructions like read ahead, etc.

And we got quite good results:

Template size Parsing time[sec]
50kB 0.002
200kB 0.007