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>"

You can access also global variables using the $GLOBALS[] array, or call PHP functions.

### More Examples

| Description | PowerLens Code
1 | Show column {c} as bold | `<b>{c}</b>`
2 | Capitalize first character of each word in column {c} using the PHP ucwords function | `=ucwords({c})`
3 | Combine 3 columns in one: {book}, {chapter}, {verse} so it will appear as [Genesis 2:3] | `[<b>{book}</b> {chapter} : {verse}]`
4 | Create a hyperlink | `<a href={linkpage}>{linktext}</a>`

### ColorLens

The powerLens allows you to modify a HTML table cell's contents. The colorLens allows you to control the cell tag (TD) attributes. Two methods to set a cell's color to red:

    $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

Note that setting the column width is discretionary. The browser can override this setting if it wants to.

### The Pipe-line

All fields are processed in a pipe-line before they are displayed.

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: &nbsp;. Here's what happens:

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

          null -> &nbsp;                                     &NBSP;

And the problem is that &NBSP; will not show as a space but as 6 characters as the non-breaking space ISO entity is case-sensitive. The solution is to use the following powerLens:

    = {STATE}=='&nbsp;' ? '&nbsp;' : 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 &nbsp; 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";
    }

    }