wasteland

home projects download

Copyright & License

DTemplate 1.2 Copyright (c) 2004, Peter Mallett
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Overview

DTemplate is a template engine written in PHP. It allows you to separate your programming logic from your HTML output. If you've ever tried to print a complex page with dynamic data in a table using only PHP...

DTemplate allows you to use complex formatting without either embedding PHP code in multiple places in your HTML or hand printing HTML from your PHP code.

The Basics

Template

Where DTemplate is concerned, a template is any text file with fields in it. When DTemplate processes the template file, the fields are replaced with the values you specify for them in your code.

In DTemplate code the fields are marked with curly braces (e.g. {FIELD}). So a simple example template file would contain just the following text:

Hello {NAME}. How are you?

Reasons for using templates

Embedding HTML code in your PHP scripts is messy at best and just a nightmare at its worst. On the other hand, embedding PHP code in your HTML files can make using a WYSIWYG editor a hassle. Using a template to separate your layout from your code can do a few things:

• Reduces clutter in your code by removing the HTML making it easier to debug and/or modify.
• Allows you to change the look of a page without editing the PHP script that runs it. Using templates, designers can update a page's look or layout without being concerned with the code that generates the final page.

Using DTemplate

The first step when using any class in PHP is to include the source file.

include('class.DTemplate.php');

Once you have included the class file in your script, using DTemplate is fairly simple. There are only five steps involved in order to render a page using a template.

1. create the template object
2. define your template
3. assign values to your fields
4. process the template
5. print the output or fetch it for later use

Since this is all you need, these five methods are listed first in the Main Method Reference section.

Main Method Reference

DTemplate

Constructor

This method is called when you create a new DTemplate object.

DTemplate ([string templatedir])

The path to your template files can be set at this time using templatedir. The template directory defaults to the current working directory if templatedir is omitted.

Examples:

$tpl = new DTemplate('path/to/template/files');

$tpl = new DTemplate( );

 

define_templates

Used to specify a template file to use and give it a handle to reference it by.

define_templates (array(string handle => string filename))

After calling define_templates you will not need to use the file name again. The handle will be used to refer to the template.

Example:

$tpl = new DTemplate('path/to/template/files');
$tpl->define_templates(array(
            'body' => 'main.tpl',
            'footer' => 'footer.tpl'
));

Note: define_templates does not actually load the template files, so it is faster and more convenient to define all templates in one call to define_templates.

 

assign

Used to assign values to the fields in the template.

assign (array(field => value))
assign (string field, string value)

The field parameter should match the field name in the template file. So, if your template file contains the text {NAME} the assign call could be either of the following:

assign ('NAME', 'value_for_name_field');

assign (array('NAME' => 'value_for_name_field'));

Notes: Field names are case sensitive; Each instance of DTemplate can have only one copy of a given field.

Example:

$tpl->assign (array(
           'FIELD1' => 'text1',
           'FIELD2' => 'text2'
));

$tpl->assign ('FIELD1', 'newfield1text');

In this example the value for FIELD1 is 'newfield1text' since that call to assign overwrites the same field assignment in the first call. This is something to be aware of if you are using multiple template files in one script that have fields with the same names.

 

process

Loads the template file if it hasn't already been loaded. Then, replaces all assigned fields with their values and stores the result using the specified handle.

process ( string handle [, string output_handle] )

handle is the name that was assigned to the template in the call to define_templates.

output_handle is an optional name that can be given to the output. Using this, you can process a template into separate output variables and then print them individually. If output_handle is omitted, DTemplate will continue to use handle to reference the output.

Examples:

$tpl->process('body');

$tpl->process('body', 'body_output01');

Note: process also inserts the output for any sub-blocks within the template. Hence, sub-blocks should always be processed before their parent blocks (see Dynamic Templates).

 

DPrint

Prints the contents of the specified output handle.

DPrint (string output_handle)

Examples:

$tpl->DPrint('body');

$tpl->DPrint('body_output01');

see also: fetch (other methods)

Other Methods

set_template_dir

Set or change the directory path that template files will be loaded from.

set_template_dir (string template_dir)

 

define_template

Alternative to define_templates. The only difference is define_template is used to specify one template at a time as opposed to an array of templates as in define_templates.

define_template (string handle, string filename)

As with define_templates, after calling define_templates you will not need to use the file name again. The handle will be used to refer to the template.

Example:

$tpl = new DTemplate('path/to/template/files');
$tpl->define_template('body', 'main.tpl');
$tpl->define_template('footer', 'footer.tpl');

Note: As with define_templates, define_template does not actually load the template files, so it is faster and more convenient to define all templates in one call to define_templates.

 

clear_assign

Clears values assigned to fields through previous calls to assign.

clear_assign ([string fieldname])

If fieldname is omitted, all field values will be cleared, otherwise only the specified field will be cleared.

 

clear_output

Clears template output created by previous calls to process.

clear_output ([string output_handle])

if output_handle is omitted, all template output is cleared, otherwise only the specified output will be cleared.

 

fetch

Returns the contents of the specified output handle.

fetch (string output_handle)

Examples:

$results = $tpl->fetch('body');

$results = $tpl->fetch('body_output01');

Note: this is useful for things like storing the processed output in a database or a file. Also, particularly useful in conjunction with CacheIT (http://www.boaddrink.com)

Dynamic Templates

A dynamic template is a template containing a portion of code specified as dynamic which may be printed multiple times within the template, or removed completely.

An example would be a template file with a table in it where the row in the table is dynamic, meaning there could be a variable amount of rows printed.

In DTemplate sub-blocks are wrapped with pseudo-XML tags in the following format:

<block:blockname>
  html goes here
</block:blockname>

Note the spacing in the example. The block delimiters in the template have to match the format given in $BLOCK_START and $BLOCK_END.

There is only one extra method for working with sub-blocks: define_block. After the block is defined, it is processed just like the main template block.

define_block

Used to specify the name of a sub-block and the template, or block that it appears in (ie: its parent block).

define_block (string blockHandle, string parentHandle);

blockHandle must match the name of the block handle in the template code.

parentHandle is either the template handle (define_templates) for the template that contains the sub-block OR the blockHandle of a previously defined block (see: Nested Blocks).

Example:

$tpl->define_template('body', 'body.tpl');

$tpl->define_block('blockname', 'body');

Note: in this example body.tpl must contain the code <block:blockname></block:blockname> or DTemplate will exit with an error.

Nested Blocks

A nested sub-block is a block that appears inside another sub-block.

Example body.tpl:

<block:outerblock>
  <block:nestedblock>
  some template code here
  </block:nestedblock>
</block:outerblock>

There are two differences that you must keep in mind when using nested blocks. First, when defining nested blocks, the blocks must be defined from the outside, in. In other words, parent blocks must be defined first.

Secondly, in the call to define_block, the nested block must reference the block it is contained within as its parent block.

Example:

$tpl->define_template('body', 'body.tpl');
$tpl->define_block('outerblock', 'body');
$tpl->define_block('nestedblock', 'outerblock');     // <-- the second parameter must be the parent block's handle

Version History

Version	Date
1.2	2004-11-28	! Major rewrite. Almost every function has been rewritten or changed in some way. ! DTemplate 1.2 is not released under the GNU General Public License, it's under the BSD license. http://www.opensource.org/licenses/bsd-license.php ! Moved copyright output to end of template output to fix a problem with IE when using XHTML in your top template block. ! Marginal speed increase over DTemplate 1.1.3 in most cases. + Sub block processing has been changed to allow empty block contents for any iteration without removing the block code completely (so it can still be used in later iterations). This allows for some extra complexity when using nested blocks. (see example 4).
1.1.3	2004-01-21	! fixed a bug that caused a memory error in PHP when using a non-defined dynamic block tag
1.1.2	2002-12-02	= when using 1.1.1 with error_reporting(E_NOTICE) several problems would occur ! fixed code that would cause a notice about an undefined index when using dynamic blocks ! fixed examples' code that would cause notices about undefined constants ! changed example code in the documentation that would cause notices if used as actual code = code cleanup in examples = fixed spelling errors in documentation ! corrected parse documentation in the dynamic template section
1.1.1	2002-11-27	! fixed clear_dynamic, it will now remove the dynamic block completely = syntax changes for PEAR coding standards = general code cleanup + added copyright information to output + added dynamic block delimiter format variables
1.1	2002-10-18	! changed the function define to define_templates. define is an internal function in PHP ! parse_dynamic is now an internal function and should not be called from scripts using DTemplate, use parse instead ! parse no longer requires an output handle. Most of the time the output is only going to one place. And in the case of dynamic blocks can only go to one place. ! when using an output handle with parse, it is now the second argument ! when defining dynamic blocks, if the block is inside another block, it needs to reference the parent block in the second argument instead of the template + dramatic speed increases when dealing with dynamic blocks over version 1.0.1
1.0.1	2002-02-19	! Fixed a bug in the fetch function.
1.0	2001-11-30	Initial release.