OmegaSoft - Developer Sandbox - Exploiting the features of the Interface Model Engine

The Interface Model Engine, IME, allows developers to separate the business and presentation logic layers in your application.

The advantages of the IME are; effective separation of interface/business models, flexible presentation and code reusability. HTML and PHP can be completely separated. PHP only needs to return variables to the IME class for inclusion into HTML file. Presentation HTML can be completely changed, without affecting any PHP code. HTML templates can be reused across a whole website, using a single template file. Allowing for changes to be instantly propagated throughout the entire website.

The structure of a template engine allows you, as the developer, to concentrate on the functional specifications of your code, while the artistic teams can concentrate on the layout and overall image of your web service. This means, you don't have to worry about the formatting issues of the website.

The HTML template

A template must first be created in HTML. Nothing more, no PHP, ASP or any other server-side scripting language. This template gives the overall feeling to your website, with all the tables in place, images, styling and JavaScript (if you want). However, all the output, the results of your application, are not included at this point, rather a placeholder 'tag' showing the location where the data will eventually be placed.


<HTML>

<BODY>
Welcome to my web service.  The time now is </b>{DATE}</b>.
</BODY}

</HTML>

The placeholder tag is defined within the curley braces, {DATE}. Obviously this tag represents where the date should finally be displayed on the website. There is now data used at this point.

This template should be saved in its own 'template' directory on your web server with a name to identify it. For example, /public_html/template/date.html

Note: tags must be enclosed in some form of identifiable characters. By default these are the curly braces. These identifiers allow the IME to search through your HTML and find where data should be displayed. You can define other characters as the identifiers should you choose to do so. This is explained later on.

Business logic layer

Now you can concentrate on the functional code. Where the date is generated and assigned to a variable in memory to be later used by the template engine. Take this following example.


<?php

// Include the IME class
include('classes/ime.php');

$date = date('d M Y');

// Instantiate a new template object 
$html_tpl = &new style_engine ('template/date.html'); 

// Define parameters for the class 
$tags = array('DATE' => $date); 

// Parse template file 
$html_tpl->parse_template($tags);

// Display to screen
print $html_tpl->display();

?>

Studying this code, line be line, we can understand how the template engine works.


<?php
include('classes/ime.php');
?>

First and foremost, the IME template class must be included in your script. It is always best to include the class using the include() function, rather than copy & pasting the class into the top of your script. If you update the IME class, you only need to change the class file itself which will propagate its effects to your other scripts. It is best to store the IME class in its own classpath directory.

This code generates the date, using PHP's date library function. It then assigns the date into a variable called $date. This variable is then stored in memory until needed again.


<?php
$html_tpl = &new style_engine('template/date.html'); 
?>

This line now instantiates a new template object from the IME class, which we included a few lines above. We give the style_engine() function parameters the location of the HTML template file we created earlier. When initiating a new class, we create a new variable $html_tpl, which we can use to refer to other helpful functions (tools) in the class.


<?php
$tags = array('DATE' => $date); 
?>

We now create an array called $tags. This array has the $data variable created earlier added to it as a new element. The key given to the array is the placeholder tag we defined in our HTML. In this case, the placeholder tag was {DATE}. The key does not need to include the curly braces.

We store these tags in an array, as usually an application making use of a template engine will most likely be handling multiple placeholder tags. So any additiaonl tags you wish to include in your HTML is added to the $tags array as a new element.


<?php
$html_tpl->parse_template($tags);
?>

We now parse the template file and the $tags array. Other than this one line, there is no other work we have to do here! The Interface Model Engine will take over and automatically find the placeholders and replace them with the data held in the variables in the $tags array.


<?php
print $html_tpl->display();
?>

Finally we print or echo the results to the screen. This will display the HTML template file with all the placeholders replaced with the data values. The result of the website is:


Welcome to my web service.  The time now is 21 June 2007

Handing more complex data

This however, is a very simple example of using the templating engine. Let's say you have a web service which displays a list of products to your customers. You may have multiple products and you want each one displayed on your website. You could use multiple elements in the $tags array. But let's assume that your product list changes day-by-day as you add new or remove existing products. You can never safely assume how many tags you need. And if you have more placeholders in your HTML template than tags, your formatting will look odd. As any placeholders which are missed will be displayed as they are seen in your HTML template.

The Interface Model Engine allows for rows of data to be displayed, by splitting the repetitive parts of the template by using a user-defined HTML comment (by default this uses a string: )

Here is your template. It will display your company name at the top. It will then list what products you supply and the quantity you have.


<!--section (int) reference: 0-->
<html>

<body>
<p>Products provided by {NAME}.
<!--SPLIT--><!--section (int) reference: 1-->
<p>{PRODUCTS} {QTY}
<!--SPLIT--><!--section (int) reference: 2-->
</body>

</html>

The template is sectioned up into three sections. Sections 0, 1, 2. (In computing, 0 is always the start of the count and thus represents the first section). The sections are essentially split by the string . The other comment are only for reference and have no functional properties. In fact, if you prefer you can remove them, although they do help a lot when debugging!


<?php

// Include the IME class
include('classes/ime.php');

// Instantiate a new template object 
$html_tpl = &new style_engine('template.html'); 

// Define parameters for the class 
$tags = array('NAME' => 'My company');

// Parse template file 
$html_tpl->parse_template($tags, 0);

// Loop through the dataset
for($i = 0; $i < count($dataset); $i++)
{
    $tags = array('PRODUCT' => $dataset[$i]['name'], 'QTY' => $dataset[$i]['qty']);
    $html_tpl->parse_template($tags, 1, true);
}

// Parse rest of the template
$html_tpl->parse_template($tags, 2);

// Display to screen
print $html_tpl->display();

?>

We call each section of HTML as we need to, by calling the parse_template() function from the class. You will, in addition to the $tags array, an integer number passed in as a parameter to the function. This number calls the appropriate section of HTML. (Those optional comments can help you (not the class) identify which section is to be called.)

The dataset, where the products are stored, is a multidimensional array, which like what is returned from a SQL database. It appears in the following structure.



Array
(
    [0] => Array
        (
            [name] => Apples
            [qty] => 4
        )
    [1] => Array
        (
            [name] => Oranges
            [qty] => 3
        )
    [2] => Array
        (
            [name] => Pears
            [qty] => 19
        )
)

We simply loop through this array, assigning the placeholders as keys and the values from the $dataset array as elements.


<?php
for($i = 0; $i < count($dataset); $i++)
{
    $tags = array('PRODUCT' => $dataset[$i]['name'], 'QTY' => $dataset[$i]['qty']);
    $html_tpl->parse_template($tags, 1, true);
}

?>

During each loop, we must parse the HTML template section. However, notice the TRUE parameter in the parse_template() function. This tells the class that it is handling repetitive data. If you don't set this to TRUE, the data will overwrite itself.

Note in the above example, how we handle multiple tags in the section, by assigning new elements to the array.

Tags which appear in sections have to be explicitly declared prior to that section being parsed. You cannot declare tags for other sections after you have called the parse_template() function.

API structure of the parse_template() method

void parse_template ( array tags [, int section [, boolean repeat ] ] )

The IME API also allows you to define your own placeholder tag delimiters and splitting comments. These can be defined when the class is instantiated, as shown in the below example.

Defining your own parameters


<?php
// Instantiate a new template object 
$html_tpl = &new style_engine('template.html', array('[', ']'), '<!--NEWSPLIT-->'); 
?>

The second parameter is an array containing a set of start and end delimiters for the placeholder tags. In this example we have used the square brackets although you may want to use any sets of characters. The third parameter is a new splitting tag. It is advised that the splitting tag is a HTML comment, so that it is not displayed on your website.

object style_engine ( string template [, array tags [, string splitting_idr ] ] )

Future potential

In reality, the potential of the Interface Model Engine has only been touched. The class is designed to be scaled,. The examples shown in this technical article are only small demonstration scripts intended to show how the class can be used. Services such as OmegaSoft's Traffic Monitor use the template engine (albeit an older beta version!) to produce visitor statistical output, results and reports.

Code Libraries

Projects & Resources