Table of Contents

## Templates

You can reconfigure the look and feel of phpLens grids using templates. Template files are created with a .tpl extension and are compiled into .php files. Templates are only available in the Advanced and Enterprise versions. If you are not sure what templates can do, see the edit template example below.

Templates use the Smarty Template Engine, an Open Source software by Monte Ohrt (monte@ispi.net) and Andrei Zmievski (andrei@ispi.net). Information on Smarty can be found at http://smarty.php.net/ and the English docs.

### Installation

PHP 4.0.6 or later is recommended for Smarty.

In all directories where you are using phpLens templates, create a templates directory, configs directory and a templates_c directory. Be sure the templates_c directory is writable by your web server user (usually nobody).

     chown nobody:nobody templates_c; chmod 700 templates_c

You can also chmod 777 this directory, but be aware of security issues for multi-user systems.

Your template files should be placed in the templates directory, and they will be compiled into .php files in the templates_c directory by phpLens.

### Some Tips on File Locations

If you have your php scripts that use phplens objects in both /htdocs/php1 and /htdocs/php2, then you create config and template directories in both php1 and php2 as follows:

     /htdocs
     	php1
    		configs
    		templates
    		templates_c
    	php2
    		configs
    		templates
    		templates_c

If you have a script that uses an edit template (called edit.tpl) in /htdocs/php1/p1.php, then the template is stored in /htdocs/php1/templates/edit.tpl. The templateEdit property should be set to

`$lens->templateEdit = 'edit.tpl'`

without the directory path. The important thing to remember about phpLens is that all template file searches are relative to the location of the php script which calls the $lens->Render() function.

You can modify the directory that phpLens uses to search for a template by setting $lens->templateBaseDir. For example, if you want all templates to be stored in /htdocs/smarty/templates:

    /htdocs
    	smarty
    		configs
    		templates
    		templates_c
    	php1
    	php2

Then you set

`$lens->templateBaseDir = '/htdocs/smarty';`

Note: If you are using phpLens applets, then you should use the templates directory automatically created for you in the applet directory.

### Usage

Fields from a database are inserted into a template by replacing all tags of the form: {$FIELDNAME} with the field values. The tag must be in uppercase.

All fields are processed in a pipe-line before they are merged into template tags.

Without powerLens, the pipeline start with any lookups (eg. converting country codes from 'ru' to 'Russia'), then performs default html formatting. This forces numbers to align right, and changes empty strings to &nbsp; as shown below:

      database fields --> lookups --> html formatting --> template merging
       field['PRICE']                                            {$PRICE}
          4.95                                        <div align=right>$4.95</div>

       field['NAME']                                             {$NAME}
           ""                                                     &nbsp;

With powerLens, we pass the raw data after lookups (eg. converting state codes from 'NY' to 'New York') to the powerLens processor:

      database fields --> lookups --> powerLens processing --> template merging
       field['PRICE']                  <b>${PRICE}</b>             {$PRICE}

          4.95                          <b>$4.95</b>             <b>$4.95</b>

When the data arrives at the template, the data has been formatted for presentation. This means to get the raw values, the html tags will have to be stripped. This can be done with the standard PHP function `striptags()`. And to check if the field is an empty string, a comparison with `&nbsp;` will have to be made.

### Extending Smarty

The phpLens template engine is based on Smarty. The Smarty engine supports many sophisticated features, including conditional if's (see edit example below).

Smarty has also been extended to support printing global variables. For example to access a global called $PHPGLOBAL we would use: `{print_global name="PHPGLOBAL"}`

You can replace the Smarty Template Engine with your own engine by modifying the file phplens-template.inc.php, which is a wrapper around Smarty.

### Regenerating Templates

By default, tempalte files are automatically recompiled provided the Web server process is able to write to the template_c directory.

### Grid Templates

Every row of the grid is treated as a separate template invocation using the template file defined in `$lens->templateGrid`. For example, `$lens->templateGrid = 'grid.tpl';` means that the './templates/grid.tpl' file will be compiled into './templates.php/grid.tpl.php' and executed for every row of the grid.

The field names (in uppercase) are available as variables containing the html formatted data. The field names with '_T' appended (eg. {$FIELDNAME_T}) hold the field titles defined in phpLens.

The following template variables are also available although they are probably not needed as the edit and delete buttons are automatically generated for you outside the template.

- _ID_ contains the phpLens id you define when you create the phpLens object (since 2.7.1).
- _DELETE_ contains the delete button code.
- _EDIT_ contains the edit button code.
- _RECNO_ contains the current record number.
- _PRIMARY_ is the urlencoded primary key (or the compound key packed in a special format).

An example template file could look like this:

    <table>
    <tr>
     <td>{$NAME_T}: {$NAME}</td><td>{$TEL_T}: {$TEL} </td>
    </tr>
    </table>

The grid template is for one record. The above example shows the template as a table embedded into a cell with a colspan=2. Alternatively, you can (since 2.8.3) define the grid template as a series of html td tags. The number of td tags must match the number of field columns displayed in the grid.

The grid header is provided with its own template: `$lens->templateGridHdr`. You can define it as a table or a set of th tags.

The forums at http://phplens.com is an example of grid template usage.

### Detail Templates

Every detail table is treated as a separate template invocation using the template file defined in `$lens->templateDetail`.

The field names (in uppercase) are available as variables containing the html formatted data. The field names with '_T' appended (eg. {$FIELDNAME_T}) hold the field titles defined in phpLens.

The following template variables are also available:

- _ID_ contains the phpLens id you define when you create the phpLens object (since 2.7.1).
- _DELETE_ contains the delete button code.
- _EDIT_ contains the edit button code.
- _RECNO_ contains the current record number.
- _PRIMARY_ is the urlencoded primary key

Example 303 at the phpLens Web site is an example of detail template usage.

### Layout Templates

If you want to control the layout of the captions, menus, and position of the grid and detail tables, you can do so with the layout template (`$lens->templateLayout`).

The following variables are available:

- _ID_ contains the phpLens id you define when you create the phpLens object (since 2.7.1).
- COLORNAVBORDER The color of the navigation menu background.
- LAYOUT_ATTR Holds the layout table attributes, including bgcolor. A synonym for {$LAYOUT_ATTR} is {$COLORBACKGROUND} for historical reasons.
- TOPCAPTION
- BOTTOMCAPTION
- GRIDDATA an array holding an the html for each column
- DETAILDATA the html for the details of a row
- PAGENO the current page number
- NAVMENUS the menus
- ERRORMESSAGES where to display error messages (see also templateShowErrors).
- FILTERFORM which holds the search/filter form (requires $lens->templateLayoutAddFilter to be set to true).

A sample that mimics the phpLens standard layout:

    {if strlen($ERRORMESSAGES)>0}
    {$ERRORMESSAGES}
    {/if}
    <table {$LAYOUT_ATTR} border=0 cellspacing=0 cellpadding=1>
    <tr><td>
    	<table bgcolor={$COLORNAVBORDER} width=100% border=0 cellspacing=0 cellpadding=0>
    	<tr><td>   {$TOPCAPTION}</td><td align=right>{$NAVMENUS}</td></tr>
    	</table>
    </td></tr>
    <tr><td>
    <table border=0 width=100% cellspacing=0 cellpadding=0>
    <tr>
     	{section name=cols loop=$GRIDDATA}
     <td valign=top>
    	{$GRIDDATA[cols]}
     </td>
     	{/section}
     {if strlen($DETAILDATA)>0}
     <td valign=top>{$DETAILDATA}</td>
     {/if}
     </tr>
    </table>
    </td></tr>
    <tr><td>
    	<table bgcolor={$COLORNAVBORDER} width=100% border=0 cellspacing=0 cellpadding=0>
    	<tr><td>   {$BOTTOMCAPTION}</td><td align=right>{$NAVMENUS}</td></tr>
    	</table>
    </td></tr>
    </table>

### Edit and New Templates

Separate templates are provided for edit (`$lens->templateEdit`) and new (`$lens->templateNew`) record.

The input fields are available as variables containing the data {$FIELDNAME}. The field names with '_T' appended (eg. {$FIELDNAME_T}) hold the field titles defined in phpLens. The fields values are available as field names with '_VALUE' appended (eg. {$FIELDNAME_VALUE}).

Other variables:

- _ID_ contains the phpLens id you define when you create the phpLens object (since 2.7.1).
- _FORMBEGIN_ This holds the <FORM> tag and should be the first template tag. Do not define the form tag yourself as attributes and hidden input tags are also added here.
- _FORMEND_ This holds the </FORM> tag and should be the last template tag. Do not define this tag yourself.
- _CAPTION_ The edit or new caption from the language file (since 2.7.1).
- _SUBMIT_ The Submit button.
- _CANCEL_ The Cancel button.
- ERRORMESSAGES where to display error messages (see also templateShowErrors).

### Edit Template Example

Suppose we don't want to use the default edit screen and want to define our own edit screen. In your PHP code add the templateDetail property:

    	$id = 'tpldemo';
    	$sql = 'select NAME,PHONE from USERTABLE';
    	$lens = PHPLensConnect($id,$sql,...);
    	$lens->templateEdit = 'edit.tpl';
    	$lens->Render();
    	$lens->Close();

The bolded line sets the templateEdit property. This will cause the following "edit.tpl" file which is stored in the template subdirectory of that page to be loaded when any record is edited. The tpl file could look like this:

    	<html><body>
    	<table border=1><tr><td>
    	<h1>Edit</h1>
    	{$_FORMBEGIN_}
    	{if $NAME_VALUE == "Nelson Mandela"}
    		<img src='/img/mandela.jpg'><hr>
    	{/if}

    	{$NAME_T}:  {$NAME}<br>
    	{$PHONE_T}:  {$PHONE}<br>
    	{$_SUBMIT_} {$_CANCEL_}<br>

    	{$_FORMEND_}
    	</td></tr></table>
    	</body></html>

This will cause phpLens to ignore its default Edit screen and use the above screen defined in the tpl file for editing. Note that the template has an IF condition, so if Nelson Mandela is being displayed, his picture is also shown. The following HTML is seen by the end-user in the Web browser:

# Edit Name: Phone:

The variables used in the tpl file are summarized below:

    	Title Variables
    	===============
    	$NAME_T = 'Name'
    	$PHONE_T = 'Telephone'

    	Input Text Variables
    	====================
    	$NAME = <input type=text name=lens_FC_NAME value='Roberto Baggio'>
    	$PHONE = <input type=text name=lens_FC_PHONE value='706-1216'>

    	Raw Contents of Fields
    	======================
    	$NAME_VALUE = 'Roberto Baggio'
    	$PHONE_VALUE = '706-1216'

    	Buttons
    	=======
    	$_SUBMIT_
    	$_CANCEL_

    	FORM tags
    	========
    	$_FORMBEGIN_ = <form><input type=hidden name=... value=...>
    	$_FORMEND_ = </form>

### Filter Form Template

The filter form template (set by $lens->filterTemplate) has most of the variables of the edit and new record templates.

- _ID_ contains the phpLens id you define when you create the phpLens object (since 2.7.1).
- _FORMBEGIN_ This holds the <FORM> tag and should be the first template tag. Do not define the form tag yourself as attributes and hidden input tags are also added here.
- _FORMEND_ This holds the </FORM> tag and should be the last template tag. Do not define this tag yourself.
- _CAPTION_ The filter caption from the language file (since 2.7.2).
- _SUBMIT_ The Submit button.
- _CANCEL_ The Cancel button.
- _FILTERTEXT_ The filter checkboxes (match beginning, match anywhere, etc).

### Generating Template Skeletons

If you set $lens->debug = -1 the detail grid and the edit/create forms will appear as Smarty template skeletons on which you can base your template design.