Table of Contents

1.0 to 1.2 1.2 to 2.0 2.0 to 3.0 3.0 to 4.0 4.0 to 5.0

Changes from phpLens 4.0 to 5.0

Added new GIF/PNG graphing.

Improved spNew and spEdit, adding a new == mode, which allows spNew/spEdit to work even properly even when the selected columns in newLens/editLens have changed.

Improved colorLens to support "Title and Input Background Colors", so you can control the background color of the detail, edit and new titles, and the input background colors.

Added property optionalCols. Make certain data entry fields optional (readonly) based on data entered in an enabler field.

Added property groupDisplay.

Added property groupByCol to group data in a vertical span.

Added property redirectOnDelete.

Added property tzOffset to modify the default timezone.

Added property footerFn to generate custom footers for subtotals and totals.

Added global variable $LENS_UTF8, which if set to true, will activate UTF8 case insensitive comparisons. Moved language files to lang folder and added utf8.inc.php.

Changes from phpLens 3.0 to 4.0

1. Real record locking of records, with auto-timeout

   This means that once a record is locked by some editing it,
   no one else can modify that record until the record is unlocked by 
   the previous user. Record locking is an optional feature if you do
   not require this extra safety measure.

   See lockRec and lockTimer

2. Smart field sizing
 
   You can vary the width of fields in an edit/new record form for 600x800 or
   768x1024 screen sizes.

   This requires you to add the javascript file phplens/img/screensize.js
   to your javascript includes. This will add a cookie that sets the screen 
   size of the browser. PhpLens will read this cookie and set the input size 
   based on this setting.

eg.

<script src=/path/to/phplens/img/screensize.js></script>

Then in the dynamic settings for each field, set the screen size.


3. More intelligent handling of select statements that
   return no records.

   See onEmpty.

 
4. Snaking column support in the grid, eg. display a record
   over multiple lines in the grid.

   See snakeLens.
   
   
5. Allow you to perform your own subtotal calculations in the grid
   using powerSumLens.

   
6. Using a lookup in an edit or new record form is not scalable when the 
   lookup is retrieving thousands or millions of records. The new searchInEditNew
   property allows you to perform a partial search in the edit or new form.
   See examples 919 and 920.

   
7. You can set default search values of the search/filter form using
   filterDefaults
   
   
8. When printing, you want page breaks to occur after a certain number of rows.

   See pageBreakRows and pageBreakHTML.


9. To place separators between rows in the details or edit/new form, use 
   sectionLens.

Changes from phpLens 2.0 to 3.0

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

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^={$_SERVER['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';

This documentation system is maintained using phpLens