Table of Contents

A Quick Tour

About phpLens

PhpLens is all about working smart and reusing your code. It makes database stuff that was hard to do in PHP easy. We can prototype and design from the Web browser using the Grid Builder, then generate the final PHP code.

Scripting

Here is the simplest phpLens script: (which we will explain in the Your First phpLens Script section).

01:  <?php
02:  include('./phplens.inc.php');
03:  session_start();
04:  $lens = PHPLensPConnect('prodLens', 'select * from Products',
05:                        'mysql', 'localhost', 'userid', 'password', 'database');
06:  $lens->Render();
07:  $lens->Close();
08:  ?>

This produces the following result:

:

Dynamic Editing using Your Browser

One of the things that we all hate to do is uploading our files to the Web server.

PhpLens shortcuts the upload process. Dynamic editing allows you to edit your database in your Web browser. The red Edit phpLens Settings icon allows you to configure global phpLens settings and Generate PHP Code.

You can also click the gray Edit Column Settings icons to configure settings specific to that column such as formating, charting (if the field is numeric), and cell colors.

The two green Edit Visible Columns icons determine what columns are visible for the Grid and Details tables. Later in Security you will learn how to hide the Dynamic Edit icons to prevent visitors from modifying the settings.

If you change any of the dynamic settings, you can regenerate your PHP code quickly by using the Generate PHP Code feature.

Builder

Just select your database and table from the top menu, and a data grid is created for the selected table. You can dynamically edit the settings, then click on Generate PHP Code , create a new .php file, and copy & paste the generated code.

This is a real time saver because no typing (except the .php file name) is required. Note that in phpLens 2.0, an alternative to the grid builder (but with a similar UI) is the applet Builder, accessible from phplens/builder/.

Parts of phpLens

Let's make sure you understand the terminology we are going to use for the rest of the manual. We can divide the above screen into the following areas:

The Grid is the left table. Each record in the Grid is assigned a Record Number (RecNo is the short form). In the above picture, one of the records has been selected (RecNo 2), and the remaining fields of the selected record are shown in the Detail Table.

You can scroll the data with the navigation bar, which provides:

	Edit Table Settings. This allows you to modify settings such as colors and the SQL statement used to generate the data. A picture of a Table settings screen can be seen here.
	Scroll to beginning of records
	Move to previous screen of records
	Move to next screen of records
	Scroll to end of records
	Create new record (only for Pro or better)
	Export to Excel/CSV
	Sort using multiple fields
	Filter or search for records. A picture of a filter screen can be seen here.
	Cancels a filter which prevents you from viewing all the records. Requires a filter to have been performed previously.

New to phpLens 2.0

We support three major innovations.

1. Multiple Row Editing in the Grid

The first innovation is the new multiple row editing feature. This allows you to edit multiple rows in a grid. This is enabled by setting the editMultiple property:

$lens->editMultiple = true;

This could produce the following screen where you can edit multiple records and click on Save to update all the records in one shot:

2. Hot Updates for Popup Lists

The second innovation is popup hot updates. This allows you to define dynamic popups that automatically update based on changes in the data. Look at the above diagram again. Notice that the country field shows 3 countries. If you change the country from USA to Malaysia for example, the state and city fields will automatically query the web server to retrieve a list of Malaysian states and cities. This is configured by defining two properties: lookupLens and phplensDatabase.

$lens->lookupLens = 'state^select distinct state from cities where country = {country}';
$lens->phplensDatabase = 'databasename';

The above example has been simplified because we only show the sql statement used for the state field. For the lookupLens property, {country} is a macro variable which tells phpLens to search for a field by that name and replace the macro variable with the current value of {country}. The phplensDatabase is a property that sets the database connection parameters to use.

3. Applets

The last innovation is the new applets interface for creating phpLens objects. Formerly with the builder you had to manually merge the source code everytime you changed a phpLens parameter from the dynamic editor. In an applet, we split the PHP code into two files: the applet.inc.php which contains the code is is never modified once created, and applet.imp.inc.php (imp stands for implementation) which is overwritten automatically by phpLens everytime you make a change with the dynamic editor. This requires the directory where the applets reside in to be set to read/write, which is by default the phplens/builder/applets/obj directory.

To use an applet in another PHP page, which has an id of "confucious", we would need to

include_once("phplens/builder/applets/obj/confucious/confucious.inc.php");

You can also move the whole confucious 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 in the confucious.inc.php file (or in an include). Applets can be created using a graphical user interface similar to the gridbuilder's from phpLens/builder/index.php.

Changes from 2.0 to 2.8

1. Since 2.2, we allow you to select which fields you want to export to Excel/CSV and you can click on this icon in the navigation bar to export. The default export format is CSV. This can be configured by the designer by selecting Columns to Export from the Choose popup in the dynamic editor.
   
2. From 2.4, we had been adding CSS support to phpLens.
   
3. Since 2.5, you can also perform sorting on mutiple fields by using the new sort interface. Click on this icon to display a form where you can select fields to sort. This can be configured by the designer by selecting Sortable Columns from the Choose popup in the dynamic editor.
   
4. In 2.6 we added support for the French language. Set the language parameter of the PHPLens constructor to 'fr'. We also added on-line help to the search form.
   
5. Since phpLens 2.7 the new PHPLensArray function allows you to manipulate an array of session variables as a recordset that can be viewed and edited. This is useful for creating wizards and forms that modify session variables.
   
6. Also since phpLens 2.7 we support compound primary keys. This can be defined using the syntax:
      $lens->keyCompound = 'field1;field2';

7. From phpLens 2.8, you can also have google style scrolling by enabling the $lens->scrollLinks property. For example, if you set $lens->scrollLinks to 11, the following scrollbar will appear:

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   
   
8. Many other user interface improvements and tweaks, including caching of blob images, better CSS control, and more.

Changes in 3.0

The new WYSIWYG HTML Editor for fields holding HTML with htmlEditLens.

Support for javascript popups in the data grid using the overlib library. See the overlibLens property.

Up to 30% improvement in execution speed and HTML generated is much smaller.

Support for the latest browsers Konqueror and Safari.

Sorting by multiple fields - previously, you could click on title links to sort based on one field. Now you can sort by multiple fields. See showSortCols.

The PHPLensArray( ) feature allows you to manipulate an array of session variables instead of database data. This makes it easy to create wizards or forms that manipulate session variables.

Better support for CSS. See CSS property and also the dynamic editor CSS color styles.

The titleLevel 1-3 properties allow you to have titles that span multiple rows and columns. Useful for reports. See example 970.

Terminology

We use the terms columns and fields interchangeably to mean table fields. The terms search and filter are also interchangeable.