Table of Contents

Templates

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

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

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

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   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;                             

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

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

Extending Smarty

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

Grid Templates

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 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

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

Layout Templates

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

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();

	<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

• _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.

This documentation system is maintained using phpLens