Table of Contents

Applet Builder

New is phpLens 2.0 is the Applet Builder, also called the Builder. This is an improved Grid Builder from version 1.0 of phpLens. In this version, instead of generating code in a browser window, it saves the source code on your web server as multiple php files.

Advantages

These php files are called applets and they run faster than the old style phpLens objects because they do not query the phplens table in the database. Also unlike the older gridbuilder, you do not need to manually merge any PHP code changes yourself. PhpLens will merge the code for you!

Installation

You need to check the following to make sure it is working.

a. Define APPLETS_DIR

In your phplens.config.inc.php file make sure the following line is defined:

if (!defined('APPLETS_DIR')) define('APPLETS_DIR',PHPLENS_DIR.'/builder/applets');

b. Allow your web server to save files in the phplens/builder/applets directory.

For example on Unix:

 chmod -R a+rw phplens/builder/applets

c. Configure the $PHPLENS_DATABASES variable

Scroll to the bottom of the file PHPLENS_DIR/config/phplens.config.inc.php and search for the following array variable: 

$PHPLENS_DATABASES = 
   array( //driver, server, userid, pwd, database
   'northwind' => array('access','nwind','','',''),
   'phplens data' => array('mysql','phplens','root','password','phplens')
   );

This lists out all the databases that the Grid Builder can access. The key is the name to display (eg. northwind), and each array element consists of the following array($driver, $server, $userid, $password, $database). Legal database drivers include 'mysql', 'postgres', 'postgres7', 'mssql', 'sybase', 'oracle', 'oci8', 'access', 'vfp', 'odbc', 'ibase'. Refer to ADODB readme.htm file for more information on database drivers.

d. Use phplens/builder/grid/ to create new applets.

Select the database to connect to, and the table you want to display. After you are happy with the settings, enter a name for the applet you want to create in the text box provided at the bottom of the screen, and click on the Save button. In the example below, we are creating an applet called country.

To view all applets in the directory, go to phplens/builder/, and you will see the following user interface. In this case we have just clicked on the CaseContac applet and are viewing the phpLens table.

To access an applet, say CaseContac, from your main file:

<?php
include_once('/path/to/phplens.inc.php');
session_start();

include_once(APPLETS_DIR.'/objs/CaseContac.inc.php');
?>

You can also move the whole CaseContac directory to another location once the applet has been created provided the PHPLENS_DIR constant which points to the location of the phplens directory is predefined, perhaps to /htdocs/casecontac. It will not be visible in the Builder anymore, but this prevents too many applets from cluttering up the builder. To access the applet from your main PHP file, use:

include_once('/htdocs/casecontac/CaseContac.inc.php');

IDE

A simple IDE is also provided where you can load files, edit and save them. This is not a substitute for a real editor, but a useful tool for last minute changes. To use this tool, you will need to set the phplens/builder/ide/ directory to read/write also.

Files Created

Three files are created for any applet:

phplens/builder/applets/objs/applet.inc.php

This is the include file you include in your main php file

phplens/builder/applets/objs/applet.imp.inc.php

This is the phpLens implementation file that is always overwritten every time you make a change to phpLens using the dynamic editor. You can still add simple properties in the file such as 

$lens->canEdit = true;

but avoid adding properties that are dynamic such as

$lens->canEdit = ($GLOBAL_ADMIN) ? true : false;

because phpLens cannot recreate the conditional expression when regenerating the code. Place such code in the applet.inc.php file instead. See example below:

phplens/builder/applets/objs/applet.imp.inc.php.bak Backup of previous implementation file, in case you need to revert changes!

Any minor code changes can be made in applet.inc.php without worrying that phpLens will overwrite the code. We never modify it after it has been created. To use the applet, just include applet.inc.php in your main php file.

Global Changes

If you want to change the a property that affects the behaviour of all applets, change the following function:

function SetLensAppletGlobal() in

phplens/builder/applets/init/setlensappletglobal.inc.php

Backward Compatibility

You can still use the old phplens/gridbuilder. Everything will still work.

Example Include File

Here is the country applet country.inc.php file: 

<?php
// Version: 1.9.2  (D0.02).  Generated: 2002-Feb-16 16:56:10
// Visit http://www.phplens.com for more info & updates on PHPLens

//-------------------------------------------------------------------------- definitions
define('LENS_DB_country','dbphplens'); // database to connect to from 
                                       // phplens.config.inc.php
//-------------------------------------------------------------------------- includes
include_once(APPLETS_DIR.'/init/init.inc.php');
require_once(dirname(__FILE__).'/country.imp.inc.php');
//-------------------------------------------------------------------------- session setup
if (empty($DB))  {
	$DB = &LensDBConnection(LENS_DB_country);	
}
//-------------------------------------------------------------------------- functions
function SetLensApplet_country(&$lens)
{
	$lens->templateBaseDir = dirname(__FILE__);
	SetLensAppletGlobal($lens);
}
//-------------------------------------------------------------------------- implementation

PhpLensApplet_country($DB,false /* do not return Object */,!defined('PHPLENS_NOEDIT'));

//-------------------------------------------------------------------------- footer
?>

Note that the global variable $DB contains the database to connect to. You can declare it yourself, otherwise it will take the database defined in $PHPLENS_DATABASES.

The function SetLensApplet_country is always called by the country applet before any settings are processed. So this is the ideal place to a dynamic setting such as the following:

function SetLensApplet_country(&$lens)
{
global $GLOBAL_ADMIN;

	$lens->templateBaseDir = dirname(__FILE__);
	SetLensAppletGlobal($lens);

	$lens->canEdit = ($GLOBAL_ADMIN) ? true : false;
}

Also note that SetLensAppletGlobal( ) is called by SetLensApplet_country( ). This allows you to globally set a property for all applet objects by modifying the function in the file applets/init/setlensappletglobal.inc.php.

The function PhpLensApplet_country(&$DB,$returnLens,$dynEdit) at the very bottom of the country.inc.php does the real work of creating the applet, and is defined in country.inc.imp.php. It takes 3 parameters:

Example Implementation File

Meanwhile, the country.inc.imp.php implementation file might look like this:

<?php
   // Version: 1.9.2 (D0.02). Generated: 2002-Feb-16 16:56:10
   // Visit http://www.phplens.com for more info & updates on PHPLens
   ####################################################################### 
   # DO NOT MODIFY CONTENTS OF THIS FILE. IT IS OVERWRITTEN
   # EVERYTIME YOU MAKE A CHANGE TO THIS PHPLENS OBJECT!
   ####################################################################### 
# Internal query interface to Applet to find out available functionality
function PhpLensAppletQuery_country($ask)
{
   switch ($ask) {
   	case 'PATH': return dirname(__FILE__);
   	case 'VERS': return 1;
   	case 'DB': return 'LENS_DB_country';
   	default: return false; # VERS==0, this was missing
   }
}
   
function &PhpLensApplet_country(&$DB,$returnLens=false,$dynEdit=true)
{
   $lens = new phpLens('country',$DB,"select * from cities");
   if (! $lens) LensDie('PHPLens country failed to start','Applet','LENSERROR_SEVERE');
   $lens->dynUseSession = false; 
   $lens->dynEdit = $dynEdit;
   $lens->menuHide = ';END'; 
   $lens->keyTable = 'cities'; 
   $lens->urlParams = '#LensBM_country';
   $lens->filterAnyWhere = false;
   $lens->overrideFunction='SetLensApplet_country'; // remember to pass by reference!
   //-----------------
   // Generate HTML
   $lens->Render();
   $lens->Close();
   return ($returnLens) ? $lens : false;
}
?>

Note the overrideFunction = 'SetLenApplet_country'; setting above, which tells phpLens to call the function that we saw was defined in country.inc.php above. This is how the implementation file country.imp.inc.php is linked to the include file country.inc.php.

Modifying Applets

Modifying All Applets Globally

Suppose I have paid the shareware license to display the nice calendar that appears next to all date fields. This means I can legally set the property showCal to true. Now I want to globally enable this feature. I would modify the function SetLensAppletGlobal( ) in the file phplens/builder/applets/init/setlensappletglobal.inc.php to: 

function SetLensAppletGlobal(&$lens)
{
	$lens->showCal = true;   
}

Now all applets would have this property set.

Modifying One Applet Property

We saw one example of modifying applet properties with canEdit above. We cover this difficult topic in more detail here.

Normally, clicking on the column titles of the phpLens grid allows you to sort the data based on the clicked field. But suppose I have this applet which returns data from a very large table, and sorting the data based on clicking a title would take several minutes and slow the database server to a crawl. So I might want to disable column sorting for that applet.

I would modify country.inc.php:

function SetLensApplet_country(&$lens)
{
	$lens->showSort = false;
	$lens->templateBaseDir = dirname(__FILE__);
	SetLensAppletGlobal($lens);
}

Now here is the tricky part. Although you are specificly warned not to modify the implementation file, for property settings which never change (are constant), you can alternatively place such changes in the country.inc.imp.php.

function &PhpLensApplet_country(&$DB,$returnLens=false,$dynEdit=true)
{
   $lens = new phpLens('country',$DB,"select * from cities");
   if (! $lens) LensDie('PHPLens country failed to start','Applet','LENSERROR_SEVERE');
   $lens->showSort = false;
   $lens->dynUseSession = false; 
   $lens->dynEdit = $dynEdit;
   $lens->menuHide = ';END';

An example of a dynamic property setting that you must place in the country.inc.php is one where you check a GET variable, and based on the GET variable, you modify your SQL statement to add an extra where condition. Because it is dynamic, it has to be defined in the function SetLensApplet_country.

If the GET variable $state is defined, you change the SQL statement to "select * from cities where state = $state". 

function SetLensApplet_country(&$lens)
{
	
	if (isset($_GET['state'])) {
		# quote the state string for safety  
		$state = $DB->qstr($_GET['state']); 
		$lens->sql = "select * from cities where state = $state";
	} else {
        # you must define all variations of the sql property
		$lens->sql = "select * from cities";
	}
	
	$lens->templateBaseDir = dirname(__FILE__);
	SetLensAppletGlobal($lens);

	$lens->showSort = false;
}

You could not place the above code in the implementation file country.inc.imp.php because phpLens would save only one version of the SQL in the implementation file next time a property is changed dynamicly from the user interface.

Security

Say I have a global variable $USER which determines who the user is. If $USER == 'ADMIN' then the administrator can dynamicly edit the phpLens.

I would place in an include script used by all your PHP code the following:

if ($USER != 'ADMIN') define('PHPLENS_NOEDIT',1);

We also have an example above on implementing canEdit/canNew/canDelete on a user by user basis.

This completes our discussion of applets.