Table of Contents

Using PowerLens and ColorLens

You can reformat a field's data before it is displayed in phpLens using powerLens. Cell background colors and cell formating can be controlled with the colorLens. These properties are only available to the Basic, Professional, Advanced and Enterprise versions.

PowerLens

For example, if you have 2 columns, say firstname and surname you can combine them using:

{firstname} {surname}

If you want to have the surname first, with the firstname in italics:

{surname}, <i>{firstname}</i>

If you want the surname in uppercase you can do so by executing PHP code. To execute PHP code, set the first character to an equals (=). This will treat all following text as PHP code.

=strtoupper({surname})", <i>".{firstname}."</i>"

More Examples

ColorLens

$lens->colorLens='col1^red';
$lens->colorLens='col1^#CC0000';

You can perform conditional color-coding also. Use the equals (=) escape sequence to execute PHP code. Say we want to hilite all products with prices greater than $100.00.

$lens->colorLens="productname^= {price}>100 ? 'red' : 'white'";

Originally the colorLens property was developed to control cell colors, but later we realized that it can be extended to set any TD tag attribute. For example, you can change column widths in the example below.

$lens->colorLens = 'totals^yellow width=200px'; // ... sets the width too

The Pipe-line

With powerLens, we pass the raw data after lookups (eg. converting state codes from 'NY' to 'New York') to the powerLens processor.

To show prices in bold.

  database fields --> lookups --> powerLens processing --> Display
   field['PRICE']                  <b>${PRICE}</b>             

      4.95                                                 <b>$4.95</b>                   

Convert US state codes to the actual state name, and ensure that all characters are capitalised.

  
database fields --> lookups --> powerLens processing --> Display
   field['STATE']                =strtoupper({STATE})            

      NY            New York                             NEW YORK 

Handling Empty Fields

There is a problem with the above example. If the field['STATE'] returns an null, phpLens assumes that you are displaying this in a grid cell, and will convert the null to a non-breaking space:  . Here's what happens:

  
database fields --> lookups --> powerLens processing --> Display
   field['STATE']                =strtoupper({STATE})            

      null ->                                        

= {STATE}==' ' ? ' ' : strtoupper({STATE})  

Unfortunately, the above code will not work as the ; is treated as a special character (the field separator) by phpLens. So we have a special variable called {NBSP} that you can use:

= {STATE}=={NBSP} ? '{NBSP}' : strtoupper({STATE})  

An alternative method is to use the special {SEMICOLON} variable:

= {STATE}=='&nbsp{SEMICOLON}' ? '&nbsp{SEMICOLON}' : strtoupper({STATE})  

The {semicolon} and {nbsp} variables are case-insensitive. You can also generate any ISO entity using the {semicolon} variable.

The =% and % modifiers

Since phpLens 2.7, you can disable the conversion of nulls and empty strings to   by using % for normal string substitution or =% for PHP code.

Example 1

The above powerLens

= {STATE}=='&nbsp{SEMICOLON}' ? '&nbsp{SEMICOLON}' : strtoupper({STATE})  

Can be rewritten more intuitively as:

=% {STATE}=='' ? '{NBSP}' : strtoupper({STATE})  

Example 2

And a powerLens such as

%<a href="/process_state.php?state={STATECODE}">{STATENAME}</a>

Will generate when STATECODE=null and STATENAME=UNKNOWN STATE

<a href="/process_state.php?state=">UNKNOWN STATE</a>

instead of

<a href="/process_state.php?state=&nbsp;">UNKNOWN STATE</a>

RowColorLens

PhpLens (since 1.2) dynamicly modifies the color of the current line the cursor is on in IE and Mozilla using a user-defined function. The default function is defined in phplens.inc.php, and you can customize it for your needs. Note that the rowColorLens property allows you to enter selected macro variables that are filled by phpLens. You cannot define your own macro variables, but you can access any column using the same {column_name} syntax in the rowColorLens property:

//----------------------------------------------------------------------------
// Define code for coloring rows. You should modify this if you want to color 
// based on some other criteria.
//
// onMouseOverColor	The color to display when the mouse is over a row.
//						Defaults to #FF8080, a shade of pink.
// id				The $lens->id property
// recno			The record number that you are currently processing
// isSelected		Is this record the current selected record (boolean)
// selColor			The $lens->colorSelect property
// oddColor			The $lens->colorOdd property
// evenColor		The $lens->colorEven property
// hasDetails		Details grid/editor visible
// primary			Primary key
// primary_type    ADOdb metatype for primary key, eg. C for char, N for numeric, I for integer
// editClick		Only when set to true will clicking invoke an edit link
//
// The default rowColorLens is
// $lens->rowColorLens = '=LensRowColor("#FF8080",
//				{_LENSID_},{_RECNO_},{_RECNO_}=={_HILITE_RECNO_},
//				{_SELECTC_},{_ODDC_},{_EVENC_},{_HASDETAILS_},
//				{_PRIMARY_},{_PRIMARYTYPE_},{_EDITCLICK_})';
//

function LensRowColor(
   $onMouseOverColor,$id,$recNo,
   $isSelected,$selColor,$oddColor,$evenColor,	$hasDetails,
   $primary=false,$primary_type=false,$editClick=false)
{
GLOBAL $PHP_SELF;
	
	$color = ($recNo%2)? $oddColor : $evenColor;
	if($hasDetails) {
		if ($isSelected) $color = $selColor;
		$js =<<<DOC
 onclick="window.location='$PHP_SELF?lens_no_$id=$recNo'" 
 onmouseover="this.style.backgroundColor='$onMouseOverColor'" 
 onmouseout="this.style.backgroundColor=''"
DOC;
	} else {
		$js = '';
		
		if ($editClick && $primary !== false) {
			$js =<<<DOC
 onclick="window.location='$PHP_SELF?phplens_$id=e&lens_p1=$primary&rn_$id=$recNo&t=$primary_type'" 
 onmouseover="this.style.backgroundColor='$onMouseOverColor'" 
 onmouseout="this.style.backgroundColor=''"
DOC;
		}
   }
 	return "$color$js valign=top";
}

}