Table of Contents

1.0 to 1.2 1.2 to 2.0 2.0 to 3.0

## Changes from phpLens 2.0 to 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.

Google style links with the scrollLinks property.

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

Support for the latest browsers Konqueror and Safari.

Support for Export to Excel - we now have a one-click button to export recordsets in Excel or CSV format. See http://phplens.com/lens/lensman/prop/exportLens.htm and http://phplens.com/lens/ex/ex970.php

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 http://phplens.com/lens/lensman/prop/showSortCols.htm

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. See http://phplens.com/lens/lensman/array.htm

Better support for CSS. See http://phplens.com/lens/lensman/prop/css.htm and also the dynamic editor CSS color styles.

Compound primary key support. The primary key can consist of multiple fields.

The titleLevel properties allow you to have titles that span multiple rows and columns. Useful for reports. See http://phplens.com/lens/ex/ex970.php

Added image caching for Blob fields, for a 70% improvement in performance when using phpLens to view images. See http://phplens.com/lens/lensman/prop/imageCacheSecs.htm

Improved browser-based PHP IDE that works on all modern browsers (in the phplens/builder).

High performance PHP applets interface that allows you to dynamically modify and save phpLens objects on your hard disk.

Improved user interface controls for everything from search forms to checkboxes and radio buttons.

We now provide more source code for you to examine and customize, including the files phplens.inc.php, phplens-common.inc.php, phplens-dynedit.inc.php, phplens_remoteq.php and the language files phplens-lang.*.inc.php.

PhpLens now supports renderers that allow you to display data grids in different ways. The first renderer available is the Calendar, which displays data in templates, organized by month and week.

## Changes from phpLens 1.2 to phpLens 2.0

This covers the big features of phpLens 2.0, multiple record edit and popup hot updates, and how to configure your phpLens code to support these features.

### MULTIPLE RECORD EDIT IN GRID

This is easy, set

$lens->multipleEdit = true;

You can also configure this in a checkbox in phpLens settings. Every field defined in $lens->editLens and $lens->gridLens will be editable in the grid. Fields that are only defined in $lens->gridLens will be readonly. The detail grid on the right remains read-only.

When you click on the Save button, every row of the grid is treated as a separate SQL insert statement. The phpLens event*SQL properties are called multiple times, once for every row.

Performance

For good performance, you should cache your popup lists using the cacheLookups property and combine it with the ADODB_CACHE_DIR constant.

    $lens->cacheLookups = 600;        // cache for 600 seconds
    define('ADODB_CACHE_DIR','/tmp'); // and store cache in this directory

We have other ideas to improve performance which we will roll out in phpLens 2.1 or later.

### POPUP HOT UPDATES

PhpLens 2.0 now supports hot updates using a new lookupLens feature. Have a look at the following property setting:

$lens->lookupLens = "STATE^#select distinct state from cities where country={country};"

observe that the select statement is prefixed with #. This means that all variables enclosed in { } are actually data fields when creating or editing records. So if the COUNTRY popup field is set to "USA" in the browser, then we populate the STATE field with the values generated by:

select distinct state from cities where country='USA'

We have integrated this with Javascript so it works in the browser also. IE 5-6, Netscape 4.77 and Mozilla 0.9.* are supported. When you change the COUNTRY popup in the browser, we create an invisible browser window and query the web server (phplens_remote.php) with an SQL statement and retrieve the data from the database. The source code to phplens_remote.php is available for your review.

PHPLENSDATABASE

To keep track of what database to that phplens_remote.php needs to query, we need to set a second property:

$lens->phplensDatabase = 'testdb';

This 'testdb' is a one of the databases you defined in the file phplens/config/phplens.config.inc.php. Eg.

    $PHPLENS_DATABASES =
    array(			//driver, server, userid, pwd, database
    	'testdb' => array('mysql','localhost','root','','test')
    );

SECURITY

We have to embed the SQL and phplensDatabase values in the javascript phpLens generates. This means that the end-user can view the HTML source. We feel that this is not a problem because we fingerprint the SQL and database values using an md5 checksum with a salt you can redefine using

define('PHPLENS_MD5_SALT','Define Your Own Random String here &*(&^*&#');

at the very top of your PHP script. This means that any hacker attempt to modify the HTML will be detected and rejected.

### OTHER CHANGES

The following properties are new to phpLens 2.0

cacheLookups
debugDie
editMultiple (covered above)
eventDetailView
sqlDetail
sqlEditNew
urlParams

## Changes in phpLens from 1.0 to 1.2

PhpLens 1.2 is backward compatible with phpLens 1.0 except for template handling (see point 15).

A quick summary of major improvements would be

- automatic row highlighting (rowColorLens property)
- the ability to have the record editor in the detail grid (childLens property)
- support for checkboxes, radio buttons, checkboxes and multiple select (listbox) in data entry forms
- improved double-byte support.

### Detailed Changelog

    1. Added rowColorLens property to set the color of the current row:

    # sets the color to red if PRICE is negative, otherwise use normal colors.
    $lens->rowColorLens = '= ({PRICE}<0) ? "red" : false ';

    There is a default rowColorLens installed now. The source code for the
    function it calls (LensRowColor) can be found in phplens.inc.php. Code contributed
    by Eric Grau.

    Also added dynamic editor setting called (Child Editor) so you can decide
    whether to enable record editing in the detail grid.

    Also see point 3 for another example, coloring the currently selected row.

    2. The following properties support PHP global variables and 1-dimensional global
    arrays. Optional curly-brackets are usable:

    Triggered by =
      powerLens - modify field columns
      sql - sql statement
      keyTable - table to update

    Triggered by % because = is used for text mappings
      lookupLens - mappings for popups, checkboxes, and submit & radio buttons

    Examples:

    $lens->keyTable = '=$table'; # get table name from variable $table

    # dynamic table name
    $lens->sql = '=select * from {$prefix}table';

    # get states from table usa_states, malaysia_states, etc depending on
    # the country...
    $lens->lookupLens = 'state^%select statecodes from {$country}_states';

    # for lookuplens, if {$var} means from PHP globals, if {col} then from database
    $lens->powerLens = 'URL^={$HTTP_SERVER_VARS['HTTP_HOST']}://{PATH}'

    3. Added _HILITE_RECNO_ and _RECNO_ variables in powerLens and rowColorLens.
    Useful for telling phplens to drilldown from grid to detail view from an
    <A> tag. Use {_HILITE_RECNO_} == {_RECNO_}  to find out if the current
    row is selected.

    Eg. We have a phpLens with $ID='abc', and we want to drilldown to the detail
    view (note: it uses the new global var support with $ID and $PHP_SELF):

    $lens->powerLens = 'Column^=<a href=$PHP_SELF?lens_no_$ID={_RECNO_}>{Column}</a>';

    #hilite the current row
    $lens->rowColorLens = '={_RECNO_} == {_HILITE_RECNO_}? "#FFCCCC": false';

    4. Property powerEditLens added. This allows you to modify the value of an field
    when editing an existing record. Useful for timestamping modifications. This differs
    from defaultLens which only allows you to modify the field when creating a new record.

    For example to set the TimeModified and TimeCreated fields:

    $lens->readOnlyLens = 'TimeModified;TimeCreated';
    $lens->powerEditLens = 'TimeModified^=time()';
    $lens->defaultLens = 'TimeModified^=time();TimeCreated^=time()';

    This property can be edited from the dynamic editor.

    5. Added inputTypeLens property to support checkboxes, radio buttons and
    submit buttons. Can be edited in dynamic editor. See 22 for support for multiple select.

    # choose 1 gender, and choose multiple hobbies
    $lens->inputTypeLens = 'gender^radio;hobbies^checkbox';

    6. Property displaySep added to hold the text used to separate checkbox items.
    Checkbox items are not stored in a separate child table, but as items in the current
    table, separated by this displaySep value (default is ', ').

    7. Save/Cancel buttons appear on both top/bottom navigation bars if the number of
    fields is greater than constant 'LENS_SHOW_TOP_MIN_ITEMS' in phplens.inc.php.

    8. Property showCancel to determine whether cancel button is displayed when
    editing records. Default is $lens->showCancel = true;

    9. Added == to lookupLens property.

    There are 2 uses for lookupLens. First, for remapping (say 'CA' to 'California'),
    and the other is for displaying a popup selection. If you were using lookupLens with
    text lookup to implement a popup selection, in phpLens 1.0 you use:

    $lens->lookupLens = 'sports^==Football/Football/Squash/Squash/Tennis/Tennis';

    Now we support a simplified lookupLens for this scenario using ==

    $lens->lookupLens = 'sports^=Football/Squash/Tennis';

    10. Property textAreaHeader extended to support different textarea rows and cols
    for different fields. The old syntax is still supported.

    $lens->textAreaHeader = 'field1^rows=10 cols=40;widefield^rows=3 cols=80';

    11. The sqlBind property will cause variable binding to occur in SQL statements.
    Currently supported by ODBC. Note this is still experimental in 1.2. Not guaranteed to work!

    $lens->sqlBind = true;

    12. Nested phpLens objects now work properly.

    13. Now if properties redirectOnInsert and redirectOnInsertCancel are set, then
     no viewing of grid is allowed for security reasons.

    14. When viewing html text, phpLens will now convert https:// url's to anchor tags.

    15. Many template changes to support future phpLens improvements. Your macro input
    variables will have to be changed from {COLUMN_INPUT} to {COLUMN}. Also changed
    macro {_EDIT_} to {_DYNEDIT_}.

    16. Now if the field is mustFill but is set to readOnly then the field can be modified
    on record creation, but not editable in the future after the record is created.

    17. New errorHandler property. Returns true if error should be shown, false to ignore
    the error. The parameters are:

        $msg = holds the error message
        $severity = one of {LENSERROR_SEVERE=1, LENSERROR=0, LENSWARNING=-1}
        $objid = the phpLens object id

    function show_error($msg, $severity, $objid)
    {
    	if ($severity  >= LENSERROR_SEVERE) {
    		@mail('admin',"Error $objid",$msg);
    		die();
    	}
    	return true;
    }
    $lens->errorHandler = 'show_error';

    18. PhpLens template skeleton support if you set $lens->debug = -1. Useful for generating
    basic Smarty templates quickly which you can then edit in a graphical html editor.

    19. Replace details with edit grid. Use with caution as this feature is very new and
    has not been tested as thoroughly as the rest of phpLens. Uses new property childLens.

    Syntax:

    $lens->childLens = '{id of child phplens};editdetail';

    The string editdetail is a constant that should not be changed. In the future, additional
    constants will be defined to modify the behaviour of the child phpLens object. The id
    of the child phpLens should be a unique value that is not used by other phpLens objects.

    Example 1: Simple Example

    include_once('./phplens.inc.php');
    session_start();

    $db = &ADONewConnection('mysql');
    if (!$db->PConnect('localhost','root','','db')) print 'Error:'.$db->ErrorMsg();
    $lens = new PHPLens('editdet',$db,' select * from  products order by 1 ');
    $lens->childLens = 'editdet2;editdetail';
    $lens->canEdit = true;
    $lens->canDelete = true;
    $lens->canNew = true;
    $lens->Render();
    $lens->Close();

    Example 2: You want to modify the child phplens object so the top border is green.
    You will need to extend the Clone() method:

    include_once('./phplens.inc.php');
    session_start();

    class PhpLens2 extends PhpLens {
    	function &Clone()
    	{
    		$lens = PhpLens::Clone();
    		$lens->colorTitle = 'green';
    		$lens->detailLeftColor = 'blue';
    		return $lens;
    	}
    }

    $db = &ADONewConnection('mysql');
    if (!$db->PConnect('localhost','root','','db')) print 'Error:'.$db->ErrorMsg();
    $lens = new PHPLens2('editdt',$db,' select * from  products order by 1 ');
    $lens->childLens = 'editdt2;editdetail';
    $lens->canEdit = true;
    $lens->canDelete = true;
    $lens->canNew = true;
    $lens->Render();
    $lens->Close();

    20. Better support for input of double-byte characters. Formerly only UTF-8 worked well.
    Now tested extensively with GB and Big5 using NJStar Communicator.

    To make all columns support double-byte characters, set
        $lens->htmlLens = '*';

    21. Blobs can be set to display normal HTML by setting
        $lens->htmlLens = 'blobCol1;blobCol2';
    or
        $lens->htmlLens = '*';

    22. New inputTypeLens value, "multiple" which allows a listbox to appear:

    $lens->inputTypeLens = 'hobbies^multiple';