Download the PHP package wernerwa/pat-template without Composer

On this page you can find all versions of the php package wernerwa/pat-template. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of wernerwa/pat-template

Informations about the package pat-template

patTemplate Introduction

patTemplate helps you separating the business logic from the layout and the content of your websites.

Using patTemplate, you will no more embed PHP code directly in your HTML code. Instead you will insert placeholders in your HTML documents, which will be replaced by the actual computed values by your PHP application.

The wiki is archived at https://web.archive.org/web/20150505033634/http://trac.php-tools.net/patTemplate/wiki/Docs

patTemplate works with PHP 5.1-8.3

patTemplate for the designer

patTemplate offers you XML-based markup tags to access different parts of your layout files so you can hide, exchange or even repeat parts. This means, that your HTML-designers will need to learn some new tags and their usage. However they do not need to learn a new programming language. In contrast to other template engines, patTemplate takes a declarative approach for the template tags, you will not find any if/else statements or for-loops in the templates.

patTemplate for the developer

If your designer is familiar with the patTemplate syntax, you will have to learn the PHP-API of patTemplate in order to assign the actual values of the placeholders to the template. If you are an experienced PHP developer you will easily grasp the API, as you will not need to learn a lot of new methods.

Getting Started

patTemplate allows you to split a page into several blocks, called templates. It requires you to at least specify one block that contains the complete page, the root template. Inside this template, you may nest as many templates, as you like. Each of these templates should have its unique name, so it can be addressed from your PHP application. To mark a template in your page, you need to enclose the HTML code in a <patTemplate:tmpl/> tag:

Loading this template from a file is easy. You only need to create a new instance of patTemplate and pass the filename to the readTemplatesFromInput method:

patTemplate will now open the file my-templates.tmpl and scan it for <patTeamplate:tmpl/> tags. It will create a structure like this:

If you want to send the HTML content to the browser, you need to call the displayParsedTemplate() method and pass the name of the template to display:

When parsing and displaying a template, all nested templates will be displayed as well. So calling this method will display:

If you do not want to echo the HTML code, but store it in a PHP variable, you may call getParsedTemplate() instead. If you do not pass the name of a template to displayParsedTemplate() or getParsedTemplate(), patTemplate will display the root template (i.e. the first template it read after creating the patTemplate object).

Chosing a directory for your templates

You will certainly not put your template files into the root directory of your webspace, but rather in a folder called templates or something similar. If you do not want to specify the full path to the files for every call to readTemplatesFromInput() you may use the setRoot() method:

This example will load the templates from the file /path/to/templates/my-template.tmpl.

The following pages will show you, how to add variables, or use different template types in your pages.

Adding variables to the template

Variables are placeholders in your templates that you may assign any value from your PHP application.

There are two types of variables in patTemplate:

  1. Local variables, that are only available in the template that they have been added to
  2. Global variables, that are available in all templates`

To place a variable in a template, you need to enclose the variable in curly braces. Variables may only consist of uppercase letters, number, dashes and the uderscore:

This template contains a variable called } that you may assign a value from your application.

Adding a local variable with addVar()

When adding a local variable, you have to use the addVar() method and pass the name of the template, where you want to add variable, the name of the variable as well as the value you want to assign:

This script will display:

Instead of a string, you may also pass an array containing several values. In this case, patTemplate will repeat the template to which the variable has been assigned for each entry on your array. Change only one line of code to add more than one name:

Now the script will display:

No need to create a for loop, neither in your PHP application, nor in your template file.

Adding several variables at once with addVars()

A template need not only contain one variable, it can contain as many of them, as you like:

Instead of two calls to addVar() you may also pass an associative array to the addVars() method:

This will add two variables (GREETING and NAME) to the template page and display:

It is also possible to assign more than one value to a variable using addVars():

This will display:

If you assign an array to one variable and a string to the other, patTemplate will use the same string for each iteration:

This example will display:

Adding rows of variables with addRows()

Often, you are confronted with record sets in the following structure:

If you want to create an HTML-table containing this information, you can use the addRows() method and the following template:

This page consists of two templates, the root template (page) and template, that should be repeated for each record set in your array (entry). To build a list containing all record sets, you only need to call one method:

The method accepts three arguments:

The method is perfectly suited to create lists from database result sets, like they are returned by PEAR DB's getAll() method.

Adding objects with addObject()

Instead of using an associative array, you may also work with an object instead.

Imagine, you are using the following class in your application:

And you created a template to display user information:

You may now pass instance of the User class directly to the template:

This will display:

patTemplate will extract all properties that are marked as public and add them to the specified template while prefixing them as you have seen in the addRows() example. If you do not want to declare your properties as public, you may as well implement a getVars() method in your class that returns an associative array containing the variables that should be added to the template:

The result will be exactly the same.

Adding global variables with addGlobalVar() and addGlobalVars()

If you want to use a variable in every template block of a page, it can get cumbersome to use any of the above methods to add this variable to every template. Instead, you may use the methods addGlobalVar() or addGlobalVars() to add the variable to every template in your page:

The variable {NOW} may now be used in all of your templates:

There are two differences between the methods for local and global variables:

  1. The global methods do not need the template name as the first parameter.
  2. The global methods do not accept an array as values of variables.

If a variable-name is used globally and locally, the local variable has precedence.

Further Reading

For more information on variables you might want to read:

Setting Default Values for Variables

When using the <patTemplate:var/> tag to include a variable in a template, it is possible to specify a default value, that will be used when no value is assigned to this variable from PHP. This can be achieved using the default attribute:

As long, as no value is assigned to the variable user, this page will display:

Using the return value of a function

Since revision [438] (or patTemplate 3.1.0a3), it is possible to specify a PHP function or a static method that will be used to generate the default value for the variable. Again, the default attribute can be used:

This way you can include the current UNIX timestamp without having to write PHP code. As this poses a security risk (your template designers my call any PHP function), you have to enable this feature, so it can be used in the templates:

To call a static method instead of a function, you need to specify the class name and the method name, separated by two colons:

The functions and methods will be evaluated, when the template is read from the file. You are not able to access the value of the variable from this function. This is what variable modifiers should be used for.

Accessing variables from other templates

There are two situations, in which you may want to access the variables from any other template:

  1. Display the value of the variable
  2. Use the value as a condition for a condition template

In both situations, you can use the dot-syntax to solve the problem.

Importing variables from other templates

To import one variable from a different template into the current template, you must use the <patTemplate:var/> tag with the copyFrom attribute:

PHP-Code:

Template:

In the above example, we are importing the variable TITLE from the template header into the template footer and name the imported value copiedVar. We could also apply a variable modifier to the copied variable. Since revision [437] it is also possible to use __parent.VARNAME to fetch any variable from the parent template without specifying the name of the template.

Using the dot-syntax in conditions

When creating a condition template you may use the dot-syntax in the conditionVar attribute:

The output of the footer template will now depend on the value you assign to the variable TITLE of the header template.

Creating templates

patTemplate allows you to split a page into several blocks, called templates. It requires you to at least specify one block that contains the complete page, the root template. Inside this template, you may nest as many templates, as you like. Each of these templates should have its unique name, so it can be addressed from your PHP application. To mark a template in your page, you need to enclose the HTML code in a <patTemplate:tmpl/> tag:

Loading this template from a file is easy:

patTemplate will now open the file my-templates.tmpl and scan it for <patTeamplate:tmpl/> tags. It will create a structure like this:

If you want to send the HTML content to the browser, you need to call the displayParsedTemplate() method and pass the name of the template to display:

When parsing and displaying a template, all nested templates will be displayed as well. So calling this method will display:

If you do not want to echo the HTML code, but store it in a PHP variable, you may call getParsedTemplate() instead. If you do not pass the name of a template to displayParsedTemplate() or getParsedTemplate(), patTemplate will display the root template (i.e. the first template it read after creating the patTemplate object).

Chosing a directory for your templates

You will certainly not put your template files into the root directory of your webspace, but rather in a folder called templates or something similar. If you do not want to specify the full path to the files for every call to readTemplatesFromInput() you may use the setRoot() method:

This example will load the templates from the file /path/to/templates/my-template.tmpl.

patTemplate also allows you to read the templates not only from the file system, but virtually [wiki:Docs/Advanced/Reader any data source].

Further reading

Of course, this is not all the functionality that patTemplate provides. patTemplate provides different types of templates, that come with different functionality:

Besides the tmpl tag there are [wiki:Docs/TagReference several other tags] and it is even possible to [wiki:Docs/Developer/CustomFunctions create your own tags].

The !SimpleCondition template

In nearly every application, there will be parts of the HTML frontend, that should only be displayed, if a certain information is available. One example could be a box, that displays information about the currently logged in user. It makes no sense, to display this box, if no user is logged in.

patTemplate helps you achieving this, by providing the simpleCondition template.

Take a look at the following template:

To add user information to this page, you need to use the addVars() method, like the following code snippet shows:

The problem is, that if there is no user logged in, that the HTML code for the user info box will still be displayed. This can easily be changed, by adding two attributes to the <patTemplate:tmpl/> tag:

By setting the type attribute to simpleCondition you are emulating an if-condition. The attribute requiredVars allows you to specify a variable that must be assigned a non-empty value in order for the template to be displayed. By setting this attribute to USER_ID you can force this template to be hidden, if no user-id has been passed.

Specifying more than one variable

It is also possible to specify more than one variable. In this case you have to set the attribute value to a comma-separated list of variable names. If any of the variables has a non-empty value, the template will be displayed:

In this example, the user-info box will be displayed, if either the username or the userid has been set.

Using global variables

If you want to display the userid and username in different places in your template, you might want to add it globally:

By ddefault, the simpleCondition template will check, whether the variable has been asigned locally. This can be changed, by setting the the useGlobals attribute to true:

Specifying a required value

It is not only possible to check, whether a variable has a non-empty value, but also to check, whether you assigned a specific value to a variable. Take a look at the following template:

The template admin-options should only be displayed, if the currently logged in user is an admin. So we change the PHP code, to pass this information to the template globally:

The getUserType() function should return either admin or user depending on the status of the currently logged in user. So it is not sufficient to only check, whether the USER_TYPE variable is set at all, but you need to check, whether it is set to admin. This can be easily accomplished:

This feature can be combined with the previously discussed feature that allowed you to specify more than one required variable.

The Condition Template

The simpleCondition template allows you to emulate a simple if-clause without the else-block. If that is not sufficient for your task, you may find the condition template helpful. It allows you to include full-fledged switch/case-blocks in your templates.

Predefined conditions

Using variables as a condition

Adding comments to templates

If your templates get more complex, you might want to document what you are doing, so it is easier for other developers or designers to comprehend the template structure. Of course you could just add simple HTML-comments to the templates, but these would be sent to the browser when displaying the page, which would result in additional traffic, although the information is not needed by the client.

To avoid this, patTemplate provides the <patTemplate:comment/> tag. All data inside this tag will be ignored when the page is displayed:

When reading and displaying this template, the result will be:

Using the comment tag has another advantage. Although the data inside the comment tags will not be displayed, patTemplate will read and interpret it. When debugging your templates? with the dump() method, the comments will be displayed next to the templates, that contained them.

Using options

patTemplate allows you to influence its behaviour by setting several of its options. To set an option, the setOption method can be used. It accepts two arguments:

  1. The name of the option
  2. The value of the option

Example:

Available options

The following table shows all available options:

|| Option || Description || Possible values || || maintainBc || Whether patTemplate should maintain backwards compatibility to version 2.x. If set to true you may use empty and default in <patTemplate:sub/> tags instead of !__empty and !__default || true or false || || defaultFunction || Name of the template function (i.e. user defined tag) that should be called if an unknown tag is encountered || any string || || allowFunctionsAsDefault || Whether it is allowed to specify a PHP function as a defaul value for variables. || true or false ||

Advanced features

patTemplate offers a lot more than just replacing placeholders in an HTML template.

Here you will find tutorials on the more sophisticated features:

Reading templates from various data sources

patTemplate is not limited to reading templates from the file system, but uses a driver based approach to read templates from virtually anywhere.

This driver-based approach has two benefits:

  1. Templates can be read from any data source
  2. Different drivers may parse a different template format

A driver to read templates is called a template reader. Currently, the following [source:trunk/patTemplate/Reader/ readers] are available:

The reader to use can be specified when parseTemplatesFromInput() is called:

If you want to use the file reader, the reader name is optional.

Reading templates from file

Reading templates from a file is the most common task. You may use the setRoot() method to specify one or more folders, where the templates are located.

Reading templates from a string

Reading a template from a string might be helpful, when you need to read a template from a source, that is not supported by patTemplate and implementing a new reader would be overkill.

All you need to do is pass the template source to the readTemplatesFromInput() method:

Reading templates from a database

When reading your templates from a database, the [http://pear.php.net/package/DB PEAR::DB] abstraction layer will be used. You need to pass the [http://pear.php.net/manual/en/package.database.db.intro-dsn.php DSN] string to the setRoot() method:

Imagine, your templates are stored in a table called templates that has to fields:

If you want to read a template called foo from the database, you may use to different ways. One would be passing the SQL statement to the readTemplatesFromInput() method:

However, if your table is that simple, you can let the reader build the query for you and use an XPath-like syntax:

This string consists of the following parts:

Reading HTML_Template_IT templates

The IT reader allows you to read templates in the [http://pear.php.net/manual/en/package.html.html-template-it.intro.php HTML_Template_IT or PHPLib] syntax. The reader itself works exactly like the File reader.

Using variable modifiers

Variable modifiers allow the template designer to modify the values that have been passed from PHP before they will be displayed to the browser.

Imagine the following PHP script:

The business-logic adds two values to the template, but both of them are quite problematic:

Both problems can be solved in the template alone:

There are two ways variable modifiers can be used:

If none of the modifiers included in the dsitribution solves your problem, you can easily [wiki:Docs/Developer/Modifiers write a new modifier].

Using more than one modifier

Since version 3.1.0a2 it is also possible to use more than one modifier per variable, by specifying a list of comma-separated functions.

Using the short-modifiers syntax

If you are familiar with the Smarty templating engine, you might prefer their syntax to specify a variable modfifier. patTemplate provides an input filter, that allows you to use the same syntax. It can easily be enabled:

You can be specify the variable modifiers in the following fashion:

Using a template cache

When using a template cache, patTemplate does not have to apply regular expressions to your template source for every request, but cache the result of the reader.

Using a template cache is extremely easy:

The following caches are available:

Each of these caches has different options, please refer to the API documentation of the cache to learn about the supported parameters.

How caches work

When enabling a cache, patTemplate will store a serialized array containing all templates, that have been read from a file in the cache. The next time you call readTemplatesFromInput(), patTemplate will first check, whether there is a cached version instead of reading the template from the file and evaluating all enclosed tags.

The template cache will not cache the output of your pages.

Working with output filters

Output filters can be used to transparently modify the resulting HTML that is generated by patTemplate. Output filters can either be applied to a single template or the complete HTML that is displayed when calling displayParsedTemplate().

Using an output filter for the generated page

To apply any output filter to all generated content, you may use the applyOutputFilter() method, which accepts the following arguments:

The following example would apply the Tidy output filter (requires ext/tidy) which can be used to create cleaner HTML:

You can apply more than one output filter, they will be executed in the order they have been applied.

What about getParsedTemplate()

When using getParsedTemplate(), the output filters will not be applied, unless you supply true as second parameter:

Applying an output filter to only one template

If you want to apply an output filter only to one template, you can use the outputFilter attribute of the <patTemplate:tmpl/> tag:

The filter will be applied to this template, regardless of using displayParsedTemplate() or getParsedTemplate().

Available filters

The following filters are included in the distribution:

All output filters are located in the [source:trunk/patTemplate/OutputFilter/ patTemplate/OutputFilter/] folder. You can also easily [wiki:Docs/Developer/OutputFilters implement new filters].

Working with input filters

Input filters are applied to the content of the template file before the reader analyses the tags. This enables you to modify the original HTML code and dynamically insert patTemplate tags or variables that will be interpreted by the template engine.

Using an input filter is extremely easy, you only need to pass the name of the filter to the applyInputFilter() method:

The StripComments input filter will remove all HTML and Javascript comments from the file, before it is anylyzed by patTemplate. This has two advantages:

  1. The reader is faster, as there is less HTML code to parse
  2. You can insert HTML comments between the opening <patTemplate:tmpl> and the opening <patTemplate:sub> tag. patTemplate does not allow any character data between these tags, but as the data is removed before patTemplate parses the file, it will not complain about this.

Currently patTemplate provides to input filters:

All input filters are located in the [browser:/trunk/patTemplate/InputFilter InputFilter] folder and you can easily [wiki:Docs/Developer/InputFilters implement new input filters].

Including external templates

patTemplate allows you to split your templates in smaller files to re-use templates in several pages. Imagine, you have a template for your page header, which is stored in header.tmpl:

Now, you want to re-use this template inside the template, that displays a page. This can be achieved using the <patTemplate:tmpl/> tag with the src attribute:

Now you can load the page-template as a normal template:

The loaded template structure now is:

As you can see, the header template is processed, as if the tag containing this template is nested in the header_include template. This means, that you can also assign variables to the header template, as if it were a normal template contained in page.tmpl.

Including standard HTML

Including with relative paths

Changing the source at runtime

Changing the namespace

patTemplate does not force you to place all of its tags inside the pat namespace. The prefix can easily be changed, by calling the setNamespace() method:

You can as well specify more than one prefix:

If you take a look at Joomla!, you will see, that they changed the default namespace to mos, but the tags are exactly the same.

patTemplate tag reference

All patTemplate tags have to be placed in the patTemplate namespace and thus prefixed with patTemplate, as long as you did not [wiki:Docs/Advanced/Namespace change the namespace]. So every tag must look like in the following example:

All tags and attribute names are case-insensitive.

The "tmpl" tag

The <patTemplate:tmpl/> tag is the main patTemplate tag. It is used to mark a block in a template which can be accessed from your PHP script.

Attributes

Required attributes are:

Optional attributes are:

Example

The "sub" tag

The <patTemplate:sub/>tag is used inside a <patTemplate:tmpl/> tag, if its type attribute is set to condition, OddEven, or modulo. It is used to define content that depends on different conditions.

Attributes

Required attributes are:

Optional attributes are:

The <patTemplate:sub/> tag does not suppport optional attributes.

Example

The "link" tag

The link tag works like a symlink on a UNIX system, it only references the content of a different template without creating an actual copy of it.

Attributes

Required attributes are:

Optional attributes are:

The <patTemplate:link/> tag does not suppport optional attributes.

The <patTemplate:link/> tag is always empty.

Example

The "var" tag

The <patTemplate:var/> tag can be used to insert a variable in a template. It adds some extra functionality to the plain variables that are inserted via curly braces.

Attributes

Required attributes are:

Optional attributes are:

Example

You should also take a look at the sections describing [wiki:Docs/Variables/DefaultValue default values for variables] and [wiki:Docs/Advanced/Modifiers variable modifiers].

The "comment" tag

The <patTemplate:comment/> tag can be used remove any text from the output. It is similar to an HTML comment, but will not even be outputted.

Attributes

The <patTemplate:comment/> tag does not support any attributes.

Example

Creating new tags

patTemplate allows you to create new tags and implement PHP code to handle them. See the [wiki:Docs/Developer/CustomFunctions developer documentation] for more information.

patTemplate FAQ

How can I create lists with the result of a database query?

Creating lists with patTemplate is quite easy, and it's even easier when you are using patTemplate in conjunction with patDbc! Let's take look at the template for a list:

Now imagine you've got a mysql table with three columns: id, superhero and real_name and you'd like to display a list with all entries from the table in the template above.

Of course you can use any other database abstraction layer or native PHP functions for database access - we used [http://pear.php.net/package/DB PEAR::DB] in this example. $db->getAll(...) just executes mysql_fetch_array() and collects all rows in one array that it returns. This array is just handed over to the template block list_entry using addRows(), and patTemplate automatically repeats this block, for the amount of rows contained in the array. This makes handling database results fun.

How can I create tables with several rows and columns?

This is a problem that often occurs, when you are creating lists with more than one columns? We refer to this problem as 'nested repetitions', as it's not only needed when creating to dimensional tables, but also nested lists. At first glance, it may seem quite hard, but once you've understood it, it's quite easy... At first, let's take a look at the template structure:

There are two templates, on called "row", which has to be repeated and one called "cell", which is repeated for all cells in each row. In these cells the content has to be displayed. To repeat the cells and the rows, use the following PHP code:

The most important function is parseTemplate( "row", "a" ), which parses a template and appends it to previously parsed contents of the template. This allows you to parse several rows.

Make use of array_chunk()

If you've already installed PHP 4.2.0 you may use array_chunk() to split the full data into arrays for each row.

How can I hide parts of a page?

Hiding parts of a page or displaying them only when a condition occurred is quite easy. Just take a look at the following example:

This example consists of two templates: page and secret, which will not be displayed if you call displayParsedTemplate() after loading this templates. It will not be displayed because of the visibility="hidden" attribute. If you went to display the page template, including the secret template, you may do this by using a PHP method of the patTemplate class called setAttribute. This method takes three arguments, the first is the name of the template for which the attribute should be set. The second is the name of the attribute and the last is the value of the attribute. To change the visibility of a template, use the following PHP code:

How do I build a drop-down menu with a database result?

Dropdown menus that let you choose between different options that result from a database query are often needed when building web-pages. To create them using patTemplate is quit easy. Take a look at the following template:

If you ignore the HTML code, the template is quite simple. Of course there is one template for the complete page, like it should be in every file. This template also contains the actual <select> tag, which creates a HTML drop down menu. Furthermore there is a second template called dropdown_entry. This template will be used to dynamically build the drop down list. The template type is set to condition as there may be two modes for each entry. Either it is selected by default or it isn't. To fill the drop down menu with entries resulting from database query you'll need the following code:

This will display a drop-down menu with all entries in the table heroes, the superhero with the id 19 will be selected by default.

Switching to radio groups

If you are using the technique of condition templates to print out to different versions for selected and unselected entries, you may switch the drop-down menu to a radio group without modifying the PHP code.

Can I re-use templates in different pages?

Of course you can. Let's say you'v got a footer and a header, which should be the same in all of your pages, so you have to change it only once and it will be updated in all pages. To accomplish this, at first create the two files, and save them to your template directory as header.tmpl and footer.tmpl. The templates could look like this:

and this

Now you may include these two files in all other pages by using the src attribute of the <patTemplate:tmpl> tag:

You may adress the header and footer templates as if the were written directly into the page but you have to change them only once, so this is some kind of include() for templates.

Organizing templates in folders

Of course you may also organzize templates in subfolders. If you'd like to put the shared templates in a subfolder of your template folder, just use <patTemplate:tmpl src="shared/header.tmpl" parse="off">. patTemplate will then load the template from ./templates/shared/header.tmpl if your basedir is set to templates.

Extending patTemplate

Starting with version 3.0, patTemplate has a more abstracted architecture, which allows you to add new or exchange components without modifying the core. To extend patTemplate you'll have to understand its internal structure and class trees.

Directory structure

The patTemplate directory structure was modeled after the PEAR concept. The main class patTemplate is located in the file patTemplate.php in the root folder (or in /pat if you installed it using the PEAR installer). This is the only file you need to include directly. You will also find a directory patTemplate which contains all modules of patTemplate. In this directory there's a Module.php file, which contains the class patTemplate_Module that acts as a base class for all different kinds of modules like Functions, Modifiers, Readers, etc. Furthermore you'll find a file for each of the modules that can be used in patTemplate like Reader.php, Function.php, TemplateCache.php, etc. These files contain the base classes for the modules you may create. In the patTemplate folder there are several folders, which help you organize the actual modules. The readers are in patTemplate/Reader, the functions in patTemplate/Functions, etc. That means, if you create a new modifier that should be used in the templates as FooMod, you will have to place it in a file called patTemplate/Modifier/FooMod.php otherwise patTemplate will not be able to locate it.

Class trees

patTemplate is fully object oriented code. That means all patTemplate modules have to be classes. Most of the classes are quite simple and you only have to implement one or two methods. But nevertheless they have to be classes, as they must not pollute the global namespace. The files and directories map directly to the class names. That means, patTemplate.php contains a class called patTemplate and the file patTemplate/Reader.php contains the class patTemplate_Reader. If you create a reader that should be able to read templates from a database, you should place it into patTemplate/Reader/DB.php and call the class patTemplate_Reader_DB. If you do not follow these simple rules, patTemplate will currently not be able to load and instantiate the module and your application will break.

Components

patTemplate consists of the following component types.

Variable Modifiers

Variable modifiers allow you to apply PHP functions and methods to variables without writing any PHP code. Once you provide a modifier, the template designer may easily use it in the templates. Variable modifiers may be used to apply htmlspecialchars() to your vars, as well as creating images and reversing text.

Template Readers

By default, patTemplate is reading templates from the local filesystem. But maybe you prefer storing the templates in a database or even shared memory. This is possible by creating a new Template Reader. Readers also allow you to 'assimilate' foreign template systems. patTemplate comes with a reader that is able to interpret [http://pear.php.net/package/HTML_Template_IT HTML_Template_IT] (and PHPLib) templates and treat them like normal patTemplate files.

Output Filters

Output Filters allow you to modify the resulting HTML code, before it is sent to the browser. Possible use cases are the removal of unneeded whitespace or even compressing the output, if the client supports gzipped content.

Input Filters

Input Filters are applied before the reader analyses the templates. This allows you to uncompress data, that is stored in gzipped format or remove comments that you do not need in the templates and thus improve the performance of the reader.

Custom Tags/Functions

Custom Functions allow you to create new tags for the patTemplate namespace. You have to write a class that will handle the tag whenever it occurs in the template. This enables you to dynamically include any kind of dynamically generated content in your templates.

Template Caches

The template cache will speed up you patTemplate powered sites. It will store the structures returned by the reader in a serialized format that can be read faster than the original templates. patTemplate comes with a cache that stores the cache files in file system, but you can store them virtually anywhere.

Template Dumpers

The Dump helps you debugging you templates as it presents a human readable interpretation of the internal structures that includes all templates, conditions, modifiers but also the variables that have been set. The initial version features a DHTML Dump, but you may create a dump that displays plain text, XUL or whatever you like.

Variable Modifiers

Variable modifiers give power to the template designer. Assume you pass a very long text to a variable but in the layout the designer only has space for a short teaser text. Using modifers, the designer may apply a Truncate modifier that shortens the text you pass in your PHP script. And this is only one application for variable modifiers.

Introduction

Applying modifers is really a piece of cake. All you have to do is to use the <patTemplate:var/>tag instead of only enclosing the variable in { and }. Then you may use the 'modifier' attribute to set the modifier.

Variable modifiers will be applied to the value of a variable when parsing the template. There two types of modifiers:

Custom Modifiers

Custom Modifiers are subclasses of patTemplate_Modifier and have to be placed inside patTemplate/Modifier. The filename has to match the last part of the classname. That means if you would like to create a filter that truncates sentences you will have to create a new class 'patTemplate_Modifier_Truncate' and place it into 'patTemplate/Modifier/Truncate.php'. The class has to implement one method modify( string value, array params ) that has to return the modified value. You may do whatever you like inside this method to modify the value. patTemplate will pass two parameters to your method:

The truncate modifier could look like this:

If you copy this file to the Modifier folder, you may instantly use it in your template files, by specifying it in the modifier attribute of any <patTemplate:var/> tag.

If you now pass a value that is longer than 50 chars, the modifier will automatically truncate it, before inserting it into the template.

Template Readers

Template readers are used to create the internal template structures from any string that contains <patTemplate:.../> tags. patTemplate ships with two readers, one that is able to read from files and one that reads directly from strings.

Reading from any datasource

If you would like to store your templates anywhere else, you can simply create a new reader. Just create a new subclass of patTemplate_Reader and place it into the reader directory. You need to implement at least one method: readTemplates(). patTemplate will call this method, whenever the user calls patTemplate::readtemplatesFromInput() and will pass the unique identifier for the template to read. This can be a filename, a URL or the value of a primary key in a database. After reading the template, you will have to return an array, that contains the template structure. In most cases you will be able to use patTemplate_Reader::parseString(), which will apply regular expressions to split the template source into several blocks and interprets all tags.

If you want to support the parse="off" functionality for external templates, you will have to create a second method called loadTemplate(). This method will receive a unique identifier and should return the data associated with it as a string. In the above example, you would just strip the call to parseString().

Possible readers

Other template engines

Readers may also be used to read templates that have been created for other template engines than patTemplate. We already delivered a reader, that is able to read templates that have been created for HTML_Template_IT and treat them like patTemplate templates. If you want to implement a reader for other engines, you'll have to make yourself familiar with the internal structure of patTemplate. We'll post more information on this subject at a latter point.

Caching

patTemplate supports caching of the returned templates structures. As the caching is still in beta state and the internal plugin API may change, documentation on this topic will follow, once the API is stable enough.

Output Filters

Output Filters allow you to modify the output, after all variables have been added and the template has been parsed. You could use it, to remove unecessesary whitespace, compress the output or obfuscate all email addresses.

Creating you own output filter

An output filter has to be a class that extends from patTemplate_OutputFilter. You have to place the file that contains your filter in the folder patTemplate/OutputFilter. In this class you only need to implement one method called apply(). This method will be called by patTemplate when patTemplate::displayParsedTemplate() is called by the script. Before the resulting HTML code is sent to the browser, your filter will have the oportunity to modify or filter the resulting HTML. The apply method has to accept one string parameter, in which it will receive the HTML code. After modifying it, you just have to return to modified HTML.

A simple example

The following example shows how to implement an output filter, that removes all linebreaks and extra spaces, indentations, etc. from the HTML code before sending it to the browser. The class has to be placed in the file patTemplate/OutputFilter/StripWhitespace.php (actually it already is there as this example is included in the distribution).

Applying output filters

Applying an output filter is an easy task. You just have to call one method on your patTemplate object and pass the desired output filter. You may create a filter chain by applying as many output filters as you like. If you applied more than one filter, the will be called in the same order as you applied them.

Passing parameters to the filter

You may also create an output filter that can be parameterised by the script that applies the filter. If the filter class needs to access the parameters set by the script, you may use the method patTemplate_OutputFilter::getParam(). When applying a filter, all parameters have to be passed as an array in the second parameter of patTemplate::applyOutputFilter().

Input Filters

Input Filters are similar to Output Filters but are used in a totally different context. The let you filter the templates after they are read from the filesystem, database or any other location, but before the template is being parsed and analyzed.

Why input filters?

You may use input filters for various tasks. You could strip all whitespace from you templates to speed up the parsing process, remove unneeded comments or unpack templates if they are stored in zipped format. You may also use it in some special cases, where you need to modify the templates but are not able to modify them in their original storage location.

Implementing an Input Filter

Implementing an Input Filter is exactly the same as creating a new Output Filter. You have to extend a new class from patTemplate_InputFilter and place it in a file in the patTemplate/InputFilter directory. The last part of the class name has to be identical to the name of the file. In this class, you simply have to implement one method:

patTemplate_Reader will pass the template code to this method before it is analyzed by the lexer and you may modify it according to your needs.

A simple example

The following example strips HTML comments from the templates before they are analyzed. This allows you to place them between the <patTemplate:tmpl> and <patTemplate:sub>tags, although it is not allowed to place data there.

Applying input filters

Applying an input filter is an easy task. You just have to call one method on your patTemplate object and pass the desired output filter. You may create a filter chain by applying as many input filters as you like. If you applied more than one filter, the will be called in the same order as you applied them.

Passing parameters to the filter

You may also create an input filter that can be parameterised by the script that applies the filter. If the filter class needs to access the parameters set by the script, you may use the method patTemplate_InputFilter::getParam(). When applying a filter, all parameters have to be passed as an array in the second parameter of patTemplate::applyInputFilter().

Custom Tags

Custom functions allow you to create new tags, and define how they should be handled. This way, you may hand over tools to the template designers, that they may use to insert any dynamic content. Think of a site, where your users may register as users and login with their usernames. You could create a new tag that retrieves the name from the database and displays it in the template. Other examples include a gettext implementation.

Using custom functions

Using a custom function is as easy as eating cheese cake. They can be used like the builtin tags tmpl, sub, var, etc.

This will output "Today is [current date].", where [current day] will be replaced with the current date.

In the above example, the PHP code enclosed between the <patTemplate:phpHighlight> tags will be syntax highlighted in the output.

Creating a custom Function

Custom Functions have to be placed in patTemplate/Function and extended from patTemplate_Function. You have to implement one method that represents the function: string patTemplate_Function::call( array params, string content ) The reader will pass an associative array containing all attributes of your tag as well as a string as second parameter, which will contain all character data (and HTML tags) between the opening and closing tags. In this method you may compute the result and return it as a string. This result will then be inserted in the template instead of your function tag as well as the enclosed content. You may use all functions, that are located in the patTemplate/Function folder, as patTemplate will auto-load the classes. Template functions will be evaluated while analyzing the template, there's currently no way to use template variables or any input from the PHP script in the funcitons. Functions may be nested, patTemplate will always evaluate the innermost function first.

Code examples

This example is the code used for the custom function time, which is able to display the current time as well as reformat any timestamp you pass to this.

Template Caches

The template cache has been developed to speed up patTemplate based applications. It will save you the overhead of analysing the template files, for every request. Instead, it will serailize the result of the reader and store it anywhere you like; on the next request to the same template, it will check, whether the file is still valid and load it from cache.

How does it work?

When you are calling patTemplate::readTemplatesFromInput(), patTemplate will include and instantiate the desired reader which will then load and analyze the template you specified. This will be done everytime the template is requested although the process is not influenced by any variables or user feedback. This technique has two drawbacks:

  1. The reader class consist of 1400+ lines of code, which have to be compiled
  2. The reader makes use of preg_* functions, which can get time consuming

To get rid of these performance brakes, I implemented the template cache, which implements a quite simple functionality: After the reader analyzed the template and returns an array containing the structure, the template cache will serialize this structure and store it with a unique key. On the next request, patTemplate asks the template cache, whether there's a stored structure for a specific key. If yes, it will be usnerialized and used instead of reading the template again.

Using a template cache

Like all patTemplate modules, using a template cache is easy. Basically, you just need to add one line of code to your scripts.

The first parameter in the call to useTemplateCache() defines which cache should be used. if you are unsured, which caches you have installed, take a look at the folder patTemplate/TemplateCache. The second parameter is an array with all parameters for the template cache. You'll have to check the documentation of the template cache you are using for a list of all supported parameters.

In the example that uses the 'File' cache, there are two parameters:

Creating a new template cache

patTemplate ships with a template cache, that stores data on the filesystem. If you need a faster storage container, like shared memory, you may easily implement it. Create a new file in patTemplate/TemplateCache and create a class, that extends patTemplate_Cache. In this class, you only need to implement the following methods:

The load() method will receive a unique key as well as the time, when the original file has been modified, if the reader supports this feature. You will have to check, whether there is a cache file for the specified key and whether it still is valid. If the file is valid, you will have to unserialize the stored data and return the resulting template structure to patTemplate. The write() method will receive the unique key, as well as the template structure, that has to be stored. Just serialize it and store it with the key, so it can be loaded at a later point.

Take a look at the code

To fully grasp, how the template cache works, take a look at the 'File' cache:

As you can see, implementing a template cache is really simple and should not pose a problem to the experienced PHP developer

Template Dumpers

Dumpers help you with debugging your application, as they display information about the loaded templates and assigned variables. patTemplate has been developed to help solve the webproblem and the output is most of the time displayed in the webbrowser. That's why we provide a dump that displays a nice (and interactive) HTML rendition of patTemplate's properties.

Writing a new Dump

If you are using patTemplate in a CLI environment or do not like the style of the Dump we provide, you may implement your own Dumper object. Just follow the following steps:

  1. Create a new file in patTemplate/Dump
  2. Create a new class in this file, that extends patTemplate_Dump
  3. Implement the needed methods: displayHeader(), displayFooter(), dumpGlobals() and dumpTemplates()

The methods displayHeader() and displayFooter() do not accept any parameters. The dumpGlobals() method will receive an array with all global template variables. The method dumpTemplates() will recieve two arrays, one with the template structures and content and one with the variables, that have been assigned.

Make use of print_r()

To get familiar with the structures passed to the Dump object, we recommend to use print_r() or var_dump() on the parameters.

All versions of pat-template with dependencies

PHP Build Version
Package Version
Requires php Version >=5.3
pear/pear-core-minimal Version ^1.0
wernerwa/pat-error Version ^1.1
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package wernerwa/pat-template contains the following files

Loading the files please wait ....