phpLens
 home • products examples manual • faq support forum • contact news • login store

phplens manual: Your first Lens script explained

Table of Contents

Your First Lens Script Explained 

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

Let us go line by line over the script:

  01: <?php

Make sure that the first line of the script file is the above. Don't leave any empty lines above it. This tells your PHP interpreter to execute the following lines as PHP code, and not to send any HTML or HTTP commands to the browser yet.

  02: #include('./phplens.inc.php');

Include all required library files needed to run phpLens.

  03: session_start();

In Line 3, before any HTML is sent to the browser, configure PHP to use session variables. Session variables allow PHP to remember what the user was doing on previous Web pages.

  04: $lens = PHPLensPConnect('prodLens', 'select * from Products',

Line 4 creates a new phpLens object ($lens) using the PHPLensPConnect( ) function.

PHPLensPConnect indicates that a persistent connection is established. A persistent connection means that the database connection is not closed at the end of the script but can be reused by other scripts. This speeds up connections dramatically.

We give the phpLens object an id of 'prodLens'. The id is used to identify the object in the internal phpLens database. Every phpLens object in your code must have a unique id, and it must be no longer than 38 characters and consist only of alphanumeric (A-Z 0-9) characters or underscore ( _ ) (If you are using phpLens 2.0.9 or earlier, it is 10 instead of 38 characters).

Warning: Very strange behaviour will occur if you have multiple phpLens objects on different pages sharing the same id because their settings will conflict with each other.

In the above example, we also set the SQL statement to use (select * from Products).

A phpLens object has many properties (variables) attached to it. The SQL statement above is a property of phpLens. The behaviour of phpLens is modified by changing these properties. See the discussion of properties in the next section below.

In PHP, variables are prefixed by the $ sign.

What is an SQL statement?

These are special commands that retrieve information from a database. Select * from Products means retrieve all (*) records from the Products table. 

  05: 'mysql', 'localhost', 'userid', 'password',    'database');

Line 5 connect phpLens to the mysql system located at localhost, with the login id userid and the password password, and the database to use is called database. These parameters are normally given to you by your database administrator. For further examples, see PHPLensConnect

  06: $lens->Render();

This will draw the phpLens Grid and Details on the Web page. If you need to script some phpLens properties, you will need to do so before calling Render( ). 

  07: $lens->Close();

Line 7 will close the internal recordset that contains the database records.

  08: ?>

The end of the PHP script. PHP will release the $lens object and free all database resources automatically.

Properties of phpLens

As mentioned above, the SQL statement used to retrieve the data is a property of phpLens. You can print it also.

print $lens->sql;

More interesting are the Lens range of properties. Lens properties are properties that filter or transform the data in some useful way. I like to think of them as lenses that allow you to refract or magnify the data in some way. For example, the colorLens property allows you to change the background color of a particular column, say ProductName with:

$lens->colorLens = 'ProductName^yellow';

To also change the color of the ProductID column, we use:

$lens->colorLens = 'ProductName^yellow;ProductID^beige';

Within the string, we use the hat (^) symbol to separate the column name with its setting. We use the semi-colon (;) to separate each column's settings.

The colorLens property from be dynamically edited from a Web browser also. Dynamic editing from a browser is much easier than coding with the cryptic conventions (but you will soon get used to it!)

PhpLens has over 200+ properties. All the important and commonly used properties can be set from your Web browser in Dynamic Editing mode (which is covered in the next section), except for properties that deal with security and the navigation bar.

Properties: Alphabetical List   Category List
Methods: Alphabetical List

A More Realistic Example

This example shows you how to interleave HTML with phpLens code, and where to place property settings..

01:  <?php
02:  #include('./phplens.inc.php');
03:  session_start();
04:  ?>
05:
06:    <html> <head> <title>phpLens demo</title></head> <body>
07:    <h3>A More Realistic Demo</3>
08:
09:  <?php
10:  $lens = PHPLensPConnect('prodLens', 'select * from Products',
11:                        'mysql', 'localhost', 'userid', 'password', 'database');
12:
13:  $lens->password = 'secret';
14:
15:  $lens->Render(); // generate and print the HTML tables
16:  $lens->Close(); 
17:  ?>
18:     </body></html>

Lines 4 to 8 show you where to place the HTML header and some HTML.

Line 13 shows us setting a property password that forces you to enter a password ('secret') before you can dynamically edit this phpLens object. We don't allow security properties to be dynamically edited to prevent unauthorised users from modifying security settings from a Web browser.

The text after // on line 15 is a comment.

This documentation system is maintained using phpLens
email: info#phplens.com (change # to @)     telephone (malaysia): 60-3 7806 1216     fax (malaysia): 60-3 7806 1210