Table of Contents Green properties are dynamically editable.

allowEmptyFilter
anchorTags
attrDateTime
autoGenerateKey
avgLens
bannedTags
border0
cacheData
cacheLookups
canDelete
canEdit
canNew
cellFontPrefix
cellFontSuffix
chartFontPrefix
chartFontSuffix
chartLens
chartParams
childLens
colorBackground
colorEven
colorFooter
colorGroup
colorLens
colorNav
colorNavBorder
colorOdd
colorRecNo
colorSelect
colorSubFooter
colorTitle
columns
compat
connection
connectionLookups
css
curState
dataVers
debug
debugDie
defaultLens
detailFontPrefix
detailFontSuffix
detailHdr
detailLeftColor
detailLens
detailRightColor
detailTableHeader
detailTitleFontPrefix
detailTitleFontSuffix
detailTitleHeader
detailValueHeader
displaySep
dynEdit
dynUseSessions
editClick
editHiddenTags
editLens
editMultiple
editNewRadioCheckBoxTD
editTableHeader
emptyCharIsNull
emptyDatesNull
errHideMessages
errorHandler
errorPrefix
errorSuffix
evenHeader
eventDetailView
eventPostDeleteSQL
eventPostInsertSQL
eventPostUpdateSQL
eventPreDeleteSQL
eventPreInsertField
eventPreInsertSQL
eventPreUpdateField
eventPreUpdateSQL
exportLens
exportOptions
fields
fieldSep
fileSessionPath
filterAllOr
filterAnyWhere
filterDefaults
filterFontPrefix
filterFontSuffix
filterLens
filterModifierFn
filterParams
filterRadioCheckBoxTD
filterShowForm
filterTableCols
filterTableHeader
filterTopColor
filterUseLike
firstState
fmtDateInput
fmtDateOutput
fmtDecimal
fmtDecimalDB
fmtDecimalPlaces
fmtThousands
fmtTimeStampInput
fmtTimeStampOutput
fmtTimeStampsAsDates
fontSelColPrefix
fontSelColSuffix
forceType
getFieldsFromTables
gridHeight
gridLens
gridReadOnlyLens
gridTableHeader
groupDesc
groupFontPrefix
groupFontSuffix
groupLens
groupSep
hideAnchorName
htmlEditLens
htmlLens
id
ignoreSessions
imageAttributes
imageCacheSecs
imageDir
imageEmpty
imageMaxSize
imagePage
imageTmpDir
imageTmpDirURL
imageType
imageUploadFunction
includeFooter
includeHeader
inputLens
inputTypeLens
keyCol
keyColClear
keyColVariable
keyCompound
keyIsChar
keyRecNo
keyRecNoSelect
keyTable
keyVariable
lang
layoutTableHeader
lensVers
lookupLens
md5Input
menuHide
mustFill
mustFillMark
nameLens
nameSpace
navFontPrefix
navFontSuffix
navHeader
navTableHeader
navTDHeader
navUserButtons
newHiddenTags
newLens
newReadOnlyLens
newTableHeader
nl2br
noAutoNew
noTrim
numberPrefix
numberSuffix
numInputLen
oddHeader
onlyOrder1Col
overlibInit
overlibLens
overrideFunction
pageBreakHTML
pageBreakRows
pageSize
password
persist
phplensDatabase
powerEditLens
powerLens
powerPrefix
readOnlyLens
redirectNoData
redirectOnInsert
redirectOnInsertCancel
redirectOnUpdate
redirectOnUpdateCancel
remoteQuery
renderer
roInputStyle
rowColorLens
rs
sameRowLens
saveOptions
scrollBgColor
scrollFontPrefix
scrollFontSuffix
scrollHiliteFontPrefix
scrollHiliteFontSuffix
scrollLinks
scrollMaxRecordCount
scrollTDHeader
searchLookupLens
sectionLens
securityCheckReferer
securityEditSeq
showCal
showCancel
showDetails
showFindMore
showGrid
showHeaders
showRecNo
showSort
showSortCols
spDelete
spEdit
spNew
sql
sqlDetail
sqlEditNew
sqlFilter
sqlWhere
subTotalFontPrefix
subTotalFontSuffix
sumLens
sumTotal
tdEdit
tdLens
templateAssign
templateBaseDir
templateDetail
templateEdit
templateFilter
templateFilterGrid
templateGrid
templateGridHdr
templateLayout
templateLayoutAddFilter
templateMode
templateNew
templatePrefix
templateSecure
templateShowErrors
templateSuffix
textAreaHeader
textAreaLens
textInputHeader
textInputMax
textInputMin
textSizeLens
titleColor
titleFontPrefix
titleFontSuffix
titleHeader
titleLevel1
titleLevel2
titleLevel3
totalFontPrefix
totalFontSuffix
totalNumPrefix
totalNumSuffix
toUpper
upperCase
urlParams
validation
versionLockCol
warnLookupOverflow

allowEmptyFilter

Filtering and Searching
allowEmptyFilter
When user performs an empty filter/search, show all records? Default: `true` If set to false, when no filter/search criteria is defined, no query is performed. Setting to true seems to be more natural, while false will improve database performance. Syntax `$lens->allowEmptyFilter = Boolean;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

anchorTags

Editing, Updating and Creating Records
anchorTags
When saving, detect http://* and www.* and email addresses convert them to links Default: `'true'` Only enabled when htmlLens is set for that column. Syntax `$lens->anchorTags = Boolean;` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.10beta]

attrDateTime

Editing, Updating and Creating Records
attrDateTime
Sets tag attributes for date and timestamp input fields Typically used to set the CSS class selector of input fields for date and timestamp fields when editing or creating records. Syntax `$lens->attrDateTime = 'class=small';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.5.2]

autoGenerateKey

Editing, Updating and Creating Records
autoGenerateKey
Makes phpLens autogenerate an integer to be stored into keyCol when inserting a new record Set this property to true to enable generation of keys by phpLens. If you want to use a custom generator, set this property to the name of the PHP function that returns the key. The generated key is also passed to the eventPostInsertSQL property, and also stored in the generatedKey property after Render() is called. Note that is only required on selected databases which do not have an auto-incement primary key, including early-PostgreSQL versions, Interbase and Oracle (oci8) currently. Internally, phpLens will create sequences or tables to manage the integer generation. If you are using autoincrement columns generated by the database (eg. mysql or mssql), you can get the last inserted value using $lens->connection->Insert_ID(); Syntax `# 1. generate integer key $lens->autoGeneratedKey = true; $lens->Render(); # 2. use a random function to generate the key. function genrand() { return rand(); } $lens->autoGenerateKey = 'genrand'; $lens->Render(); # now the generatedKey value is available after an insert $id = $lens->generatedKey;` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

avgLens

Grouping and totaling of rows
avgLens
Display averages in the subtotal and total rows Display averages for subtotals and totals. Syntax `# display averages for the following 2 fields... $lens->avgLens = 'UnitsInStock;UnitPrice';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 2.2]

bannedTags

Editing, Updating and Creating Records
bannedTags
Regular expression describing which tags are banned for data entry Default: `'/<\\/*((SCRIPT)|(META)|(DIV)|(APPLET)|(OBJECT)|(EMBED)|(INPUT)|(TEXTAREA)|(IFRAME)|(FRAME)|(SPAN))/i'` Only works if htmlLens is set for that column. Otherwise all tags are converted by htmlspecialchars() to their html entities. Uses Perl compatible regular expressions. Note: since phpLens 3.0, we no longer ban table, th, td. tr tags by default. This is because the new htmlEditLens allows HTML tables to be created. Syntax `$lens->bannedTags = Regular Expression String; Let's dissect the beginning of the default search: '/<\\/*((SCRIPT)|(META)|(DIV)|(.../i All Perl compatible regular expressions begin and end with /, so just ignore them. First we search for < which is the beginning of a tag. Then we search for an optional slash (/) using \\/*. Next we check for tags (which are separated by the |, which is the OR-operator) such as SCRIPT or META or DIV etc. The /i at the end means that the regular expression search is case-insensitive.` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

border0

Table Cell formating
border0
Set table borders to 0 0 = use table borders set to border="0" 1 = no borders in cells nor around table 2 = no borders between cells, but place a border around table It is recommended you do not manually modify this property in an editor, but use the Dynamic Editor as phpLens does special processing on this property. If you want to manually change the borders, phpLens will not modify the border if you set the border without the quotes, or uppercase the attribute, eg. border=0 BORDER="1" Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3.2]

cacheData

Programming
cacheData
Cache data in $ADODB_CACHE_DIR for cacheData seconds Default: `0` Make sure that the global variable $ADODB_CACHE_DIR points to the correct directory. See cacheLookups property for more examples. Data is only cached if the data is set to readonly (no editing/deleting/inserting). Do not set this to true when you have multiple Web servers accessing the same data. However if scrollLinks is set, then the value from the SELECT COUNT(*) that phpLens makes will always be cached if cacheData is set to a non-zero value, whether or not the data is set to readonly. Syntax `$ADODB_CACHE_DIR = '/tmp'; $lens->cacheData = 60; # cache 60 secs` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

cacheLookups

Programming
cacheLookups
Cache lookup values for cacheLookups seconds in the $ADODB_CACHE_DIR directory. Default: `0` PhpLens uses the ADODB database library internally. ADODB has the ability to cache queries and recordsets in a directory defined by the variable $ADODB_CACHE_DIR. You should define this constant at the top of your script. This property can speed up phpLens significantly by reducing queries to the database. Syntax `$ADODB_CACHE_DIR='/path/to/dir'; include('phplens.inc.php'); $conn = NewADOConnection('mysql'); $conn->PConnect('server','user','pwd','db'); $sql = 'select * from table'; $lens = new phpLens('someid',$conn,$sql); $lens->cacheLookups = 120; $lens->Render();` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

canDelete

Editing, Updating and Creating Records
canDelete
Show Delete button and allow deletes Default: `false` Clicking on the button will ask for confirmation from the user if Javascript is enabled on the browser. The icon can be modified. It is configured in the language class $lens->lang->iconDel. Also requires the keyTable and keyCol properties to be defined. If you want only selected rows to be deletable, you can define an additional column called "_CANDELETE_" and set the value to 0 or 1. Non-zero values means that the row can be deleted. This is available since 2.2.0. For example, set $lens->sql to the following if you want the user to only be able to delete products that begin with 'A' (assuming your database supports CASE) SELECT productname, supplier, unitinstock, unitprice, CASE WHEN substr(productname,1,1) = 'A' THEN 1 ELSE 0 END "_CANDELETE_" FROM products Syntax `$lens->canDelete = Boolean;` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

canEdit

Editing, Updating and Creating Records
canEdit
Show Edit button and allow record updates Default: `false` Also requires the keyTable and keyCol properties to be defined. The icon can be modified in $lens->lang->iconEdit. If you want only selected rows to be editable, you can define an additional column called "_CANEDIT_" and set the value to 0 or 1. Non-zero values means that the row is editable. Available since 2.2.0. For example, set $lens->sql to the following if you want the user to be able to only edit products that begin with 'A' (assuming your database supports CASE) SELECT productname, supplier, unitinstock, unitprice, CASE WHEN substr(productname,1,1) = 'A' THEN 1 ELSE 0 END "_CANEDIT_" FROM products Syntax `$lens->canEdit = Boolean;` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

canNew

Editing, Updating and Creating Records
canNew
Show New Record button and allow record creation Default: `false` The icon can be modified. It is configured in the language class $lens->lang->iconNew. Also requires the keyTable and keyCol properties to be defined. Syntax `$lens->canNew = Boolean;` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

cellFontPrefix

Table Cell formating
cellFontPrefix
Tags to prefix to data cell text Default: `'<font size=2>'` Tags must match cellFontSuffix. Syntax `$lens->cellFontPrefix = String;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

cellFontSuffix

Table Cell formating
cellFontSuffix
Tags to append to cell data Default: `'</font>'` Must match cellFontPrefix. Syntax `$lens->cellFontSuffix = String;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

chartFontPrefix

Charting
chartFontPrefix
Tags to prefix chart numbers Default: `'<code>'` Chart numbers must always be monospaced so that they align properly. Syntax `$lens->chartFontPrefix = String;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

chartFontSuffix

Charting
chartFontSuffix
Tags to append to chart numbers Default: `'</code>'` Must match chartFontPrefix. Syntax `$chartFontSuffix = string` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

chartLens

Charting
chartLens
Fields listed in this lens are displayed as charts The field must be of type integer or numeric. There are two types of charts you can create. Bar Charts The first is a horizontal bar chart. If the chart has both negative and positive numbers, you can choose two different colors for the negative and positive values. Chart dimensions must be set for bar charts. This is the maximum size of a chart. Set the width and height. To fit the chart into the chart dimensions, phpLens needs to estimate the maximum and minimum values of the field. You can provide an SQL statement to calculate it here, or hard-code numeric values (this is faster). Icon Chart The other chart is the icon chart, which shows a picture for every Scale units (rounded up). Setting Chart Min/Max The scale of the chart is determined by these settings. Chart Min is the smallest possible value and Chart Max is the largest possible value in that column. You can set this value manually (default), or execute an SQL statement to do this, normally:
    select min(col),max(col) from table
From these values and the Chart Dimensions, phpLens is able to scale the chart correctly. Syntax `$lens->chartLens = 'Col1;Col2;Col3';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

chartParams

Charting
chartParams
Stores charting parameters set when dynamic editing enabled If you need to save the chart settings as source code, set your charting parameters using dynamic editing, generate the PHP code, then copy and save the chartParms and chartLens properties. Syntax `Not documented currently because the format will change in future versions.` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

childLens

Editing, Updating and Creating Records
childLens
Replaces the details grid with an editor to create/edit records Legal settings:
Create and Edit | New record form is the default, unless a record is selected for editing
Edit Only | Always show the edit record form for the current record
Create Only | Always show the new record form
Edit and Create | Show edit record form for the current record is the default. When the new record icon is clicked, show the new record form in details
This is called childLens because internally, it creates a second phpLens object(the child) to do the editing. Syntax: $lens->childLens = '{id of child phplens}[;editdetail][;newdetail][;editfirst]'; The string editdetail is a constant that specifies editing is allowed in the detail grid. The string newdetail is optional and when defined, will display the create new record screen in the detail grid when no record has been clicked on. The editdetail constant must also be set for newdetail to work. The id of the child phpLens should be a unique value that is not used by other phpLens objects. Since phpLens 2.4, both editdetail and newdetail are optional. Since phpLens 2.4.8, a new optional setting, editfirst is available. When makes editing the default instead of creating a new record if both editdetail and newdetail are defined. Syntax `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->colorNavBorder = 'green'; 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();` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.2]

colorBackground

Colors
colorBackground
Color of the background area outside the grid and detail table Syntax `$lens->colorBackground = Color String; $lens->colorBackground = 'black'; $lens->colorBackground = '#000000';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorEven

Colors
colorEven
Color of even rows in grid Set the bgcolor in the TR tag. Addional TR properties can be placed after the color, for example: `$lens->colorEven = 'yellow valign=bottom';` See also colorOdd. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorFooter

Colors
colorFooter
Color of any totals at bottom of grid Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorGroup

Colors
colorGroup
Color of any column grouping rows Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorLens

Table Cell formating
colorLens
Dynamicly change color of column or cell, and column attributes too. You can use this property to enter a color such as 'white' or 'black', or use the numeric RGB values where #000000 and #FFFFFF is white. To set dynamic colors in your columns, set the first character to an equals (=), then you can use the PHP's ternary logical operator or your own pre-defined function to perform checks and comparisons. PHP has a nice way of allowing you to choose between multiple values in one line of code: `= (expr) ? "value if expr is true" : "value if expr is false"` An example is given a column named UnitsInStock, and we want to color the column red if the units are less than 10: `=({UnitsInStock} < 10)? "red" : ""` You can also use any global variables defined in the $GLOBALS array using {$VARNAME}, for example {$PHP_SELF}. The colorLens property can access any column in the current row using the {columnname} syntax just like the powerLens. Additional Macro Variables Available {NBSP} = ' ' {SEMICOLON} = ';' {_HILITE_RECNO_} = current record number {_LENSID_} = the phpLens object's id {_ODDC_} = the odd row color {_EVENC_} = the even row color {_SELECTC_} = the hilite color for the current line {_HASDETAILS_} = whether the detail grid is visible Changing Column Attributes You can also change column widths with this property by taking advantage of a side-effect. Any attribute can be added to the TD tag using colorLens. See example in syntax. Note that setting the column width is discretionary. The browser can override this setting if it wants to. However since phpLens 2.6, we have the tdLens property, which allows you direct access to all td attributes. Note however that tdLens does not do column interpolation (eg {col1}) nor php code processing (with =). Syntax `$lens->colorLens = 'totals^yellow'; // color the totals column yellow $lens->colorLens = 'totals^yellow width=200px'; // ... sets the width too $lens->colorLens = 'totals^yellow;name^#0000FF'; // and name is blue` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorNav

Colors
colorNav
Color of the navigation bar cells Default: `#C0C0C0` This property determines the color inside the menu option cells. ColorNavBorder sets the border color of the cells. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

colorNavBorder

Colors
colorNavBorder
Color of background behind captions and navigation bar Syntax `$lens->colorNavBorder = '#C0C0C0'; # to use with CSS # assuming the following is defined: # .navcss {background: #C0C0C0} $lens->colorNavBorder = '#C0C0C0 class=navcss';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorOdd

Colors
colorOdd
Color of odd rows in grid Set the bgcolor in the TR tag. Addional TR properties can be placed after the color, for example: `$lens->colorOdd = 'yellow valign=bottom';` See also colorEven. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorRecNo

Colors
colorRecNo
Color of background of RecNo column Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorSelect

Colors
colorSelect
Color of selected sort column and selected recno Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorSubFooter

Colors
colorSubFooter
Color of subtotals when groupLens enabled Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

colorTitle

Colors
colorTitle
Color of column/field title cell Set the bgcolor in the TH tag. Addional TH properties can be placed after the color, for example: `$lens->colorTitle = 'yellow align=right';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

columns

Table Rows and Columns
columns
Number of columns to display in grid Default: `1` Auto-Resizing If $lens->columns > 1 and $this->pageSize >= 1000, then phpLens will auto-resize the grid to fit all records in one page by adjusting the number of records per column. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

compat

Programming
compat
Compatibility mode, defaults to 2.0 Default: `2.0` When set to 2.0, phpLens uses the default behaviour for the following: a. Filtering lookups use =1/2/3/4/5 and no mapping is allowed. When $lens->compat = 2.5 or greater a. Filtering lookups behave like powerLens. Eg. =1/One/2/Two for mapping lookups, or ==1/2/3/4/5 for no mapping. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.5.1]

connection

Programming
connection
Holds the ADOdb connection object This represents the connection to the database. You can access access the connection resource directly using $lens->connection->_connectionID. See also rs, the recordset property, and the ADOdb manual. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

connectionLookups

Programming
connectionLookups
Instead of using the default connection, use this connection for sql lookups There are 2 ways to use it. First is to set it to an existing database connection: $db =& NewADOConnection('mysql'); $db->PConnect($host,$user,$pwd,$db); $lens->connectionLookups =& $db; Alternatively, define a database connection string (defined in $PHPLENS_DATABASES, in the phplens/config/phplens.config.inc.php file). $lens->connectionLookups = 'mysql_db2'; PHPLens will create a persistent connection. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

css

Colors
css
CSS include file. Default: `'phplens/img/phplens.css'` CSS file to include that contains CSS definitions. Should be the absolute path if defined. See the CSS Blue and CSS Red examples, which make use of the default phplens/img/phplens.css file. Syntax `$lens->css = '/css/site.css';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.4.10]

curState

Programming
curState
Current phpLens state. Legal states: 'VIEW' means view the normal grid 'EDIT' means edit a record 'FILTER' is when we are in the search screen but have not initiated a search. 'FILTERVIEW' means we have initiated a search 'NEW' is when we are creating a new record 'EDITSAVE', see below, has been available since phpLens 2.4.2. 'HIDE' hides the phplens object. Available since phpLens 3.2. This property is read-only and should not be changed directly. To force a record edit or to create a new record or to force a search, use GET variables instead, as documented in the FAQ at http://phplens.com/lens/faq/faq.php?#402 New to phpLens 2.4.2 is the EDITSAVE state. Set firstState = 'EDITSAVE' when we want to display an EDIT screen in firstState, but after we successfully save, we want switch to VIEW. Also if firstState is EDIT and we click on Save and save was successful, we set curState to EDITSAVE. This is a state that is otherwise identical to EDIT. To maintain backward compatiblity, to detect EDIT state, we suggest using substr($this->curState,0,4) == 'EDIT' HIDE The curState property is normally read-only, but you can hide the phpLens object for 1 page request by setting $lens->curState = 'HIDE'. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

dataVers

Information and Debugging
dataVers
Version number of phpLens internal data format Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

debug

Information and Debugging
debug
Debug level. 0=none, 1=show SQL, 2=detailed view Default: `0` The settings are -1 = show template skeletons 0 = no debugging 1 = show SQL and phpLens state 2 = show lots of information Syntax `$lens->debug = Integer;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

debugDie

Information and Debugging
debugDie
Print SQL generated by phpLens and halt execution. Default: `false` Useful for debugging poorly optimized SQL that is running too long. The SQL is not executed. Syntax `$lens->debugDie = 1;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0]

defaultLens

Editing, Updating and Creating Records
defaultLens
On new record, these are the default values of specified fields When creating a new record, you might want a default value to be automatically entered. You can enter a normal string (without quotes) or number, or generate the value dynamicly using PHP or your RDBMS. Default values can be hard-coded values, or you can execute PHP code if you prefix with the equals(=) character. Dates can either be generated in Unix timestamp format provided you return the value as an integer, or in 'Y-m-d H:i:s' format. Executing PHP Code When you want the value to be dynamically generated by PHP, set the first character to an equals (=) to treat the following text as PHP code. To generate the current date, use the PHP time function like this: =time() PHP Globals To access global variables, before 3.2, you needed to use the following: =$GLOBALS['PHP_SELF'] Since 3.2, you can use this directly: =$PHP_SELF Database Example To access the ADODB connection from here, use the following example, which passes the connection object to the getvalue function:
    $lens->defaultLens = 'col1^=getvalue($this->lens->connection)';
Executing SQL Code Sometimes, you have a read-only field whose value is generated by your SQL server and not by the user. You can do this by setting the first character to percentage (%) to treat the following text as SQL code. Since 2.5.2, you can also put PHP global variables in the SQL string. To set a column to a random number in Microsoft SQL server, use the rand function like this: %rand() Syntax `To set a field called thetime to the current datetime: $lens->defaultLens = 'thetime^=time()' To execute a standard SQL function for a field called rr: $lens->defaultLens = 'rr^%rand()';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

detailFontPrefix
Warning: flock(): 804 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Table Cell formating
detailFontPrefix
Tags to prefix to cell data for detail, new and edit tables Default: `'<font size=2>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

detailFontSuffix

Table Cell formating
detailFontSuffix
Tags to append to cell data for detail, new and edit tables Default: `'</font>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

detailHdr
Warning: flock(): 700 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Table and Grid formating
detailHdr
Attributes of <TR> tag for detail table Default: `'valign=top'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

detailLeftColor

Colors
detailLeftColor
Color of left column of detail grid and edit/new record Color of left column of edit form, new record form, and detail grid. Syntax `$lens->detailLeftColor='red'; # with alternative CSS $lens->detailLeftColor='red class=redcss';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

detailLens

Table Rows and Columns
detailLens
This lens sets which fields are shown in the detail table Default: `Normally all fields in the recordset` Syntax `$lens->detailLens = 'FieldName1;FieldName2;FieldName3';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

detailRightColor

Colors
detailRightColor
Color of right column of detail grid or edit/new record Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

detailTableHeader

Table and Grid formating
detailTableHeader
Attributes of detail <table> tag Default: `'width=100% BORDER=1 cellspacing=0 cellpadding=2'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

detailTitleFontPrefix

Table Column/Field Titles
detailTitleFontPrefix
Tags to prefix to detail, edit, new, filter table column titles Default: `'<i>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

detailTitleFontSuffix

Table Column/Field Titles
detailTitleFontSuffix
Tags to append to detail table column titles Default: `'</i>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

detailTitleHeader

Table and Grid formating
detailTitleHeader
Attributes of TD tag for field titles Default: `''` Sets the TD tag attributes of the detail grid for titles. Syntax `$lens->detailTitleHeader = 'class=title';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3]

detailValueHeader

Table and Grid formating
detailValueHeader
Attributes of TD tag for field values in detail grid Default: `''` Syntax `$lens->detailValueHeader = 'class=detailvals';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3]

displaySep

Programming
displaySep
The separator used to display the checkbox choices Default: `', '` When selecting multiple checkboxes, the choices selected are stored in the field, using the displaySep as the separator. For example, you have a set of checkboxes storing the following values: "Giraffe", "Lion", "Zebra". The user selects the first two values, so we store in the database "Giraffe, Lion". If the displaySep was '||', then we would store "Giraffe||Lion". The default is comma-space (', '). Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.1]

dynEdit

Essential
dynEdit
Turn on dynamic editing Default: `true` Use this to determine whether users can modify phpLens dynamic settings. When dynEdit is disabled, all dynamic edit settings are not loaded from the phpLens table. So make sure you Generate PHP Code and paste your changes into your .php file before turning off dynEdit. Sometimes the phpLens source code settings are in conflict with the dynamic editing settings. In this case you should Generate PHP Code and save it as a backup. Then click on the Remove Settings to wipe out all dynamic editing settings that might be in conflict with your PHP source code. Finally, manually merge any settings from the backup to that are missing in the original source code. Syntax `$lens->dynEdit = Boolean;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

dynUseSessions

Programming
dynUseSessions
Use dynamic editing settings Default: `true` Set this to false if you want to ignore dynamic editing settings. This will speed up phpLens because phpLens will not query the phpLens table to get configuration settings. This means that all dynamic editor settings are ignored. When using applets, dynUseSession is always set to false. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

editClick

Editing, Updating and Creating Records
editClick
Set to true to edit a record when you click anywhere in a row Default: `false` Due to problems with browser incompatibilities, this property is no longer supported. Though we will leave it available for backward compatibility, we will not entertain any support requests regarding using this property. Set to true to enable. This only works when the keyCol property is defined (eg. the primary key is known), editMultiple = false and no child editor is configured (childLens property). Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.4]

editHiddenTags

Editing, Updating and Creating Records
editHiddenTags
Define hidden input tags to be included in edit form Any invisible tag can be defined here. These tags can be used to embed any additional information that you require for your own processing. Syntax `$lens->editHiddenTags = '<input type=hidden name=test2 value=22>';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

editLens

Editing, Updating and Creating Records
editLens
This lens sets which fields are shown when editing This is normally combined with readonlyLens for fields that are viewable but not modifiable. Syntax `$lens->editLens = 'FieldName1;FieldName2;FieldName3';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

editMultiple

Editing, Updating and Creating Records
editMultiple
Allow editing of multiple records in the grid Default: `false` Requires the keyTable and keyCol properties to be set. If the column is defined in both editLens and gridLens, the column is editable. If the column is defined only in gridLens, then the column is read-only. The details grid is not modified by this property and remains read-only. Works with popup hot updates, must-fill checking and also type checking. If you are using the templateGrid property, then make sure you display the _RECNO_ because some of the hidden input fields are stored with the _RECNO_. Currently the main limitation is that client-validation with javascript is not supported. Commits Before 3.1, the saving of each record is treated as a separate transaction. So if 3 records are saved, then 3 transactions are generated. In 3.1 and later, all 3 records will be saved in 1 transaction. Syntax `$lens->editMultiple = true;` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0]

editNewRadioCheckBoxTD

Editing, Updating and Creating Records
editNewRadioCheckBoxTD
Control checkbox style and formating in edit/new record form All checkboxes and radio buttons are laid out in an invisible table. This allows you to control the cell formatting of this invisible table, to set font sizes and other formatting. Syntax `$lens->editNewRadioCheckBoxTD = 'class=small';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

editTableHeader

Table and Grid formating
editTableHeader
Attributes of <table> tag used in editing/updating Default: `'BORDER=1 cellspacing=0 cellpadding=2'` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

emptyCharIsNull

Editing, Updating and Creating Records
emptyCharIsNull
If true, then zero length strings are stored as nulls Default: `false` This applies when the metatype is 'C' or 'X' (char and varchar) and strlen($data) == 0. Note that we do not trim the data first, so if you want to also strip off white-space, you will have to do it manually using spEdit or spNew properties. Syntax `# the following fields will store null when the string is empty. $lens->emptyCharIsNull = 'field1;field2';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.7.2]

emptyDatesNull

Editing, Updating and Creating Records
emptyDatesNull
Date to use when date is empty on Insert/Update Default: `'null'` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

errHideMessages

Error Handling, Redirects
errHideMessages
Hide warning messages Default: `LENSNOTICE (hide all notices)` If $lens->errHideMessages = 0, then all errors and notices are shown. To hide all notices (normally harmless warnings). $lens->errHideMessages = LENSNOTICE; The only notice currently is that no records can be found. $lang->txtErrNoRecords = "No records found"; The following will hide all notices and warnings. Warnings are mostly data entry errors. $lens->errHideMessages = LENSWARNING; Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.3]

errorHandler

Programming
errorHandler
Define errorHandler function that is called when errors occur 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 Syntax `function show_error($msg, $severity, $objid) { if ($severity >= LENSERROR_SEVERE) { @mail('admin',"Error $objid",$msg); die(); } return true; } $lens->errorHandler = 'show_error';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

errorPrefix

Error Handling, Redirects
errorPrefix
Prefix to apply to all error messages displayed Default: `'<div align=center><h3>$error</h3>'` $error is set to the localised text "Error". Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

errorSuffix

Error Handling, Redirects
errorSuffix
Suffix to be applied to all error messages displayed Default: `'</div>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

evenHeader

Table Rows and Columns
evenHeader
Attributes of <TR> tag of even rows of grid Default: `'valign=top'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventDetailView

Table and Grid formating
eventDetailView
Calls PHP function defined here whenever the detail view changes This event will be triggered as long as a keyCol primary key has been defined. The easiest way to explain this is to give an example: The detail view is useful for emulating user interfaces such as email readers. Whenever we view an email, we want to mark the email as read. So we do the following: function MarkAsRead($id) { global $DB; $DB->Execute("update table set read=1 where id=$id and read=0"); } $lens->eventDetailView('MarkAsRead'); Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0]

eventPostDeleteSQL

Editing, Updating and Creating Records
eventPostDeleteSQL
Name of function to call after record is deleted. The function is passed 3 parameters. The first parameter is $key, the primary key. The second is $deleteok which is set to true if the record was deleted correctly. The 3rd parameter is the $lens object. Syntax `$lens->postDeleteSQL = 'DeleteChildren'; function DeleteChildren($key,$ok,$lens) { if ($ok) $lens->connection->Execute( "delete * from childtable where parentid=$key" ); }` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPostInsertSQL

Editing, Updating and Creating Records
eventPostInsertSQL
Name of function to call after New Record is created The function is passed 3 parameters. The first parameter is $key, the primary key. The second is $insertok which is set to true if the record was inserted correctly. The 3rd parameter is the $lens object. Note that some PHP extensions do not support the insert_id() function such as Oracle/OCI8 and Interbase (we set $key to the OID in PostgreSQL). For those databases, the $key variable will be empty. If you are using sequences to set the default value of the primary key, then you can still obtain the current value of the sequence. For example if you are using oci8 and $seqname holds the name of your sequence: `$rs = $lens->connection->Execute("SELECT $seqname.currval FROM dual"); $key = $rs->fields[0];` Syntax `function preinsert($lens) { GLOBAL $HTTP_POST_VARS; $lens->connection->BeginTrans(); } function postinsert($key, $insertok, $lens) { if ($insertok) { $rs = $lens->Execute("insert into childtable (parent) values ($key)"); if ($rs) $lens->connection->CommitTrans(); else $insertok = false; } if (!$insertok) { $lens->connection->RollbackTrans(); } } $lens->eventPreInsertSQL = 'preinsert'; $lens->eventPostInsertSQL = 'postinsert';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPostUpdateSQL

Editing, Updating and Creating Records
eventPostUpdateSQL
Name of function to call after record is changed The function is passed 3 parameters. The first parameter is $key, the primary key. The second is $updateok which is set to true if the record was updated correctly. The 3rd parameter is the $lens object. Syntax `function preupdate($key, $lens) { GLOBAL $HTTP_POST_VARS; $lens->connection->BeginTrans(); } function postupdate($key, $updateok, $lens) { if ($updateok) { $rs = $lens->Execute("update table set values=??? where parentid=$key"); if ($rs) $lens->connection->CommitTrans(); else $updateok= false; } if (!$updateok) { $lens->connection->RollbackTrans(); } } $lens->eventPreUpdateSQL = 'preupdate'; $lens->eventPostUpdateSQL = 'postupdate';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPreDeleteSQL

Editing, Updating and Creating Records
eventPreDeleteSQL
Name of function to call before record is deleted. This function will be passed 2 parameters, $key, the primary key of the relevant record, and the $lens object. This function is typically used to initiate a transaction. The transaction is completed in the eventPostDeleteSQL function. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPreInsertField

Editing, Updating and Creating Records
eventPreInsertField
Name of function to call before every field is processed for new records This function should have 3 parameters. $colname is the field name, &$data is the data and $type is the ADODB data type (not the native type). For $data, dates are passed as strings in 'Y-m-d h:i:s' format, eg. 4pm 23rd February 2002 is '2002-02-23 16:00:00'. Strings are passed without quoting. Do not quote strings yourself because phpLens does it for you. For $type, legal values are X (long text), B (blob/image), D (date), T (timestamp), C (char), N (numeric), I (integer). See ADODB readme.htm documentation. Return a value of -2 to cancel the insert, show the New Record form, and clear all fields -1 to skip this field when inserting, 0 to cancel the insert, show the New Record form, leaving all fields unchanged 1 to continue inserting. There is no eventPostInsertField property. ### Example `//I want to cancel the insert if one //specific column has one specific value... $lens->eventPreInsertField = 'CheckField'; // return -1 = skip processing this field // return 0 = cancel INSERT sql // return 1 = process this field and continue INSERT sql function CheckField($colname, $data, $type) { // $colname is uppercase if ($colname == 'FIELDTOCANCEL' and $data == 'datatocancel') return 0; // cancel return 1; // normal }` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPreInsertSQL

Editing, Updating and Creating Records
eventPreInsertSQL
Name of function to call before New Record is created This function will be passed 1 parameter, the $lens object (unlike eventPreDeleteSQL and eventPreUpdateSQL which get 2 parameters). This function is typically used to initiate a transaction. The transaction is completed in the eventPostInsertSQL function. This property is obsolete. We recommend using spNew instead. Syntax `function preinsert($lens) { GLOBAL $HTTP_POST_VARS; $lens->connection->BeginTrans(); } function postinsert($key,$insertok, $lens) { if ($insertok) { $rs = $lens->Execute('update some table with $key values'); if ($rs) $lens->connection->CommitTrans(); else $insertok = false; } if (!$insertok) { $lens->connection->RollbackTrans(); } } $lens->eventPreInsertSQL = 'preinsert'; $lens->eventPostInsertSQL = 'postinsert';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPreUpdateField

Editing, Updating and Creating Records
eventPreUpdateField
Name of function to call before every field is processed for updates This function should have 3 parameters. $colname is the field name, &$data is the data and $type is the ADODB data type (not the native type). For $data, dates are passed as strings in 'Y-m-d h:i:s' format, eg. 4pm 23rd February 2002 is '2002-02-23 16:00:00'. Strings are passed without quoting. Do not quote strings yourself because phpLens does it for you. For $type, legal values are X (long text), B (blob/image), D (date), T (timestamp), C (char), N (numeric), I (integer). See ADODB readme.htm documentation. Returns a value of -1 to skip this field when updating, 0 to cancel all updates, and 1 to continue updating. There is no eventPostUpdateField property. Syntax `// return -1 = skip processing this field // return 0 = cancel UPDATE sql // return 1 = process this field and continue UPDATE sql function UpdateField($colname,&$data,$type) { print "<BR>$colname[$type] = $data"; return 1; // update everything } $lens->eventPreUpdateField = 'UpdateField';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

eventPreUpdateSQL

Editing, Updating and Creating Records
eventPreUpdateSQL
Name of function to call before record is changed This function will be passed 2 parameters, $key, the primary key of the relevant record, and the $lens object. This function is typically used to initiate a transaction. The transaction is completed in the eventPostUpdateSQL function. This property is obsolete. We recommend using spEdit instead. Syntax `function preupdate($key, $lens) { GLOBAL $HTTP_POST_VARS; $lens->connection->BeginTrans(); } function postupdate($key, $updateok, $lens) { if ($updateok) { $rs = $lens->Execute("update table set values=??? where parentid=$key"); if ($rs) $lens->connection->CommitTrans(); else $updateok= false; } if (!$updateok) { $lens->connection->RollbackTrans(); } } $lens->eventPreUpdateSQL = 'preupdate'; $lens->eventPostUpdateSQL = 'postupdate';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

exportLens

Editing, Updating and Creating Records
exportLens
List of fields to export as Excel file or CSV when they click on the export button List of fields to export as CSV or as an Excel file. All carriage returns are converted to spaces. The files generated need to be stored in a temporary directory before they are downloaded. Set the temporary directory using the imageTmpDir property. Excel files are generated using the LGPL class, SimpleXlsGen, which can be found in phplens-excel.inc.php. We conform to Microsoft Excel 5.0 File Format. They are exported by default with the .xls extension. For CSV, all text fields are quoted with double-quotes, and double-quotes are escaped with double-quotes, following Microsoft Excel CSV conventions. CSV files generated are by default exported with the .csv extension. The source code for the exporting can be found in phplens-template.inc.php. You can also modify the mime types used from this file. The actual file downloading to your web browser is performed by a helper script, phplens-img.php. By default, all records will be exported in Excel format. Also see the exportOptions property to change the defaults, or change the file name to use for exports. Microsoft Excel is a copyrighted product of Microsoft Corporation. Syntax `$lens->exportLens = 'ProductName;Supplier;UnitPrice';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 2.2]

exportOptions

Editing, Updating and Creating Records
exportOptions
Export options for exportLens property Default: `'CSV'` The default of exportLens is to export all records in CSV format. To only export current page, set exportOptions = 'CURPAGE'. To export Excel format instead of CSV, remove the 'CSV' setting from exportOptions. To change export file name, use exportOptions="NAME^export-\$DATE.xls". The $DATE in the file name will be replaced with the current date in Y-m-d format. Note: In 2.4.10, default export mode was changed from Excel to CSV. Syntax `# use ; to combine choices, for example: # export CSV, only current page, with name file.csv $lens->exportOptions = 'CSV;CURPAGE;NAME^file.csv';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.2]

fields

Programming
fields
Holds the data of the current record in VIEW/FILTERVIEW This array is only valid after Render() is called. As each row from a SQL query is processed, this property is updated. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fieldSep

Programming
fieldSep
Seperator between multiple settings for a single column Default: `'^'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fileSessionPath

Information and Debugging
fileSessionPath
For non-applet phpLens objects, store session info in a file instead of in the phpLens table Instead of saving phpLens settings in a database table, save in a file stored in the directory refered to by fileSessionPath. This makes it easy to install new phpLens objects because you do not need to download and upload database records, but simply copy the phplens settings files into the fileSessionPath directory. This property is smart enough to attempt reading from phplens table in database if session file not found, so is backward compatible with old phplens objects. Warning: This might not work in safe mode. Save settings to a database table instead. Syntax `$lens->fileSessionPath = '/tmp';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.5.0]

filterAllOr

Filtering and Searching
filterAllOr
Search clauses are ORed Default: `false` The default (filterAllOr = false) will cause a filter/search on column1, column2 like this (assume that exact match has been configured): SELECT * FROM table WHERE column1 = '$col1' AND column2 = '$col2'; When filterAllOr = true, this becomes SELECT * FROM table WHERE column1 = '$col1' OR column2 = '$col2'; Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

filterAnyWhere

Filtering and Searching
filterAnyWhere
Determines whether the match anywhere in the filter/search form is visible Default: `true` For scalability, we might not want a user to search for substrings in any field. To disable this feature, set $lens->filterAnyWhere = false; Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

filterDefaults

Filtering and Searching
filterDefaults
Set the default values for filtering/searching If you have 2 search fields, the first being a free text field for product launch date with the default being all products to be launched in the future(m/d/Y), and the second is a set of checkboxes, indicating product status, and you want the checkboxes "Development" and "Launching" checked, then set: $lens->filterDefaults = "launchdate^>".date('m/d/Y').';status^Development/Launching'; If today is 21 January 2004, this will generate: $lens->filterDefaults = "launchdate^>1/21/2004;status^Development/Launching'; Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 3.3]

filterFontPrefix

Filtering and Searching
filterFontPrefix
Tags to prefix to search criteria for filter/search table Default: `'<font size=3>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

filterFontSuffix

Filtering and Searching
filterFontSuffix
Tags to append to search criteria for filter/search table Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

filterLens

Filtering and Searching
filterLens
This lens determines which fields are to be used when filtering/searching Default: `Will use the gridLens settings.` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

filterModifierFn
Warning: flock(): 1996 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Filtering and Searching
filterModifierFn
Allows you to perform special searching on a column Allows you override normal WHERE searching clauses, so you can use database specific syntax. Useful for full text search and case-sensitive matching. Formerly named filterLikeFunction. First a quick overview of how it works. Let's say we have a WHERE clause for field id: id = 'abc' which we want to rewrite to: id like 'abc%' Now the filter modifier works by breaking the string to the component parts: `$colname = 'ID' # automatically converted to uppercase for you $oper = ' = ' $prefix = "'" $valArray = array('abc') $suffix = "'"` We need to change it to: `$colname = 'ID' # automatically converted to uppercase $oper = ' like ' $prefix = "'" # remains unchanged $valArray = array('abc%') $suffix = "'" # remains unchanged` or `$colname = 'ID' # automatically converted to uppercase $oper = ' like ' $prefix = "'" # remains unchanged $valArray = array('abc') # remains unchanged $suffix = "%'"` Since phpLens 2.5.2, we have added two additional parameters to the function, $valueArray and $inputArray. function LensFilterFn(&$colname,&$oper, &$prefix, &$suffix, &$quote, $matchMode, &$valArray, &$inputArr) $colname is the name of the column $oper is the operator to use (LIKE/=) $prefix is the prefix to attach to the search string $suffix is the suffix to attach to the search string $quote = true to let phplens quote the search string, false if you do it yourself, default is true (phplens quotes for you) $matchMode is 0 == exact match, 1 = match beginning, 2 = match anywhere. $valueArray is an array holding the values keyed in by the user. It is an array because a series of checkboxes could have been keyed in. $inputArray allows you to use data binding. Initially set to false, modify this to set an array value. See example 4 below. So the above change to ID can be implemented with `function LensLikeFn(&$colname,&$oper, &$prefix, &$suffix, &$quote, $matchMode, &valArray) { if ($colname == 'ID') { $oper = ' LIKE '; $valArray[0] .= '%'; } }` Syntax `Example 1: MySQL Full Text Search /********************************************************************************* example to support say mysql full text search for column 'message': SELECT * FROM articles WHERE MATCH (message) AGAINST ('text'); *********************************************************************************/ function LensLikeFn(&$colname,&$oper, &$prefix, &$suffix, &$quote, $matchMode) { if (strtoupper($colname) == 'MESSAGE') { $quote = false; $colname = " MATCH ($colname) "; $oper = " AGAINST "; $prefix = "('"; $suffix = "')"; } } $lens->filterModifierFn= 'LensLikeFn'; Example 2: Switch to using PostgreSQL ILIKE operator # ILIKE is case sensitive function LensLikeFn(&$colname,&$oper, &$prefix, &$suffix, &$quote, $matchMode) { if (strtoupper($oper) == ' LIKE ') $oper = ' ILIKE '; } $lens->filterModifierFn= 'LensLikeFn'; Example 3: Using Full Text Search in Microsoft SQL Server /********************************************************************************* To support full text search for column 'message': SELECT * FROM articles WHERE CONTAINS(message,'text'); *********************************************************************************/ function LensLikeFn(&$colname,&$oper, &$prefix, &$suffix, &$quote, $matchMode) { if (strtoupper($colname) == 'MESSAGE') { $quote = false; $oper = " CONTAINS($colname,"; $colname = ""; $prefix = "'"; $suffix = "')"; } } $lens->filterModifierFn= 'LensLikeFn'; Example 4: Implementing data binding with oci8 function LensLikeFn(&$colname,&$oper, &$prefix, &$suffix, &$quote, $matchMode,&$valArray,&$inputArr) { foreach ($valArray as $k => $v) { if ($matchMode == 1) $v .= '%'; else if ($matchMode == 2) $v = '%'.$v.$'%'; $inputArr[$colname.$k] = $v; $valArray[$k] = ':'.$colname.$k; } } $lens->filterModifierFn= 'LensLikeFn';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

filterParams

Filtering and Searching
filterParams
Additional settings that are used internally by filterLens To save these settings as source code, go to Search/Filter mode, change the field settings, generate PHP code and save the filterParams and filterLens properties. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

filterRadioCheckBoxTD

Filtering and Searching
filterRadioCheckBoxTD
Control checkbox style and formating in filter form All checkboxes in the filter form are formatted in an invisible table. This allows you to control the cell properties, including the font size with CSS. Syntax `$lens->filterRadioCheckBoxTD = 'class=small';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

filterShowForm

Filtering and Searching
filterShowForm
When filtering/searching, show the filterscreen and grid together Default: `true` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

filterTableCols

Filtering and Searching
filterTableCols
The number of field columns to display Default: `1` This allows you to display multiple fields in one row. Formerly 3 search fields would display by default as: Field 1: [ ] Field 2: [ ] Field 3: [ ] Search Cancel Now by setting $lens->filterTableCols = 3; the fields will appear as Field 1: [ ] Field 2: [ ] Field 3: [ ] Search Cancel Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 3.1]

filterTableHeader

Table and Grid formating
filterTableHeader
Attributes of filter table Default: `'BORDER=1 cellspacing=0 cellpadding=2 BGCOLOR=silver'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

filterTopColor

Colors
filterTopColor
The background color of the top of the search/filter form If no value is defined for this property, then it will use the $lens->colorTitle property used by the Edit/New record form. Syntax `$lens->filterTopColor = 'red class=topbar'; # red, or use CSS class topbar` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3.3]

filterUseLike

Filtering and Searching
filterUseLike
Determines whether searching strings will match using SQL LIKE Default: `1 (match from beginning)` 0 == exact match, 1 = match beginning, 2 = match anywhere. The user can override the settings. This is the session default. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

firstState

Programming
firstState
Which screen to show on startup and when phpLens is reset Default: `VIEW` Usually we set firstState to VIEW or FILTER on startup. We set it to VIEW if we want to view the grid on startup. We set it to FILTER if we want a search screen to appear on startup. Additional Notes If you want phpLens to create a new record on startup, set it to NEW. If you want phpLens to edit a specific record on startup, use the URL: $PHP_SELF?lens_$id=e&lens_p1=$primarykey where $id is the id you passed to phpLens and $primarykey is the primary key of the record that matches $lens->keyCol. EDITSAVE New to phpLens 2.4.2 is the EDITSAVE state. Set firstState = 'EDITSAVE' when we want to display an EDIT screen in firstState, but after we successfully save, we want switch to VIEW. Also see curState. Syntax `$lens->firstState = "state"; where legal state values are: 'VIEW', 'FILTER', 'EDIT' or 'NEW'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

fmtDateInput

Editing, Updating and Creating Records
fmtDateInput
The default date input format Default: `Taken from language settings` Default for USA is "m/d/Y". a - "am" or "pm" A - "AM" or "PM" d - day of the month, 2 digits with leading zeros; i.e. "01" to "31" D - day of the week, textual, 3 letters; i.e. "Fri" F - month, textual, long; i.e. "January" -- uses short always g - hour, 12-hour format without leading zeros; i.e. "1" to "12" G - hour, 24-hour format without leading zeros; i.e. "0" to "23" h - hour, 12-hour format; i.e. "01" to "12" H - hour, 24-hour format; i.e. "00" to "23" i - minutes; i.e. "00" to "59" j - day of the month without leading zeros; i.e. "1" to "31" l (lowercase 'L') - day of the week, textual, long; i.e. "Friday" m - month; i.e. "01" to "12" M - month, textual, 3 letters; i.e. "Jan" n - month without leading zeros; i.e. "1" to "12" s - seconds; i.e. "00" to "59" w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday) Y - year, 4 digits; i.e. "1999" y - year, 2 digits; i.e. "99" Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

fmtDateOutput

Table Cell formating
fmtDateOutput
Default format of dates for display in grid or detail table Default: `Taken from language settings` Default for USA is "M-d-Y". a - "am" or "pm" A - "AM" or "PM" d - day of the month, 2 digits with leading zeros; i.e. "01" to "31" D - day of the week, textual, 3 letters; i.e. "Fri" F - month, textual, long; i.e. "January" -- uses short always g - hour, 12-hour format without leading zeros; i.e. "1" to "12" G - hour, 24-hour format without leading zeros; i.e. "0" to "23" h - hour, 12-hour format; i.e. "01" to "12" H - hour, 24-hour format; i.e. "00" to "23" i - minutes; i.e. "00" to "59" j - day of the month without leading zeros; i.e. "1" to "31" l (lowercase 'L') - day of the week, textual, long; i.e. "Friday" m - month; i.e. "01" to "12" M - month, textual, 3 letters; i.e. "Jan" n - month without leading zeros; i.e. "1" to "12" s - seconds; i.e. "00" to "59" w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday) Y - year, 4 digits; i.e. "1999" y - year, 2 digits; i.e. "99" Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

fmtDecimal

Table Cell formating
fmtDecimal
Decimal character Default: `'.'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fmtDecimalDB

Editing, Updating and Creating Records
fmtDecimalDB
The character that the database uses for decimal places on INSERT/UPDATE Default: `'.'` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.3]

fmtDecimalPlaces

Table Cell formating
fmtDecimalPlaces
Number of decimal places to display for numeric data Default: `2` This property is for display purposes only. When editing a record, we display the full precision of the data and ignore this property. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fmtThousands

Table Cell formating
fmtThousands
Thousands seperator for numbers Default: `','` This is for display purposes only and does not modify the data. Set to empty string to disable. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fmtTimeStampInput

Editing, Updating and Creating Records
fmtTimeStampInput
Default format of timestamps for data entry Default: `$lens->lang->fmtTimeStampInput` Default for USA is "m/d/Y h:i:s A". a - "am" or "pm" A - "AM" or "PM" d - day of the month, 2 digits with leading zeros; i.e. "01" to "31" D - day of the week, textual, 3 letters; i.e. "Fri" F - month, textual, long; i.e. "January" -- uses short always g - hour, 12-hour format without leading zeros; i.e. "1" to "12" G - hour, 24-hour format without leading zeros; i.e. "0" to "23" h - hour, 12-hour format; i.e. "01" to "12" H - hour, 24-hour format; i.e. "00" to "23" i - minutes; i.e. "00" to "59" j - day of the month without leading zeros; i.e. "1" to "31" l (lowercase 'L') - day of the week, textual, long; i.e. "Friday" m - month; i.e. "01" to "12" M - month, textual, 3 letters; i.e. "Jan" n - month without leading zeros; i.e. "1" to "12" s - seconds; i.e. "00" to "59" w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday) Y - year, 4 digits; i.e. "1999" y - year, 2 digits; i.e. "99" Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

fmtTimeStampOutput

Table Cell formating
fmtTimeStampOutput
Default format of timestamps for display Default: `$lens->lang->fmtTimeStampOutput` For USA, default is "M-d-Y h:i:s A". a - "am" or "pm" A - "AM" or "PM" d - day of the month, 2 digits with leading zeros; i.e. "01" to "31" D - day of the week, textual, 3 letters; i.e. "Fri" F - month, textual, long; i.e. "January" -- uses short always g - hour, 12-hour format without leading zeros; i.e. "1" to "12" G - hour, 24-hour format without leading zeros; i.e. "0" to "23" h - hour, 12-hour format; i.e. "01" to "12" H - hour, 24-hour format; i.e. "00" to "23" i - minutes; i.e. "00" to "59" j - day of the month without leading zeros; i.e. "1" to "31" l (lowercase 'L') - day of the week, textual, long; i.e. "Friday" m - month; i.e. "01" to "12" M - month, textual, 3 letters; i.e. "Jan" n - month without leading zeros; i.e. "1" to "12" s - seconds; i.e. "00" to "59" w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday) Y - year, 4 digits; i.e. "1999" y - year, 2 digits; i.e. "99" Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

fmtTimeStampsAsDates

Table Cell formating
fmtTimeStampsAsDates
Force all timestamps to appear as dates. Default: `false` Some databases do not have a date type. This will force all timestamps to mimic dates. Syntax `$lens->fmtTimeStampsAsDates = true;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fontSelColPrefix

Table Column/Field Titles
fontSelColPrefix
Attributes to prefix currently selected (sort) column title Default: `'<font size=+1>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

fontSelColSuffix

Table Column/Field Titles
fontSelColSuffix
Attributes to append to currently selected (sort) column title Default: `'</font>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

forceType

Programming
forceType
Change the type of a column This is useful for changing datetime/timestamp columns to type date, or logical to integer. We use the ADODB type codes. If a number or integer is forced to date or timestamp, then we assume that the number is a Unix timestamp. C: character and varchar types X: text or long character (eg. more than 255 bytes wide). B: blob or binary image D: date T: timestamp L: logical (boolean) I: integer J: positive integer (>= 0) N: numeric (float, double, money) P: positive numeric (>= 0.0) Note that we do not modify the field types in your database. This property is for display and data entry type checking purposes only. Syntax `# change col1 to type 'D' for date $lens->forceType = 'col1^D';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

getFieldsFromTables

Editing, Updating and Creating Records
getFieldsFromTables
If sql select statement returns no fields, then we get field info from these tables Some databases do not return any field information if no records are returned (because the tables are empty). As a workaround, we have this property. When sql select statement returns no fields, then we get field info from the fields of these tables (comma-separated). Note: Make sure all tables listed have unique field names. Having order.id and product.id will confuse phpLens. Syntax `$lens->sql = 'select * from order, product where order.prod_id = product.id'; $lens->getFieldsFromTables = 'order, product';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.0.6]

gridHeight

Table and Grid formating
gridHeight
Used to fix the main grid's height to a certain amount Default: `''` Default is that the grid height is determined by the Web browser. You can set this to a percentage (eg. 100%) or number of pixels (eg. 200), but it is not guaranteed to work because the browser can override your settings. Syntax `$lens->gridHeight='100%' // means 100% of the enclosing page/table's height $lens->gridHeight=600; // means that the grid is 600 pixels tall` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

gridLens

Table Rows and Columns
gridLens
This lens sets which fields are shown in the grid Default: `The first 5 fields of the recordset are displayed` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

gridReadOnlyLens

Editing, Updating and Creating Records
gridReadOnlyLens
Sets fields cannot be modified when editMultiple is true This lens sets which fields cannot be modified when editMultiple is true in the grid. Note that the gridReadOnlyLens property is additive with readOnlyLens, in that readOnlyLens also affects which fields cannot be modified when editMultiple is true also. Syntax `$lens->gridReadOnlyLens = 'ProductID;ProductName';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.2]

gridTableHeader

Table and Grid formating
gridTableHeader
Attributes of grid <table> tag Default: `'width=100% border=1 cellspacing=1 cellpadding=1'` This was formerly set to 'width=100% border=1 cellspacing=0 cellpadding=2' which looks really nice in IE, but it looked horrible in Mozilla, so we changed it so that phpLens looks equally good (or bad) in all browsers. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

groupDesc

Grouping and totaling of rows
groupDesc
Use groupLens sorted descending Default: `false` The property groupLens by default orders rows ascending. Set this to true to sort descending. Syntax `$lens->groupDesc = true;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.4.4]

groupFontPrefix

Table Cell formating
groupFontPrefix
The tags prefixed to the group text Default: `'<font size=2><b>&nbsp; '` Activated when groupLens is set. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

groupFontSuffix

Table Cell formating
groupFontSuffix
Tags appended to grouped text Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

groupLens

Grouping and totaling of rows
groupLens
Group rows by this data column This Lens will order your data by a the specified column, and show a divider in the grid marking the beginning of all records in that group. You can also subTotal groups using the sumLens property. For example you have a MEMBERS table which is a list of people who are members of a club. In the table there is a field called STATE indicating what US State the user resides in. Setting `$lens->groupLens='STATE';` will produce the following if the grouping field is visible:
Alaska | Abraham | Nielson
Joseph Ahmed | Boesky
Bill | Baggins
Arkansas | Mee | Siam
Maido | Bola
Billy | Clinton
and if the grouping field is hidden:
Alaska
Abraham | Nielson
Joseph Ahmed | Boesky
Bill | Baggins
Arkansas
Mee | Siam
Maido | Bola
Billy | Clinton
To disable the error message which appears if the groupLens column is missing, set the language file class variable $txtErrGroupLens to an empty string (""). Syntax `$lens->groupLens = 'ColumnName';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

groupSep

Programming
groupSep
Separator between column settings Default: `';'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

hideAnchorName

Navigation Bar and Menu
hideAnchorName
When true, hides the anchor name that is generated by phpLens so that we scroll down the browser to where the applet is located Default: `false` For example, if you have an applet called abc, then at the end of every url, we generate the following url hash: #LensBM_abc Then we place at the top of the applet the following anchor tag if hideAnchorName is false. <a name="LensBM_abc"> Then every click on a link will scroll the browser screen to just above the applet. Setting this property to true will disable the generation of this anchor tag, though the url hash will still be generated. This is useful if you want to generate the anchor name yourself in another position instead of the top of the screen, or if you want to disable this behaviour. Syntax `$lens->hideAnchorName = true;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.7.2]

htmlEditLens

Editing, Updating and Creating Records
htmlEditLens
Creates a wysiwyg HTML editor for fields when editing records The WYSIWYG editor can be customized by modifying phplens/img/htmlarea/editor.js. Thanks also to the people at interactivetools.com for releasing this software as a free component. Syntax `$lens->htmlEditLens = 'field1;field2';
Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.0]

htmlLens

Table Cell formating
htmlLens
Determines which character fields to treat as native HTML/binary (no encoding) Normally phpLens will convert all < characters to &lt;. This disables HTML tags. Setting this will stop this conversion. See the nl2br and anchorTags property. To support double byte character sets, you need to set this for all columns. You can make all columns support HTML and double byte by using *, as shown below: `$lens->htmlLens = '*';`Finally, set htmlLens for a BLOB field to prevent phpLens from treating the field as a picture field. Instead it will be treated as a text field. Syntax `$lens->htmlLens = "ColumnName1;ColumnName2.."` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]`

id

Essential
id
ID to identify this phpLens object You might have multiple phpLens objects configured on different pages. Each copy of phpLens must be assigned a unique ID. This ID must be no longer than 38 characters, and must consist only of underscores, letters or numbers (_ A-Z and 0-9). If you are using phpLens 2.0.9 or later, it is 10 characters in length. This is also part of the primary key into the phpLens table, and used in naming GET and POST variables. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

ignoreSessions

Programming
ignoreSessions
Do not register any session variables Default: `'false'` For advanced users. If this is enabled then saving, sorting in descending order, filtering and editing will not work. Syntax `$lens->ignoreSessions = Boolean;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0beta9]

imageAttributes

Graphic Images
imageAttributes
Attributes in the <img> tag such as WIDTH or HEIGHT Default: `'' Since phpLens 2.1.1, if you have the exif extension installed and leave $lens->imageAttributes empty, phpLens will auto-calculate the img tag's height and width for you, using GetImageSize( ). If you do not have exif installed and this property is not defined, we let the browser size the images. Since 2.7, we autodetect the ^ symbol, and if we detect ^, we assume that the settings are on a column by column basis. Syntax `#If you want all images to be 100 pixels wide and 120 pixels high: $lens->imageAttributes='WIDTH=100 HEIGHT=100'; #If you want to manage different sizes for different images: $lens->imageAttributes='colA^height=20;colB^height=99'; Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imageCacheSecs

Graphic Images imageCacheSecs Cache blobs stored in database in the imageTmpDir directory for imageCacheSecs Default: `0 Set to a positive number of seconds to cache images. The images are cached in the LENS_IMG_TEMP_DIR directory (PHP constant), or if that is not defined, in the $lens->imageTmpDir directory (phpLens property). Requires the primary key to be defined with the keyCol property, because we generate temporary file names using the following algorithm: $file = $lens->imageTmpDir.'/lens_'.$lens->id.'_'. md5($lens->id.$lens->keyTable.$key).'.gif'; Note that you will have to delete expired cache files yourself using cron or at.exe. PhpLens does not delete expired files. Also all files are saved with the gif extension, even if they are jpeg or png. All common web browsers ignore the file extension and auto-detect the file type correctly. Caching The following properties are used together to enable image caching: imageCacheSecs: Number of seconds to cache image imageTmpDirURL: The URL to use from the web browser to read the directory and you have to modify the following constant in the file phplens/config/phplens.img.config.inc.php LENS_IMAGETMPDIR: the path to where the images are cached So suppose the web server root directory is /htdocs, and the images are in /htdocs/img, we set `$lens->imageTmpDirURL = '/img'; $lens->imageCacheSecs = 3600 * 24 * 30; // 30 days And in phplens.img.config.inc.php define('LENS_IMAGETMPDIR','/htdocs/img'); Whenever we upload a new image to the server, the cached image file is also deleted automatically. Note: when cached images are generated, a .gif suffix is added to the filename even if the file uses some other format. This is to ensure that the images are cached by proxy servers. Compatibility Note For phpLens 2.8 and earlier, we do not use the phplens.img.config.inc.php file to store the location of the image directory. Instead you have to set the property imageTmpDir: The location of the image temporary directory on the server Then you have to modify the source code of phplens-img.php file, changing the hard-coded '/tmp' string with the correct path. Syntax `$lens->imageCacheSecs = 600; # cache 10 minutes Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.3.1]

imageDir

Graphic Images
imageDir
PhpLens icons and javascript are stored here Normally, there is no need to modify, unless you have moved the phplens code outside the Web server directories. Alternatively, define the global variable $PHPLENS_GRAPHICS_SERVER to the path to your images. Syntax `$lens->imageDir = 'http://server.com/images'; or $PHPLENS_GRAPHICS_SERVER = 'http://server.com/images'; Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imageEmpty

Graphic Images
imageEmpty
Image or text to show when no image is seen Default: `'&nbsp;'` This can be text or an IMG tag. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imageMaxSize

Editing, Updating and Creating Records
imageMaxSize
Maximum binary file to upload in bytes Default: `102400` Default is 100K. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imagePage

Graphic Images
imagePage
URL of web page used to display images Default: `'/php/phplens/phplens-img.php'` Currently this file must be placed in the phplens directory. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imageTmpDir

Graphic Images
imageTmpDir
Directory to store temporary images and export excel/csv files Default: `'/tmp'` Important. This property is obsolete in phpLens 3.0. Caching The following properties are used together to enable image caching: imageCacheSecs: Number of seconds to cache image imageTmpDirURL: The URL to use from the web browser to read the directory and you have to modify the following constant in the file phplens/config/phplens.img.config.inc.php LENS_IMAGETMPDIR: the path to where the images are cached So suppose the web server root directory is /htdocs, and the images are in /htdocs/img, we set `$lens->imageTmpDirURL = '/img'; $lens->imageCacheSecs = 3600 * 24 * 30; // 30 days` And in phplens.img.config.inc.php define('LENS_IMAGETMPDIR','/htdocs/img'); Whenever we upload a new image to the server, the cached image file is also deleted automatically. Note: when cached images are generated, a .gif suffix is added to the filename even if the file uses some other format. This is to ensure that the images are cached by proxy servers. Compatibility Note For phpLens 2.8 and earlier, we do not use the phplens.img.config.inc.php file to store the location of the image directory. Instead you have to set the property imageTmpDir: The location of the image temporary directory on the server Then you have to modify the source code of phplens-img.php file, changing the hard-coded '/tmp' string with the correct path. File Naming for Temporary Images The file name algorithm since 2.4 is: '/lens_'.$this->id.'_'.md5(strlen($blob).$this->id.$this->keyTable.$key).'.gif'; where $blob is the actual image data, and $key is the primary key value, or false if not defined. Even if the file is not a gif, we append a gif to the end to ensure that proxy servers cache the file correctly. Normally browsers are able to auto-detect the image type correctly. Also see the imageTmpDirURL property. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imageTmpDirURL

Graphic Images
imageTmpDirURL
Maps the image cache directory to a URL so that we can generate img tags efficiently The following properties are used together to enable image caching: imageCacheSecs: Number of seconds to cache image imageTmpDirURL: The URL to use from the web browser to read the directory and you have to modify the following constant in the file phplens/config/phplens.img.config.inc.php LENS_IMAGETMPDIR: the path to where the images are cached So suppose the web server root directory is /htdocs, and the images are in /htdocs/img, we set `$lens->imageTmpDirURL = '/img'; $lens->imageCacheSecs = 3600 * 24 * 30; // 30 days` And in phplens.img.config.inc.php define('LENS_IMAGETMPDIR','/htdocs/img'); Whenever we upload a new image to the server, the cached image file is also deleted automatically. Note: when cached images are generated, a .gif suffix is added to the filename even if the file uses some other format. This is to ensure that the images are cached by proxy servers. Compatibility Note For phpLens 2.8 and earlier, we do not use the phplens.img.config.inc.php file to store the location of the image directory. Instead you have to set the property imageTmpDir: The location of the image temporary directory on the server Then you have to modify the source code of phplens-img.php file, changing the hard-coded '/tmp' string with the correct path. Syntax `# see example above` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.4.8]

imageType

Graphic Images
imageType
mime type to return for binary images for GIF, PNG and JPEG, you can leave this empty because phpLens can autodetect the type. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

imageUploadFunction

Editing, Updating and Creating Records
imageUploadFunction
Name of function to call when uploading data in PHP safe mode Default: `false` In PHP safe mode, you cannot access files outside the Web server root directory. In this case phplens cannot read uploaded files with some help from you. You need to define a function which accepts one parameter, the PHP4 upload array and returns as a binary string the contents of the file to be uploaded. Set the name of this function to the imageUploadFunction property. This array is equivalent to $HTTP_POST_FILES['tmpfile']. `function uploadimg($arr) { $fp = fopen($arr['tmp_name'],'r'); if (!$fp) return false; $s = fread($fp,9999999); fclose ($fp); return $s; }` $arr should contain: $arr['name'] The original name of the file on the client machine. $arr[type'] The mime type of the file, if the browser provided this information. An example would be "image/gif". $arr['size'] The size, in bytes, of the uploaded file. $arr['tmp_name'] The name of the uploaded file. See http://php.net/manual/en/features.file-upload.php Syntax `$lens = PHPLensConnect(...); $lens->imageUploadFunction = 'uploadimg'; $lens->Render();` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

includeFooter

Templates
includeFooter
Include and run a PHP file after the phpLens html is rendered This must be set before the Render() function is called. Syntax `$lens->includeFooter = '/htdocs/footer.php';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

includeHeader

Templates
includeHeader
Include and run a PHP file before the phpLens html is rendered This must be set before the Render() function is called. Syntax `$lens->includeHeader = '/htdocs/header.php';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

inputLens

Editing, Updating and Creating Records
inputLens
Allows you to add html/css attributes to input fields Allows you to add specific attributes to input/textarea/select fields. For example, if you want to add an onclick handler the input field for the column "unitsinstock", $lens->inputLens = 'unitsinstock^onclick="alert(\'this is a test\')"'; So the input field generated would look like this: <INPUT name=LENS_FI_UNITSINSTOCK onclick="alert('this is a test')" value="33" > CSS If you want to use CSS for input field "fruittype": $lens->inputLens = 'fruittype^id=colorInput'; So the input field generated looks like this: <INPUT name=LENS_FI_FRUITTYPE id=colorInput value="CITRUS" > Using * You can define a global inputLens using * that is applied to all input tags: $lens->inputLens = '*^class=input-type'; You can also define an inputLens for a specific field, and then use the global inputLens for all other tags. The fruittype field will not use the global inputLens, but use class=fruit-css instead. $lens->inputLens = '*^class=input-css;fruittype^class=fruit-css'; Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.4.2]

inputTypeLens

Editing, Updating and Creating Records
inputTypeLens
When editing, display checkbox, radio or submit buttons for selected fields You can display a field as a set of lists items (popups and multiple select), check boxes, radio buttons or submit buttons using this property. The mustFill property is ignored if this property is set. Legal values for input types are: select, multiple, checkbox, radio, submit, combo, readonly. popup Display as a drop down list (popup) multiple Display as a multiple select list. checkbox There are 2 types of checkboxes: First are numeric/boolean checkboxes where you can toggle the checkbox on or off. Second are multiple selection checkboxes. This works in conjunction with lookupLens which provide the lookup options, and the displaySep property which controls how each selection is used. See an example below. Checkbox options are saved as comma separated items in the field. To use some other separator, modify the displaySep field. radio Radio buttons allow you to select one item only. If you require this to be must fill field, use a popup instead. submit Submit buttons are useful for approval/workflow forms and surveys. Say you have an approval screen with 3 buttons, Approve, Decline and Send Back. We then have the following code: `$lens->lookupLens = 'status=^Approve/Decline/Send Back'; $lens->inputTypeLens = 'status^submit';` Clicking on any of the buttons will save the "Approve", "Decline" or "Send Back" text into the database field status linked to these set of buttons. combo This is a combination of an input text field and a popup where values can be selected. Useful when you have a set of standard values (defined in the popup), but you want to be able to enter strings that do not match the standard values also. readonly The cell value is stored in an input text field that is read-only. This is useful when you have a searchLookupLens that changes multiple fields, but you do not want the user to modify the fields directly. This differs from the readOnlyLens where the value is stored as text, with no input field and no data is posted on form submission. Available since 3.1. Number of Columns for Checkboxes and Radio-buttons Since phpLens 2.7.0, you can determine the number of columns to display for check boxes and radio buttons. In this example, the 3 means use 3 columns. $lens->inputTypeLens = 'Col1^checkbox^3'; Syntax `# To select all the cities i like by clicking on multiple checkboxes # and then save them into the Cities_I_Like column in the format: # "Bukina Faso, London, Verona" $lens->displaySep = ', '; $lens->lookupLens = 'select distinct cityname from citylist'; $lens->inputTypeLens = 'Cities_I_Like^checkbox'; # to select only one city from 'NY,Moscow,Beijing': $lens->lookupLens = 'Cities_I_Like^==NY/Moscow/Beijing'; $lens->inputTypeLens = 'Cities_I_Like^radio'; # to select only one US state, and you want the user to save time # by not having to click on the default Save button (which is hidden). # We show the state names, but save as state codes ( a mapping): $lens->lookupLens = 'State^=AR/Arkansas/CA/California/NY/New York'; $lens->inputTypeLens = 'State^submit';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.2]

keyCol

Editing, Updating and Creating Records
keyCol
Primary key of keyTable For some databases such as MySQL and through ODBC, phpLens can guess the key if you are using an autonumbering field. Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

keyColClear

Information and Debugging
keyColClear
Clears the keyVariable if it not visible on page Default: `true` The keyVariable is used to store the primary key of the currently selected record. If you dynamically change the sql, you normally want to clear the keyVariable when the selected record is not visible. This is the default behaviour. If you want the keyVariable to be sticky, so that the record remains selected even if it is not visible, set this to false. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.2]

keyColVariable

Programming
keyColVariable
Mirror the primary key column value in a global variable This has been rendered obsolete by the keyVariable property. This is useful when you want need to access the primary key of the currently selected record. The variable defined in keyColVariable is automatically set to the primary key value as soon as it becomes available. Note that if a new record is inserted into a table, we are unable to set the keyColVariable correctly. Syntax `$lens->keyColVariable = 'ID'; $lens->Render(); print $ID; # now the global var $ID is set to the primary key value` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

keyCompound

Essential
keyCompound
Compound primary key fields Define compound primary key here as a ; delimited list of fields. If this is defined, then the keyCol property is ignored (phpLens will set keyCol to '*'). Note: the key (lens_p1) generated in phpLens url's for compound keys uses a special formula to combine all the fields into one value. See source code of LensPackKeys($keyarray) in phplens-common.inc.php. Syntax `$lens->keyCompound = 'Field1;Field2;Field3'; $lens->keyCompound = 'Table1.Field1;Table1.Field2';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 2.7]

keyIsChar

Editing, Updating and Creating Records
keyIsChar
Force primary key to be treated as a char if true, otherwise autodetect Default: `false` Sometimes the type autodetection of the key column fails, and a numeric key is actually a string. To force the key to be quoted, set this to true. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

keyRecNo

Programming
keyRecNo
Add primary key to RecNo link Default: `1` Useful to detect which record the user clicked on. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

keyRecNoSelect

Table Rows and Columns
keyRecNoSelect
Selected record is based on primary key and not relative position in grid Default: `0` 0 = Show record based on relative record number in details. If no record found, show first row. 1 = Show record based on selected primary key in details, if no record found then hide details. 2 = Show only record based on selected primary key in details, if no record found then show first row in details. Previously we highlight records based on record number. This caused problems when we want to show the same record in the details all the time because as records get added/deleted, the record number would point to a different record. When keyRecNoSelect is set to 1, the same record is always selected as record selection is by primary key and not relative position in the recordset. When set to 0 (the default), the record selected is based on the relative position from the beginning of the recordset. So if records are added to the beginning of the recordset (or deleted), a different record could be selected. T On the first time a phpLens object is displayed, no record will be selected if keyRecNoSelect = 1, while if set to keyRecNoSelect=2, the first record will be auto-selected. GET parameters The required URL variables in your GET parameters becomes: lens_no_mysql=0&p=$key where the $recno is the record number you want to go to (it is ignored), and $key is the urlencoded primary key to select and display in the details. Syntax `$lens->keyRecNoSelect = 1; // select by primary key` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8.1]

keyTable

Editing, Updating and Creating Records
keyTable
The name of the table you are editing and creating records on Normally, phpLens can guess the name of the table for you unless you are using stored procedures. You can define a dynamic key table by prefixing this property with '=' or '%'. See example below. Available in phplens 1.2. Syntax `$lens->keyTable = 'atable'; # the following allows you to have multiple tables # holding postcodes for different countries, eg. # MALAYSIA_POSTCODES, USA_POSTCODES, etc. # and reuse the same phpLens object for different tables. $lens->keyTable = '={$COUNTRY}_POSTCODES';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

keyVariable

Editing, Updating and Creating Records
keyVariable
Edit a record based on a global variable One way of forcing phpLens to view/edit a specific record is by setting a global variable in this way: `$lens->sql = "=select * from table where id=\$ID"; $lens->keyCol = 'table_id';` However this is a problem when we want to create a new record, and continue showing this record after it is created. Initially, $ID will be empty, and we need a mechanism to update $ID after the record is created. The keyVariable property solves this problem, because phpLens will auto-update $ID after the record is created. `$lens->sql = "select * from table"; $lens->keyVariable = "ID";` In the above example, $ID must be a global session variable. Now when creating a new record, $ID is updated with the created record's serial id, if the database supports serial id's (mssql, mysql). If the database does not support serial id's, then we provide a second parameter to keyVariable where you can define some sql to execute to obtain the primary key of the newly inserted record. In the following example, we store the serial id in an oracle sequence: `$lens->keyVariable = "ID/select sequence1 from dual";` In the above example, you will still need to define an oracle trigger which sets 'table_id' to sequence1.nextval. Also note the seperator used is the option seperator (/) and not the field seperator (^). Note that if $ID is already defined, then instead of showing the New Record form, we will be viewing or editing the record specified by $ID. Limitations: Only works with numeric/integer primary keys currently. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.1]

lang

Programming
lang
Holds the current language definitions This is an instance of a php class. It is created by instantiating the class defined in phplens-lang-*.inc.php, where * represents the language, which can be: en_us (US English) en_uk (UK English) fr (French) bm (Bahasa Malaysia/Indonesia) Other languages might be supported in the future. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

layoutTableHeader

Table and Grid formating
layoutTableHeader
Attributes of (invisible) bounding table surrounding phpLens Default: `'align=center border=0 cellspacing=0 cellpadding=1'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

lensVers

Information and Debugging
lensVers
Version number of phpLens Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

lookupLens

Table Cell formating
lookupLens
A lens to lookup descriptions of codes and create popups for <select> options There are 2 types of lookup values. The first is looking up the description of a code. For example mapping the country code ca to Canada, and uk for United Kingdom. The second is when you are editing a record and you want the user to be able to lookup all legal values for that field in a popup menu. 1. Lookup a Code Sometimes you are using an abbreviation or a code in a column. You want to translate the abbreviation to something more natural. Use the Lookup Value feature to do so. You can lookup a value by using a SQL select statement where the first column selected matches the code/abbreviation, and the second column matches the translated value to display. See example below. SELECT col_id,col_to_display FROM table To lookup the country names from a list of country codes, you could use: SELECT Code, CountryName FROM CountryTable Alternately you can text mappings. Make the first character equals (=), and follow it with your mappings. In the example below, we want to set "1" to lookup "one", "2" to lookup "two", etc. =1/one/2/two/3/three/4/four 2. Lookup Popup Values When editing or creating a record, you can give the user a list of legal values to select from by entering SQL of the form SELECT DISTINCT colname FROM table If you do not want to use SQL and want to perform text lookups, make use double equals(==) and follow it with your mappings. In the example below, we want legal values to be Yes or No: ==Yes/No The double equals is available in phpLens 1.1 onwards. Using variables in your SQL In phpLens 1.2 onwards, you can access PHP global variables in your SQL statement provided you prefix the statement with a '%'. See examples in the syntax section. Hot Update of Lookups You might have a popup that is tied to the value of another field. For example, if you have a popup field taken from a SQL column called "states" that displays the US states, and a second popup field with data taken from SQL column "cities" that displays the cities in that state. When you change the state, the cities popup will change also. You can perform a hot update of the cities popup like this: `$lens->lookupLens="states^select name from states;"; $lens->lookupLens .= "cities^#select name from cities where state={states}"; $lens->phplensDatabase = 'oracledb'; // database defined in phplens.config.inc.php` Place a # as the first character of the select statement of the field that requires a hot update, and incorporate the controlling field (states here) as part of the sql statement as a {variable}. This hot update uses javascript to make a request to phplens/phplens_remoteq.php. You might need to configure the above file so that the correct database connection settings are set. The remoteQuery and phplensDatabase properties might need to be configured also. The phplensDatabase property is the name of the $PHPLENS_DATABASE entry (from config/phplens.config.inc.php) being used to connect to the database. Alternatively, you can modify the phplens_remoteq.php script yourself. The remoteQuery property is the full http path to the phplens_remoteq.php file - you only need to set this property if you move this file out of the phplens directory. The SQL used in the hot update is stored in the html generated by phpLens. As an extra security step, the SQL string is fingerprinted using MD5 with a salt. The salt can be configured using the constant PHPLENS_MD5_SALT in phplens.inc.php. The file phplens_remoteq.php detects if the SQL has been tampered with using the MD5 fingerprint and refuses to execute the SQL in this case. This works in both Edit and Filter mode. Since phpLens 1.3.15. Evaluating PHP Code in Normal Lookup New to phpLens 1.9 is the ability to execute PHP code. =% means evaluate PHP code, the PHP code must return values in a string of the form "1/one/2/two". Eg. $lens->lookupLens="col1^=%ReturnString()"; ==% means evaluate PHP code, the PHP code must return values in a string of the form "1/2/3/4". Evaluating PHP Code in Hot Update Since 3.3, phpLens allows you to execute a function in a Hot Update. All source code must be placed in the APPLETS_DIR.'/remoteq' directory, typically found in phplens/builder/applets/remoteq. Remoteq stands for remote query. For example, you have a field emp_name that hot updates based on changes in the company_id field. The hot update calls a PHP function called 'test', stored in the file 'remoteq/test.inc.php'. Then you define in the lookup: $lens->lookupLens = 'emp_name^#MetaPHP test.inc.php test({company_id})'; The first character, #, indicates that it is a hot update. The parameter MetaPHP indicates that is is PHP code, and not SQL. The following parameter 'test.inc.php' is the name of the file located in the remoteq directory. Lastly, the function (defined in test.inc.php) and the parameters follow. The {company_id} means that company_id is passed as the function's first parameter, and is called every time the company_id changes. The function must return an array, or false on failure. If string keys are defined, then they are the option values, while the values become the option text. One global variable is available to the function, $DB, which is the default database connection. For example: `function test($co_id) { global $DB; $co_id = (integer) $co_id; // sanitize param for security $rs = $DB->Execute("select emp_no,emp_name from employees where company=$co_id"); if (!$rs) return false; return $rs->GetAssoc(); # eg. array('23' => 'Jack Szo', '24' => 'Mary Lamb'); }` Note: We use a very simple parser. Each parameter must be separated by a single space. Conditional Lookups There is a 3rd lookupLens parameter which allows you to define in which states (EDIT, VIEW, NEW, FILTER, FILTERVIEW) the lookupLens is evaluated. The following means use 1st SQL lookup when editing, otherwise for all other states, use the second SQL stmt. $lens->lookupLens='col1^select f from table^EDIT^select f2 from table2'; To simplify matters, two additional states were added: "+VIEW" means display this lookup in VIEW, FILTER and FILTERVIEW states. Conversely, we have "-VIEW" which means display this lookup in EDIT or NEW states. $lens->lookupLens='col1^select fld from table^+VIEW^select fld2 from table2'; This means that the 1st select statement is used when VIEWing the data (VIEW/FILTER/FILTERVIEW states), otherwise the 2nd select statement is used. $lens->lookupLens='col1^select f from table^VIEW^select f2 from table2^FILTER^select f3 from table3^FILTERVIEW^select f4 from table4'; In the above example, VIEW, FILTER and FILTERVIEW states have their own select statements. All other lookups use "select fld4 from table4". Note that "-VIEW" and "!VIEW" mean the same. Implementing a Single Checkbox For boolean fields which require a single checkbox, try this (for the field checkcol, with a label 'Yes'): $this->inputTypeLens = 'checkcol^checkbox'; $this->lookupLens = 'checkcol^=1/Yes'; Syntax `$lens->lookupLens='Column^sql statement'; $lens->lookupLens='Column^=1/one/2/two'; $lens->lookupLens='Column^%select value,caption from $table'; $lens->lookupLens="Column^%select value,caption from map where key=\$key";` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

md5Input

Security
md5Input
Enables md5 fingerprinting of data entry fields Default: `true` This is a security feature that ensures that unauthorized users do not add addtional input fields to your form. MD5 fingerprinting is disabled when templates are used, or when this property is set to false. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

menuHide

Navigation Bar and Menu
menuHide
Menu items in navigation bar to hide Default: `''` Legal values are 'DYNEDIT' 'SCROLL' 'NEW' 'FILTER' 'MENUS' 'ALL' 'TOP' 'BOTTOM' or a combination of the above. DYNEDIT = hide dynamic editing "e" icon SCROLL = hide all arrow icons END = hide scroll to end icon. NEW = hide new icon FILTER = hide filter/search icon MENUS = hide menus, but show caption ALL = hide both top and bottom menus and captions TOP = hide top menu and caption BOTTOM = hide bottom menu and caption Syntax `To hide all the DYNEDIT and NEW icons: $lens->menuHide = 'DYNEDIT;NEW';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

mustFill

Editing, Updating and Creating Records
mustFill
Indicates fields that must be filled when editing/creating records In phpLens 1.1 and later, if the field is readonly but mustfill, then when the record is created, you can still enter a value in that field, but not after the record is created. This 1.1 feature allows you to create records where the primary key is entered, but never allowed to change after creation. Syntax `$lens->mustFill = 'col1;col2';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

mustFillMark

Editing, Updating and Creating Records
mustFillMark
Mark appended to the text label indicating that the field must be filled (for new records) Default: `'<font=red>*</font>'` Only appears when creating new records. To disable, set $lens->mustFillMark = ''; Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

nameLens

Table Column/Field Titles
nameLens
Sets the field titles for the grid, detail, edit, new record and search/filter screens Default: `Use the field name` This allows you to place additional instructions specific to a field when editing it, a different one when creating a new record, or to shorten or rephrase a column title. To set a blank title, use {nbsp} to set a non-breaking space. The order of titles is $lens->nameLens ="$colname^$title^$editTitle^$newTitle^$detailTitle^$filterTitle^$gridTitle"; If a title is not defined, then the default $title is used. Note: $filterTitle can only be set since phpLens 2.4.7, and $gridTitle since phpLens 2.5.5. Syntax `$lens->nameLens="col1^grid^edit^new^detail;col2^grid2";` Consider a column called PHONE and we want to tell users that it accepts the format 999-9999: `nameLens="PHONE^Tel^Edit Phone (999-9999)^New Phone (999-9999)^";` If you leave a parameter blank, the column name will be used instead. ``
Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

nameSpace

Programming
nameSpace
Changing this property prevents the same applet on different pages from sharing session variables Default: `'_'` This allows you to run the same applet in different pages with different settings (session variables). The value of the nameSpace is any valid string. This feature only works with PHP 4.2.3 or later. Syntax `$lens->nameSpace = 'This is a nameSpace!';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

navFontPrefix

Navigation Bar and Menu
navFontPrefix
Attributes to prefix to menu item text Default: `'<b><i>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

navFontSuffix

Navigation Bar and Menu
navFontSuffix
Attributes to append to menu item text Default: `'</i></b>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

navHeader

Navigation Bar and Menu
navHeader
Defines the TR attributes for the top and bottom navigation bar Default: `''` Syntax `$lens->navHeader = 'class=NAVCLASS';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.70]

navTableHeader

Navigation Bar and Menu
navTableHeader
Attributes table enclosing navigation bar at top and bottom of grid Default: `'BORDER=1 CELLSPACING=0 BGCOLOR=silver'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

navTDHeader

Navigation Bar and Menu
navTDHeader
Attributes of <td> tag for navigation menu items Default: `''` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

navUserButtons

Navigation Bar and Menu
navUserButtons
Define additional menu items in navigation bar Must include <TD> tags also. Buttons will be added to left of navigation bar. Syntax `To add a menu item "Show" that goes to page show.php: $this->navUserButtons = '<TD bgColor=#C0C0C0><a href=show.php>Show</a></TD>';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

newHiddenTags

Editing, Updating and Creating Records
newHiddenTags
Define hidden input tags to be included in new record form Syntax `$lens->newHiddenTags = '<input type=hidden name=test value=test1>';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

newLens

Editing, Updating and Creating Records
newLens
This lens sets which fields are shown when creating a new record By default, the displayed fields are editable unless the newReadOnlyLens or readonlyLens properties are used. Use defaultLens for fields that have hard-coded default values. Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

newReadOnlyLens

Editing, Updating and Creating Records
newReadOnlyLens
This lens sets which fields cannot be modified on creation, but are editable. Use this for fields which have a hard-coded default value, but are editable subsequently. See also readOnlyLens. Note that readonly means that the user cannot change the value, but you can still set the value to insert into the database using the defaultLens property. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

newTableHeader

Table and Grid formating
newTableHeader
Attributes of <table> tag used in creating new record Default: `'BORDER=1 cellspacing=0 cellpadding=2'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

nl2br

Editing, Updating and Creating Records
nl2br
Convert newlines to <BR> tags in a field after on saving a record Default: `true` If nl2br is true and htmlLens is set to true for a field, when you save then <BR> tags are added automatically for the field. If nl2br is set to true, then all text areas will have their <BR> tags stripped automatically, whether or not htmlLens is set for that field. One limitation is that <BR>'s can be generated in places where it is illegal, such as within <SCRIPT> and <TABLE> tags. Since these are normally banned tags, this is not an issue. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

noAutoNew
Warning: flock(): 804 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Editing, Updating and Creating Records
noAutoNew
Set to true to disable switching to NEW record state when no records are found Default: `false` Syntax `$lens->autoNew = true;` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.1]

noTrim

Table Cell formating
noTrim
Do not trim column data Default: `false` Normally phpLens will trim all field data and this is harmless. However if you are combining multiple data columns together to form one big text string (maybe there are limits to a varchar field for your database), you might not want any trimming to occur. Syntax `$lens->noTrim = true;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.7]

numberPrefix

Table Cell formating
numberPrefix
HTML tags to prefix to numbers Default: `'<div align=right>'` The default is to align right. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

numberSuffix

Table Cell formating
numberSuffix
HTML tags to append to numbers Default: `'<div>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

numInputLen

Editing, Updating and Creating Records
numInputLen
Specify the width of <input type=text> tag for numbers Default: `14` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

oddHeader

Table Rows and Columns
oddHeader
Attributes of <TR> tag of odd rows of grid Default: `'valign=top'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

onlyOrder1Col

Programming
onlyOrder1Col
Do not allow an ORDER BY on the same column Default: `false (except for mssql)` Some databases do not allow ORDER BY's with the following syntax: SELECT * FROM TABLE ORDER BY 1,1 PhpLens automatically does a sort when you click on a column title by modifying SQL ORDER BY's. This hint will help prevent SQL errors from occuring. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

overlibInit

Table Cell formating
overlibInit
Set this to false to disable generation of overlib div tag and javascript include Overlib requires some initialization. If this variable is not set to false, then phpLens will generate this: <div id="overDiv" style="position:absolute; visibility:hidden; z-index:1000;"></div> <script type="text/javascript" language="JavaScript" src="'.$imgpath.'/img/overlib.js"></script> when overlibLens is set. This is mostly useful when you already have an existing overlib setup and you do not want to use the phpLens overlib setup. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.0]

overlibLens

Table Cell formating
overlibLens
Uses the overlib library to create a javascript popup in the grid for specific columns To configure a javascript popup for the SHORT_NAME field that displays the DETAILS and MORE_DETAILS fields, you should do this: $this->overlibLens = 'SHORT_NAME^Details:<br>{DETAILS} {MORE_DETAILS}'; You can use PHP code using: $this->overlibLens = 'SHORT_NAME^=strtoupper({DETAILS})'; You can also define additional overlib parameters (see overlib docs) like this: $this->overlibLens = 'COL1^{COL2}^WIDTH,300,HEIGHT,200'; The overlib parameters are documented here: http://www.bosrup.com/web/overlib/reference.html Syntax `$lens->overlibLens = "$fieldname^{FIELD2} {FIELD3}^$overlib_parameters"; $lens->overlibLens .= ";$fieldname2^Some Text";` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.0]

overrideFunction

Programming
overrideFunction
Name of function used to modify globally phpLens settings Default: `false` Sometimes you want to implement a function that modifies phpLens settings before the $lens object is rendered. This is typically for global settings on security, table colors, etc. But Generate PHP Code will always overwrite this global security function. This property makes the global function part of the Generate PHP Code process, simplifying your code. The function is called after the phpLens dynamic editor settings are retrieved, so it will override any settings configured using the dynamic editor. Syntax `$lens->overrideFunction = 'SetSecurity'; An Example // remember $lens is by reference! function SetSecurity(&$lens) { $global $isAdmin; if ($isAdmin) { $lens->dynEdit = 1; $lens->menuHide = ''; } else { $lens->dynEdit = 0; $lens->menuHide = 'ALL'; } } $lens = new phpLens($db,'select * from table'); $lens->overrideFunction = 'SetSecurity'; // Now the next line is autogenerated by Generate PHP Code SetSecurity($lens); $lens->Render(); $lens->Close();` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

pageBreakHTML

Table and Grid formating
pageBreakHTML
HTML used to indicate page break when pageBreakRows>0 Default: `<p id=lvPageBreak></p><!--NewPage-->\n` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3.2]

pageBreakRows

Grouping and totaling of rows
pageBreakRows
Number of rows before issuing a CSS page break for printing Default: `0` The default of 0 means do not issue a page break. The CSS page break when printing works on IE 5 or later. Testing with Mozilla 1.4 indicates there is a bug in Mozilla 1.4 that prevents it from supporting this page break. The page break code also supports widow control when groupLens is enabled. This means that if a new group is to be started at the end of the page, we will move the group to the next page. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3.2]

pageSize

Table Rows and Columns
pageSize
Number of rows per page Default: `10` If you don't want to scroll, set the pageSize to an impossibly high number such as 99999. Syntax `$lens->pageSize = Integer;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

password

Security
password
Password protect dynamic editing Default: `''` Before any dynamic editing can occur, the user will be prompted to enter this password if it is set. The default is not to prompt the user for a password. Syntax `$lens->password = 'secret';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

persist

Programming
persist
For internal connections, use persistent connections if true Default: `false` When phpLens connects internally to the database where the phpLens table resides, it will use this setting to determine whether to connect using persistent or non-persistent connections. Also when you generate PHP source code or use the applets technology, this setting determines whether the code uses persistent connections or not. Syntax `$lens->persist = true; // or false` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0.6]

phplensDatabase

Filtering and Searching
phplensDatabase
Name of the index to $PHPLENS_DATABASES Allows you to define which database in $PHPLENS_DATABASES you are using. This is useful for hot updates of lookupLens. $PHPLENS_DATABASES is defined in phplens/config/phplens.inc.php. For example, if the first element in $PHPLENS_DATABASE is selected: $PHPLENS_DATABASES = array( //driver, server, userid, pwd, database 'mysqldb'=>array('mysql','localhost', 'root','','phplens') ); Then $lens->phplensDatabase = 'mysqldb'; Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3.15]

powerEditLens
Warning: flock(): 1779 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Editing, Updating and Creating Records
powerEditLens
Allows you to modify default input values when editing records This is similar to powerLens, but for input fields when editing or creating new records. See also defaultLens to modify default input values when creating records. Read Only Fields When you use powerEditLens with readonly fields, the fields would be updated when the user clicks on the save button. For example this field RO: $lens->powerEditLens = 'RO^=strtoupper({RO})'; $lens->readOnlyLens = 'RO'; would be readonly on the screen, but when you save, the upper-cased data would be updated in the database. To prevent this from happening, in 2.7.0 and later, we add a new modifier, !! (double-exclamation mark): $lens->powerEditLens = 'RO^!!=strtoupper({RO})'; $lens->readOnlyLens = 'RO'; Then the field RO will not be updated in the database when the user clicks on Save. Syntax `#uppercase text of field col1 $lens->powerEditLens = 'col1^=strtoupper({col1})';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.2]

powerLens

Table Cell formating
powerLens
Dynamicly change contents of cell You can reformat a field's data before displaying it in a HTML grid cell using 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}, {firstname}` 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}) . ", " .{firstname} . ""` You can access also global variables using the $GLOBALS[] array, or call PHP functions. Empty Fields and NBSP Sometimes you want to check if a field is empty/null. You cannot check by using `if empty({column})` because all empty columns are set to & nbsp; for display purposes. Nor can you compare `if ({column} == '& nbsp;')` because semi-colon `;` is used to separate column settings. NOTE: Since phpLens 2.6.5, we allow you to disable conversion of empty strings to & nbsp;. You do this by prefixing a % or =% to your powerLens. Here are two examples: %<a href=someurl.com/?param={param}>{value}</a> =%'<a href=someurl.com/?param='.urlencode({param}).'>'.{value}.'</a>'; Before 2.6.5, you had to use this technique: We also have defined a variable {NBSP} to represent & nbsp; . So you can check if a field is empty using `if ({column} == {NBSP})`. Similarly for formatting, when you want to add additional spaces between words: `Name: {NBSP} {Name}` Lastly if you need to display an ISO entity, for example the bullet symbol (•) • you can use the {SEMICOLON} variable: "•{SEMICOLON}"; If the field you are accessing is numeric, we automatically format the number with the thousand's separator. So if you have a column called {kg} and you want the raw unformated data, the raw data is available in the $_flds array. Note that the _flds array might be indexed by number, not by field name (depends on the database). More Examples
| Description | PowerLens Code
1 | Show column {c} as bold | `{c}`
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] | `[{book} {chapter} : {verse}]`
4 | Create a hyperlink | `{linktext}`
Global Variables The $GLOBALS[] array is accessible from a powerLens. For example, to access $PHP_SELF, use {$PHP_SELF}. Record Numbers This is new to phpLens 1.2. Each row is assigned a record number and this can be obtained using the special {_RECNO_} variable. Useful for switching detail grids dynamically. The currently selected row number is stored in {_HILITE_RECNO_}. Complete List of Macro Variables {NBSP} = ' ' {SEMICOLON} = ';' {_RECNO_} = record number powerLens is acting on {_HILITE_RECNO_} = currently selected record number {_LENSID_} = the phpLens object's id {_ODDC_} = the odd row color {_EVENC_} = the even row color {_SELECTC_} = the hilite color for the selected record {_HASDETAILS_} = whether the detail grid is visible See Also See also colorLens. Also see the inputTypeLens property to change the input type to checkbox, radio or submit buttons. Syntax `# modify the firstname column to show both surname and firstname $lens->powerLens = "FIRSTNAME^{surname}, {firstname}"; # modifies firstname to show the surname in uppercase $lens->powerLens = "FIRSTNAME^=strtoupper({surname})", ".{firstname}."";` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

powerPrefix

Table Cell formating
powerPrefix
Prefix powerLens code with the following PHP code Default: `"global \$PHP_SELF,\$PHPLENS_PATH,\$GLOBALS;\n"` If your powerLens code is accessing a special array (eg. $HTTP_COOKIE_VARS), add this array to the global declaration above. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

readOnlyLens

Editing, Updating and Creating Records
readOnlyLens
This lens sets fields which are readonly in both edit and new record mode See also newReadOnlyLens and gridReadOnlyLens. Setting this property for a field means that the user cannot change the field value. However when creating a new record, you can still set the value to insert into the database using the defaultLens property. Also if you have the mustFill property, then when creating the record the field will be editable. If you require an input field that is read-only that is manipulated using javascript, see the inputTypeLens property, readonly type. Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

redirectNoData

Error Handling, Redirects
redirectNoData
when no data returned from SQL query, redirect to another page Set to a URL to page to redirect to. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

redirectOnInsert

Error Handling, Redirects
redirectOnInsert
After successful insert new record, redirect to another page We now add a GET parameter so you can access the primary key of the inserted record (since phpLens 2.4.1): $lens->redirectOnInsert = 'http://server.com/page.php'; will generate the redirect following for the primary key '1234'. 'http://server.com/page.php?lens_p1=1234' PhpLens will detect whether you have existing GET parameters in your URL, and use ? or & as appropriate. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

redirectOnInsertCancel

Error Handling, Redirects
redirectOnInsertCancel
Redirect if user cancels new record Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

redirectOnUpdate

Error Handling, Redirects
redirectOnUpdate
After a successful update, redirect to another page Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

redirectOnUpdateCancel

Error Handling, Redirects
redirectOnUpdateCancel
Redirect if user cancels editing Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

remoteQuery

Filtering and Searching
remoteQuery
Full http path to the phplens_remoteq.php file This php file is used in hot updates of lookupLens to query the database. Syntax `$lens->remoteQuery = '/php/phplens/phplens_remoteq.php';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

renderer

Programming
renderer
Custom PHP class for drawing in grid view. This allows users to radically change the look and feel of a phpLens object. Currently a prototype Web calendar which displays recordsets sorted by date has been developed using the renderer. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

roInputStyle

Editing, Updating and Creating Records
roInputStyle
Read-only input field CSS style Default: `"background-color: #C0C0C0"` The CSS style of a read-only input field. Syntax `# You must include the double-quotes $lens->roInputStyle = '"background-color: beige"';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.1]

rowColorLens

Table and Grid formating
rowColorLens
Set the color of rows in the grid dynamically If the first character is = then the rest of the line is evaluated as PHP code. The default rowColorLens can be seen in the syntax example below: The following example highlights the selected row, and all those below the selected row: `$lens->rowColorLens = '={_RECNO_}>={_HILITE_RECNO_} ? "#FFCCCC" : "" ';` where {_RECNO_} is the current row, and {_HILITE_RECNO_} is the selected or highlighted record number. This is not particularly useful. The following is the actual rowColorLens used by phpLens: `$lens->rowColorLens= '=LensRowColor("#FF8080",{_LENSID_},{_RECNO_},'. '{_RECNO_}=={_HILITE_RECNO_},{_SELECTC_},{_ODDC_},{_EVENC_},{_HASDETAILS_})';` To change the default select color from pink, change the #FF8080 above. You can also use column names. For example, to highlight all negative prices in pink: `$lens->rowColorLens = '={PRICE}<0? "#FFCCCC" : "" ';` If you do not prefix this property with equals, the string will be treated as HTML and not PHP code as in the powerLens property. Variable List {_LENSID_} The $lens->id {_RECNO_} The current record number {_HILITE_RECNO_} The record number that is currently selected {_SELECTC_} The select color for selected record, eg #800000 for red {_ODDC_} The odd line color (from $lang->oddColor) {_EVENC_}The evenline color (from $lang->evenColor) {_HASDETAILS_} 1 if $lens->showDetails is true, 0 if false Syntax `# The source code for LensRowsColor() is in phplens.inc.php $lens->rowColorLens= '=LensRowColor("#FF8080",{_LENSID_},{_RECNO_},'. '{_RECNO_}=={_HILITE_RECNO_},{_SELECTC_},{_ODDC_},{_EVENC_},{_HASDETAILS_})';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

rs

Programming
rs
Holds the adodb recordset This is automatically set internally by phpLens. See also the connection property. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

sameRowLens

Table Cell formating
sameRowLens
Controls whether to show 1 or 2 fields per row in new, edit & detail grids. Assume we display 4 fields, F1, F2, F3, F4 in that order. Then assume the following settings: $lens->sameRowLens = 'F1^EDIT^VIEW^NEW;F3^EDIT'; The example above sets F1 to display the next field (F2) in the same row in the edit, new record and details grid (VIEW), while F3 and F4 are in the same row only when editing. Visually in the detail grid and new record form: F1 F2 F3 F4 In edit record form we will see: F1 F2 F3 F4 Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 3.2]

saveOptions

Editing, Updating and Creating Records
saveOptions
Additional save options when editing or creating records NEW $lens->saveOptions = "NEW", a new icon is displayed when editing, allowing you to create new records from the edit form. DELETE $lens->saveOptions = "DELETE", a delete icon is displayed when editing, allowing to delete the current record. HIDETOPBTNS $lens->saveOptions = "HIDETOPBTNS", will hide the Save and Cancel buttons that appear at the top of the form. SAMEROW1COLOR $lens->saveOptions="SAMEROW1COLOR", and if the sameRowLens property is used to force two fields in the edit/new form to share the same row, then the title caption background of the 2nd field are also colored with the detailColor. This makes the color scheme simpler. OCISEQUENCE $lens->saveOptions = "OCISEQUENCE^seqname" allows you to name the oracle sequence you are using within a trigger to set the integer serial id column of the table. The following feature is experimental, and not supported: $lens->saveOptions = "COLLECTIONS" will cause all checkbox/multi-select fields to be mirrored in another table. For example, if $lens->keyTable = 'master', then the mirroring table will be called "master_collection", and the fields of the table will be all fields that allow multiple values to be entered, plus the column containing the primary key. From 3.3.2 onwards, you can define the table to save in, eg. $lens->saveOptions = "COLLECTIONS^NameOfTable" Syntax `#All saveOptions can be combined, eg. $lens->saveOptions = 'NEW;DELETE;OCISEQUENCE^seqgeneral';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 3.1]

scrollBgColor

Navigation Bar and Menu
scrollBgColor
The background color in the navigation bar for scroll links Default: `#EEEECC` If scrollLinks set then the default color is #EEEECC (light yellow shade) or if no scrollLinks are defined, then we set it to $lens->colorNav. If you define this color, then it is applied whether or not scrollLinks is defined. Syntax `$lens->scrollBgColor = '#CCCCCC';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

scrollFontPrefix

Navigation Bar and Menu
scrollFontPrefix
Formatting to apply before an unselected link in the navigation bar Default: `'' (no formatting)` See also scrollHiliteFontPrefix. Syntax `$lens->scrollFontPrefix = '<font size=1>'; $lens->scrollFontSuffix = '</font>';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

scrollFontSuffix

Navigation Bar and Menu
scrollFontSuffix
Formatting tags to apply to end of scroll link in navigation bar See scrollFontPrefix. Syntax `$lens->scrollFontPrefix = '<font size=1>'; $lens->scrollFontSuffix = '</font>';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

scrollHiliteFontPrefix

Navigation Bar and Menu
scrollHiliteFontPrefix
The formatting of the current page link selected in the navigation bar Default: `<b>` Syntax `$lens->scrollHiliteFontPrefix = '<div class=hilite>'; $lens->scrollHiliteFontSuffix = '</div>';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

scrollHiliteFontSuffix

Navigation Bar and Menu
scrollHiliteFontSuffix
The formatting of the current page link selected in the navigation bar Default: `</b>` Syntax `$lens->scrollHiliteFontPrefix = '<div class=hilite>'; $lens->scrollHiliteFontSuffix = '</div>';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

scrollLinks

Navigation Bar and Menu
scrollLinks
Display a set of scrolling page links in the navigation bar Default: `0` Set this to a positive number to indicate the number of page links to display. As the current selected page will be centered in the display, it is best to use an odd number. For example: $lens->scrollLinks = 3; Will display 3 links in the navigation bar (and assuming that we are at page 5):
    |<  <   4    5    6    >   >|
To set the scroll background color, see scrollBgColor. Tip When scrolling to the end of the grid is slow, consider setting scrollLinks > 0. This is because setting scrollLinks will force phpLens to perform a count of the recordset, so it has a better idea of what record to scroll to reach the end of the grid. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 2.8]

scrollMaxRecordCount

Grouping and totaling of rows
scrollMaxRecordCount
Read-only property that holds number of records in all pages This is only set when scrollLinks > 0, and is generated before templates are rendered, so it is accessible from a Smarty template using {php} tags. {php} global $lens; echo $lens->scrollMaxRecordCount; {/php} This property is read-only and should not be modified. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3]

scrollTDHeader

Navigation Bar and Menu
scrollTDHeader
Defines the TD attributes for the scroll link cells Useful for defining CSS styles. Syntax `$lens->scrollTDHeader = 'class=scroll';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

searchLookupLens

Editing, Updating and Creating Records
searchLookupLens
Dynamically search for record and store results in fields when editing or new record Suppose you have an customer complaint form (accessing the COMPLAINT table) where you need to search for a customer name, and store the customer id and address in the fields from the CUSTOMER table. However you don't want to use a normal lookupLens because your CUSTOMER table has over 100,000 records. So you want the user to enter a search string first to narrow down the list of records to return from the server, and then click on a search button. As shown below: [ Enter Customer Name ] [SearchBtn] After clicking on the search button, a list of records will be displayed, and the user can select one of the records. This will copy the selected CUSTOMER.NAME to the COMPLAINT.NAME field, and copy the search results from CUSTOMER.NAME to COMPLAINT.NAME, CUSTOMER.ID to COMPLAINT.CUSTID and CUSTOMER.ADDRESS to COMPLAINT.ADDRESS. To add a Search button to the name field, use the following. The {#} is replaced with the text the user enters: $lens->searchLookupLens = "name^select name from customer where name like '{#}%' "; To allow searching only in the New record form and not the Edit record form, place after the SQL statement this option !NEW : $lens->searchLookupLens = "name^select name from customer where name like '{#}%' ^!NEW"; Suppose you don't want to populate the New record form when you find a match, but switch to editing the selected record, set the 2nd field of the select statement to the primary key of the record to be edited (custid in this example), and place after the SQL statement this optiion !NEWEDIT : $lens->searchLookupLens = "name^select name,custid from customer where name like '{#}%' ^!NEWEDIT"; To copy the CUSTOMER fields (name,id,address) to the COMPLAINT fields (name,custid,address), use: $lens->searchLookupLens = "name^select name,name,id,address from customer where name like '{#}%' ^name^custid^address"; The column name is repeated twice in the SQL statement because the first mention of name is the text to display, and the second is the field to copy from. Now you might require the user enter at least 3 characters in the search field before you allow them to click on the Search button. To do so add a '>3' to the property: $lens->searchLookupLens = "name^select name,name,id,address from customer where name like '{#}%' ^name^custid^address^>3"; Advanced Lookups The above examples assume that you are modifying the name directly. But suppose we store cust_id, a foreign key to the CUSTOMER table in COMPLAINT.cust_id and not the name. We don't want the user to search for the cust_id, which is an integer and internal to the database. We want to search by name instead. First we need a mapping between the CUSTOMER and COMPLAINT tables. This is done using the normal lookupLens. We don't want to pull the whole CUSTOMER table over (to PHP) to do a join, so we use a hot update that only works in NEW and EDIT mode. $lens->lookupLens = 'cust_id^#select cust_id,name from customer where cust_id = {cust_id}^-VIEW'; Then have a searchLookupLens for the cust_id field, such as the following: $lens->searchLookupLens = "cust_id^select name||'-'||address,name,cust_id from customer where name like '{#}%' "; There must be 3 columns in the select statement, first the column to show to the end-user to select from a popup (in this example, the name followed by the address), second the value to display in the text field after selection, and third the actual value to store in the COMPLAINTS table, cust_id. It will create special input tags like this: [ Enter name here ... ] [cust_id] [Search Btn] The [cust_id] field can be set by selecting an item from the results of the search. Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 3.1]

sectionLens

Editing, Updating and Creating Records
sectionLens
Creates section breaks for edit/new record forms To create section breaks above the NAME and CREATED fields, titled "User Info" and "Audit", with green backgrounds, and the CREATED field uses the redfont CSS class. The !EDIT!NEW below indicates that the section breaks are for EDIT and NEW states. `$lens->sectionLens = 'NAME^!EDIT!NEW^User Info^green;" . "CREATED^!EDIT!NEW^Audit^green^redfont";` The order of the settings are: "FIELDNAME^STATES^Title^BackgroundColor^cssStyle"; Note that the default CSS style is "lvbw", which stands for "lens value bold white". Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.2]

securityCheckReferer

Security
securityCheckReferer
Check referer on save record is same as host server Default: `true` As an additional security check, we make sure that the New/Edit record page came from the current server. This might cause problems when using a load-balancing server farm, so you can disable it here. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

securityEditSeq

Security
securityEditSeq
keep track of order of updates by storing a seq no for every New/Edit Default: `true` This is useful because when phpLens is asked to update or create a record, phpLens will check whether the user is authorised to edit those columns. This prevents hackers from modifying private fields. This feature cannot be modified in the Professional version, and is always enabled. Only Enterprise users can disable this feature. This feature currently does not work if templates are used. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

showCal
Warning: flock(): 804 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Editing, Updating and Creating Records
showCal
Show popup calendar when editing entries Default: `false` We are using a shareware popup calendar by Liming Weng called PopCalendarXP. Please only enable this for evaluation purposes, or if you have purchased this software from Robin. See http://www.hotscripts.com/Detailed/10619.html If you prefer your own calendar, we provide the ability to define the javascript function to call when the calendar icon is clicked. Instead of setting $lens->showCal = true or false, set $lens->showCal to the name of the javascript function. See below for an example. This is since 2.2.6. Syntax `$lens->showCal = true; # Alternatively define your own js calendar function # the example below is not a full calendar and is # to help you understand the API. $lens->showCal = 'MyCalendar'; <script> // zdoc is the document object // ctrlname is the name of the control, starting with zdoc // range normally range is set to null // is an array in this format // [RangeBeginDate, RangeEndDate {,disabledDate}] function MyCalendar(zdoc,ctrlname,range) { var od,om,oy,d od = eval(ctrlname+'_d'); om = eval(ctrlname+'_m'); oy = eval(ctrlname+'_y'); alert(od.value + '/'+om.value+'/'+oy.value); // now we have 3 text objects which hold y/m/d //now call your calendar and set the values... /* // call calendar function and return date! d = ShowCalendar(); od.value = d.getDate(); om.value = d.getMonth()+1; oy.value = d.getFullYear(); */ } </script>` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

showCancel

Editing, Updating and Creating Records
showCancel
Show cancel button when editing Default: `true` Use this to prevent users from canceling. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

showDetails

Table and Grid formating
showDetails
Show detail grid for current row Default: `true (if data has more than 5 columns)` Syntax `Boolean` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

showFindMore
Warning: flock(): 804 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Filtering and Searching
showFindMore
Show Find More checkbox in search form if true Default: `false` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

showGrid

Table and Grid formating
showGrid
Show main grid Default: `true` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

showHeaders

Table Column/Field Titles
showHeaders
Display column headers/titles Default: `true` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

showRecNo

Table Rows and Columns
showRecNo
0=hide, 1=show on left of grid, 2=show on right of grid, 3 = hide details and show on left, 4 = hide grid show details, 5 = show details below grid Default: `1` New to phpLens 1.3 is showRecNo = 3. 3 will hide details grid and show the record number. If the childLens is enabled, the editor in the details area will still appear. New to phpLens 2.4.2 is showRecNo = 4 4 will hide the normal grid and show the details only. New to phpLens 3.1 is showRecNo = 5 5 will display the details below the grid. Syntax `$lens->showRecNo = 1;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

showSort

Table Column/Field Titles
showSort
Clicking on column titles will sort columns Default: `true` First click will sort ascending, second click will sort descending, and third to revert back to sort ascending, etc. Syntax `Boolean` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

showSortCols

Table Column/Field Titles
showSortCols
The columns or fields that users can click on to sort By default, all columns in the grid are sortable. To define only columns lastname and postcode aresortable, set: $lens->showSortCols = 'lastname;postcode'; Set Sort Order form Since phpLens 2.5.4, this property is also used to determine which are the sortable columns to display in the Set Sort Order form. If this property is not defined, then the Set Sort Order form is hidden. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

spDelete

Editing, Updating and Creating Records
spDelete
Stored procedure to delete a record The SQL to perform the delete. For example, if you need to use the following stored procedure DeleteRow to delete a record with a primary key column with the name "key": `call DeleteRow ({key})` and the variable {key} will be substituted with the correct values. Note: actually you can use any variable name for the key as phpLens searches for a variable delimited by { }. If the first character is '=', then it is evaluated by PHP first like the powerLens. Syntax `$lens->spDelete = 'call DeleteRow ({key})';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

spEdit

Editing, Updating and Creating Records
spEdit
Stored procedure to update a record Default: `''` The SQL to perform the update. For example, if you need to use the following stored procedure `EditRow` to update a record for a table with columns col1 and col2, we would use: `call EditRow({col1},{col2})` and the variables {col1} and {col2} will be substituted with the correct values. Only non-readonly fields are passed to spEdit. New in phpLens 2.0 is support for calling PHP programs. Simply prepend an = sign to your code. Before phpLens 3.1, we always assume that spEdit succeeds and the return value is ignored. In 3.1 and later, if you return: -1: Show Edit Record form and display SQL error message -2: Show Edit Record form, and do not display any error message array($error): Show Edit Record form, and display $error message (phpLens 3.3+) other values: Assume successful save, switch to the firstState. For example: `$lens->spEdit = '=ProcessRec({name},{postcode})'; function ProcessRec($name, $postcode) { global $DB; if (strlen($postcode) < 5) { printError("Invalid postcode"); return -2; } return DoStoreRecord($name,$postcode); }` Please note that spEdit is not supported if you are using input type checkbox or select multiple. To perform validation, use the eventPreUpdateField property. Note: Only columns defined in editLens and readonlyLens will be processed by spEdit when editMultiple = false. When editMultiple is true, only columns defined in editLens and are also visible in the grid (gridLens) are processed. All other columns will be set to null. Compatibility Between spEdit and editMultiple Properties Some people have complained that spEdit does not work the same when editMultiple is enabled, namely readonly fields are not passed as parameters to spEdit when editMultiple = true. The reason for this is that we have multiple html rendering engines. One for the grid (GridRenderer), one for editing (EditRenderer). When editMultiple = true, the editable fields are rendered by the EditRenderer engine, but readonly fields are rendered by the GridRenderer engine. The GridRenderer engine does not generate invisible input tags for the readonly fields. So we cannot pass these readonly fields to spEdit currently. The workaround is to read the readonly fields yourself, or pass them as hidden fields using a powerLens: <input type=hidden name=VAL"{PRIMARYKEY}" value="{VALUECOL}"> {_PRIMARY_KEY_} Since phpLens 2.4.10, {_PRIMARYKEY_} is a pre-defined variable you can place in your spEdit string. This is very useful when you allow the primary key to be modified, as this variable will hold the old value of the primary key, while the actual variable name will hold the new value. $lens->spEdit = '=InsertRecord({_PRIMARY_KEY_}, {KEY})'; For compound keys, if spEdit generates an SQL statement, then {_PRIMARYKEY_} will not hold the field value, but will generate the WHERE conditions as a string as shown below: $lens->spEdit = 'update table set col1 = {COL1} where {_PRIMARYKEY_}'; For compound keys, if spEdit is PHP code, then {_PRIMARYKEY_} will be an array consisting of the primary key values (in the order defined in $lens->keyCompound). Commits We use the default auto-commit behaviour. So two insert statements will be treated as two separate transactions by default. If you want to control your own transactions, you will need to use $DB->StartTrans() and $DB->CompleteTrans(), assuming that $DB has been pre-defined as the database connection. The only exception is in 3.1 or later, when editMultiple=true. Then saving multiple records is treated as a single transaction, and StartTrans/CompleteTrans is called automatically for you by phpLens. Syntax `# example 1 $lens->spEdit = 'call EditRow({col1},{col2})'; # example 2 - add an update timestamp for oracle/mysql $lens->spEdit = 'update table set col1 = {col1}, modified=SYSDATE where id={id}';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

spNew

Editing, Updating and Creating Records
spNew
Stored procedure to insert a new record Default: `''` The SQL to perform the insert. For example, if you need to use the following stored procedure `NewRow` to insert a record for a table with columns col1 and col2, we would use: `call NewRow({col1},{col2})` and the variables {col1} and {col2} will be substituted with the correct values. Only columns that are defined in newLens and readonlyLens will be substituted in. If the first character is '=', then it is evaluated by PHP first like the powerLens. New in phpLens 2.0 is support for calling PHP programs. Simply prepend an = sign to your code. Before phpLens 3.1, we always assume that spNew succeeds and the return value is ignored. In 3.1 and later, if you return: -1: Show New Record form and display SQL error message -2: Show New Record form, and do not display any error message array($error): Show New Record form, display $error msg (phpLens 3.3+) other values: Assume successful save, switch to the firstState. For example: $lens->spNew = '=ProcessRec({name},{postcode}); function ProcessRec($name, $postcode) { global $DB; if (strlen($postcode) < 5) { printError("Invalid postcode"); return -2; } return DoStoreRecord($name,$postcode); } To perform validation, use the eventPreInsertField property. Commits We use the default auto-commit behaviour. If you want to control your own transactions, you will need to use $DB->BeginTrans() and $DB->EndTrans(), assuming that $DB has been pre-defined as the database connection. Syntax `$lens->spNew = 'call NewRow({col1},{col2})'; or $lens->spNew = 'insert into table values({col1},{col2})'; or $lens->spNew = '=PHPFunction({col1},{col2})';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

sql

Essential
sql
Holds the SQL string sent to the database This property is also the 3rd parameter in the phpLens constructor. This SQL statement can be a SELECT statement or stored procedure. Don't do this: currently avoid using SELECT UNION statements, and do not place a limit on the rows returned yourself with SELECT TOP nrows from TABLE or SELECT * FROM TABLE LIMIT nrows. If you need to limit the number of rows returned, look in the phplens.inc.php file and you will see a constant defined: `define ('PHPLENS_MAX_ROWS',99999999); // 9.9 million` Redefine this constant to control the maximum records to return. In phpLens 1.1 onwards, you can access global PHP variables in the SQL if you prefix the SQL with = or %: =select * from table where col='$key' =select * from table where id='$HTTP_COOKIE_VARS['key']' =select * from {$country}codes Syntax `$lens = new phpLens($id,$DB,"=select * from \$table"); $lens->sql = 'select * from catalog';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

sqlDetail

Table and Grid formating
sqlDetail
SQL to use to display fields in the details Speed up your database retrieval by having seperate specialized SQL statements for retrieving grid results and detail results. Note that if you use this property, the lookupLens and powerLens properties will not work, because these properties affect the grid SQL, but not sqlDetail. Fortunately, this is a minor problem because you can use joins to simulate the behaviour of lookupLens, and use string expressions in your SELECT statement to generate the string formatting. Syntax `# by using 2 sql statements, we speed up grid access below: $lens = new PHPLens($id,$DB,'select name from table'); $lens->sqlDetail = 'select bigcol1, bigcol2, bigcol3 from table');` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0]

sqlEditNew

Editing, Updating and Creating Records
sqlEditNew
Allows you control what fields to display when editing or creating new records Allows you to fine-tune your SQL to retrieve the minimum number of rows for every situation. Syntax `# by using several sql statements, we speed up grid access below: $lens = new PHPLens($id,$DB,'select name from table'); $lens->sqlDetail = 'select bigcol1, bigcol2, bigcol3 from table'); # while we reserve the slower SELECT * from editing and record creation $lens->sqlEditNew = 'select * from table';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0]

sqlFilter
Warning: flock(): 804 bytes of buffered data lost during conversion to FILE*! in /var/www/html/php/phplens/adodb/adodb-csvlib.inc.php on line 92

Filtering and Searching
sqlFilter
Sets the sql statement when searching/filtering When we are viewing a single record and we want to perform a search, we don't want to search on that single record of course. We want to search on all the records in a table. So we provide an alternative SQL statement for searches. Similarly, sometimes we have readonly columns which are normally hidden when browsing, but you might want to expose them for searching. Syntax `# we search on name, category1, category2 in table $lens->sqlFilter = 'select name,category1,category2 from table'; # the grid results that will be displayed lens->sql = 'select name, gender, title, country from table';` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

sqlWhere

Programming
sqlWhere
Allows you to modify SQL where clause without modifying sql property If you set the following properties $lens->sqlWhere = "name='Lee'"; $lens->sql = "select * from people where age > 30 or sex='F'"; this will rewrite the sql to select * from people where (age > 30 or sex='F') and name = 'Lee' This property is useful for rewriting sql. NOTE: Since 3.2, this property has to be reset on every page request, as it is not retained in any session variable. Formerly it was saved by phpLens. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

subTotalFontPrefix

Grouping and totaling of rows
subTotalFontPrefix
Tags to prefix to subtotal label Default: `'<font size=2>'` This is not for the numeric subtotal, but for the caption of that subtotal. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

subTotalFontSuffix

Grouping and totaling of rows
subTotalFontSuffix
Tags to append to subtotal label Default: `'</font>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

sumLens

Grouping and totaling of rows
sumLens
Fields to sum Subtotals are enabled if groupLens is set. The totals at the bottom of the grid are stored in an array $lens->sumTotal. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

sumTotal

Grouping and totaling of rows
sumTotal
Array that holds the totals generated by sumLens Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

tdEdit

Editing, Updating and Creating Records
tdEdit
Set TD attributes for input cell when editing or creating records Default: `id="COL-#"` Sets the TD attribute of the cell containing the input tags to COL-$fieldname. So if you have a field name "OVERDRAFT", then the TD tag will have the attribute TD=COL-OVERDRAFT. The # is substituted with the field name. To disable this feature, set $lens->tdEdit = false; Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 3.0]

tdLens

Table Cell formating
tdLens
Set the TD attributes of cells Define cell attributes on a column by column basis. $lens->tdLens = 'col1^nowrap^col2^bgcolor=red'; You can also set an attribute for all columns using the field name '*': $lens->tdLens = '*^nowrap;field1^class=num-class nowrap'; In the above example, all fields are set to nowrap. Note that we have to define the nowrap for field1 because the field1 definition overrides the global * defintion. To dynamicly modify the cell color, you should still use the colorLens property as this property does not allow you to reference cell values or call PHP code dynamically. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 2.6.0]

templateAssign

Templates
templateAssign
Pass additional variables to the template engine Default: `false` Pass an array to the template engine. Syntax `# Smarty template variable {$COLOR} will be set to red $lens->templateAssign = array('COLOR'=>'red');` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

templateBaseDir

Templates
templateBaseDir
Define default location of templates directory. Sets the path to the following directories used by Smarty template engine: templates templates_c configs cache Syntax `$lens->templateBaseDir = '/usr/local/smartybase';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

templateDetail

Templates
templateDetail
Define Smarty template for details The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$_EDIT_} -- The edit record icon {$_DELETE_} -- The delete record icon {$_RECNO_} -- The record number (this is not the primary key) {$_PRIMARY_} -- urlencoded primary key The field values and the field titles are available also. If a field "name" is defined, then: {$NAME} -- field value {$NAME_T} -- field title Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateEdit

Templates
templateEdit
Define Smarty template for editing The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$_FORMBEGIN_} -- equivalent of the <FORM> tag {$_FORMEND_} -- equivalent of the </FORM> tag {$_EDIT_} -- "e" dynamic edit icon {$_SUBMIT_} -- submit button {$_CANCEL_} -- Cancel button {$ERRORMESSAGES} -- where to display error messages (see also templateShowErrors). All column values are available, and the data input fields also as variables. Assume that we have a column called NAME (all column names must be in upper case), then we have the following: {NAME} -- value of column NAME {NAME_T} -- title of column NAME {NAME_INPUT} -- input field for NAME View source of the forums at http://phplens.com/ for examples of template files. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateFilter

Templates
templateFilter
Template for search form The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$_FORMBEGIN_} -- equivalent of the <FORM> tag {$_FORMEND_} -- equivalent of the </FORM> tag {$_EDIT_} -- "e" dynamic edit icon {$_SUBMIT_} -- submit button {$_CANCEL_} -- Cancel button All column values are available, and the data input fields also as variables. Assume that we have a column called NAME (all column names must be in upper case), then we have the following: {NAME} -- input fields for column NAME {NAME_T} -- title of column NAME Syntax `$lens->templateFilter = 'find.tpl';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

templateFilterGrid

Templates
templateFilterGrid
Smarty template for one row of phpLens grid when filtering Use this if you need a custom template to display your filter/search results. If this property is not defined, but templateGrid is defined, the templateGrid template is used instead. The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$_EDIT_} -- The edit record icon {$_DELETE_} -- The delete record icon {$_RECNO_} -- The record number (this is not the primary key) {$_PRIMARY_} -- urlencoded primary key The field values and the field titles are available also. If a field "name" is defined, then: {$NAME} -- field value {$NAME_T} -- field title See also templateGrid. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateGrid

Templates
templateGrid
Smarty template for one row of phpLens grid The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$_EDIT_} -- The edit record icon {$_DELETE_} -- The delete record icon {$_RECNO_} -- The record number (this is not the primary key) {$_PRIMARY_} -- urlencoded primary key The field values and the field titles are available also. If a field "name" is defined, then: {$NAME} -- field value {$NAME_T} -- field title See also templateFilterGrid. Template Format The template can either be a html table or a set of td cells. If a table is defined, then phpLens will set the enclosing cell containing the table to fit the colspan. So if the template fits 4 columns, then the enclosing cell will be set to colspan=4. If it is a set of td cells, then the number of cells must match the number of columns defined in the grid. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateGridHdr

Templates
templateGridHdr
Template of the header row of phpLens grid where all field titles are shown in view state The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: if a field "name" is defined, then: {$NAME_T} -- field title Template Format The template can either be a html table or a set of td or th cells. If a table is defined, then phpLens will set the enclosing cell containing the table to fit the colspan. So if the template fits 4 columns, then the enclosing cell will be set to colspan=4. If it is a set of td or th cells, then the number of cells must match the number of columns defined in the grid. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateLayout

Templates
templateLayout
Template of phpLens in view state The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$COLORNAVBORDER} -- The color of the navigation menu background. {$LAYOUT_ATTR} -- all the layout table attributes, including bgcolor {$TOPCAPTION} {$BOTTOMCAPTION} {$GRIDDATA} -- an array holding an the html for each column {$DETAILDATA} -- the html for the details of a row {$PAGENO} -- the current page number {$NAVMENUS} -- the menus {$ERRORMESSAGES} -- where to display error messages (see also templateShowErrors). A synonym for {$LAYOUT_ATTR} is {$COLORBACKGROUND} for historical reasons. Also since 2.8, if you set $lens->templateLayoutAddFilter then a new variable becomes available, {$FILTERFORM} -- where to place the filter/search form Syntax `$lens->templateLayout = 'layout.tpl'; Contents of sample layout.tpl: <table {$LAYOUT_ATTR} border=0 cellspacing=0 cellpadding=1> <tr><td> <table bgcolor={$COLORNAVBORDER} width=100% cellspacing=0 cellpadding=0 border=0> <tr><td> {$TOPCAPTION}</td><td align=right>{$NAVMENUS}</td></tr> </table> </td></tr> <tr><td> <table border=0 width=100% cellspacing=0 cellpadding=0> <tr> {section name=cols loop=$GRIDDATA} <td valign=top> {$GRIDDATA[cols]} </td> {/section} {if strlen($DETAILDATA)>0} <td valign=top>{$DETAILDATA}</td> {/if} </tr> </table> </td></tr> <tr><td> <table bgcolor={$COLORNAVBORDER} width=100% border=0 cellspacing=0 cellpadding=0> <tr><td> {$BOTTOMCAPTION}</td><td align=right>{$NAVMENUS}</td></tr> </table> </td></tr> </table>` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateLayoutAddFilter

Templates
templateLayoutAddFilter
Adds new variable to layout template that holds filter/search form Default: `false` The new variable added is called {$FILTERFORM}. For example, if you want to show the filter form in both at the top and bottom of the phpLens grid, you can define the following layout template in your templates/layout.shtml file: {$FILTERFORM} {if strlen($ERRORMESSAGES)>0} {$ERRORMESSAGES} {/if} <table {$LAYOUT_ATTR} border=0 cellspacing=0 cellpadding=1> <tr><td> <table bgcolor={$COLORNAVBORDER} width=100% border=0 cellspacing=0 cellpadding=0> <tr><td> {$TOPCAPTION}</td><td align=right>{$NAVMENUS}</td></tr> </table> </td></tr> <tr><td> <table border=0 width=100% cellspacing=0 cellpadding=0> <tr> {section name=cols loop=$GRIDDATA} <td valign=top> {$GRIDDATA[cols]} </td> {/section} <td valign=top> {if strlen($FILTERFORM)>0} {$FILTERFORM} {/if} {if strlen($DETAILDATA)>0} {$DETAILDATA} {/if} </td> </tr> </table> </td></tr> <tr><td> <table bgcolor={$COLORNAVBORDER} width=100% border=0 cellspacing=0 cellpadding=0> <tr><td> {$BOTTOMCAPTION}</td><td align=right>{$NAVMENUS}</td></tr> </table> </td></tr> {$FILTERFORM} Syntax `$lens->layoutTemplate = 'layout.shtml'; $lens->templateLayoutAddFilter = true;` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.8]

templateMode

Templates
templateMode
Controls how edit/new templates display input fields This is a set of bit fields that control how input fields are displayed in edit and new record templates. Bit field 1: Setting it means that the _FORMBEGIN_ and _FORMEND_ values will be automatically added to the beginning and end of the template. Bit field 2: Setting it means that the field titles will be added above the input fields automatically, so you don't have to place {$COLUMNNAME_T} variables in the template yourself. Syntax `$lens->templateMode = 3; // add _FORM*_ values and show field titles $lens->templateMode = 2; // show field titles only $lens->templateMode = 1; // add _FORM*_ values only` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.2]

templateNew

Templates
templateNew
Template of phpLens when creating new records The Smarty template file must be placed in the templates subdirectory of the Web page. The following template variables are available: {$_FORMBEGIN_} -- equivalent of the <FORM> tag {$_FORMEND_} -- equivalent of the </FORM> tag {$_EDIT_} -- "e" dynamic edit icon {$_SUBMIT_} -- submit button {$_CANCEL_} -- Cancel button {$ERRORMESSAGES} -- where to display error messages (see also templateShowErrors). All column values are available, and the data input fields also as variables. Assume that we have a column called NAME (all column names must be in upper case), then we have the following: {NAME} -- value of column NAME {NAME_T} -- title of column NAME {NAME_INPUT} -- input field for NAME View source of the forums at http://phplens.com/ for examples of template files. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templatePrefix

Templates
templatePrefix
Prefix that indicates the beginning of a template or powerLens variable Default: `'{'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateSecure

Templates
templateSecure
When using new or edit templates the field checksums are used Default: `true` For extra security, we check that the fields being edited match those defined in phpLens editLens and newLens properties exactly if this property is set to true. Syntax `$lens->templateSecure = false;` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateShowErrors

Templates
templateShowErrors
Place error messages within template instead of showing them automatically Default: `false` By default, we always display error messages above the phpLens grid. However if you have custom screens, then you might need to customize the position of the error messages, or decide to hide them. Set this property to true to hide automatic display of error messages and to place the error messages in a template variable. The error messages are stored in the {ERRORMESSAGES} variable. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

templateSuffix

Templates
templateSuffix
Suffix that indicates the end of a template or powerLens variable Default: `'}' Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

textAreaHeader

Editing, Updating and Creating Records
textAreaHeader
Attributes for <textarea> tag when editing/creating records Default: `'rows=3 cols=40'` Use this to control the attributes of the text header. Although you can use this property to change the size of the textarea, we recommend using the textSizeLens property. If the textSizeLens is defined, it will override the value defined in textAreaHeader. Syntax `# Define for all textareas: $lens->textAreaHeader = 'rows=3 cols=80'; # Suppose you have 2 textareas linked to columns A and B: $lens->textAreaHeader= 'A^rows=2 cols=60;B^rows=10 cols=60'; Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

textAreaLens

Editing, Updating and Creating Records
textAreaLens
This lens determines which fields use the larger textarea tags for data entry This property is obsolete. Use textSizeLens

property instead, setting the number of rows to a value greater than 1.
This was formerly called textareaLens.
If the fields t1 and t2 are meant to use textarea's when editing or creating new records, then we would define:
$lens->textAreaLens = 't1;t2';

Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

textInputHeader

Editing, Updating and Creating Records
textInputHeader
Set attributes of <input type=text> tags for editing/creating records This property is obsolete and replaced by the inputLens. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

textInputMax

Editing, Updating and Creating Records
textInputMax
Visual width of <input type=text> tag. You can enter more chars than this! Default: `48` Applies to string types only. For numeric fields, we use the numInputLen propert. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

textInputMin

Editing, Updating and Creating Records
textInputMin
Minimum visual width of <input type=text> tag Default: `16` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

textSizeLens

Editing, Updating and Creating Records
textSizeLens
Determines the size of input text and textarea fields Manages the size of input and textarea fields. The syntax is: "ColumnName^columns^rows"; If rows is omitted, it defaults to 1. If rows > 1 then a textarea is used. Syntax `#To set a field "col1" to 60x3 and set "col2" to 40x1 use: $lens->textSizeLens = "col1^60^3;col2^40";` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.3]

titleColor

Table Column/Field Titles
titleColor
Sets the color of a span of titles Allows you to set the background color of field titles. For example: $lens->gridLens = "name;description;price;stock"; $lens->titleColor = "NAME^2^red;PRICE^1^green"; This will result in the NAME and DESCRIPTION titles to be backgrounds to be colored red, the PRICE title green, while the last field STOCK will use the default color. See also titleLevel1. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

titleFontPrefix

Table Column/Field Titles
titleFontPrefix
Tags to prefix column titles Default: `'<b>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

titleFontSuffix

Table Column/Field Titles
titleFontSuffix
Tags to append to column titles Default: `'</b>'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

titleHeader

Table Column/Field Titles
titleHeader
Attributes for <TH> tag for column titles in grid Default: `''` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

titleLevel1

Table Column/Field Titles
titleLevel1
Adds an additional title row which spans multiple columns to the grid Displays a top level header with the format: $lens->titleLevel1 = 'Field1^3^Products^green;Field2^2^<b>The Amount</b>^#C0C0C0'; This will display for an additional title header starting at field1 that spans 3 columns with the text "Products", and has the background color green, and a field2 in the same row that spans 2 cells with the text "Amount" in bold, and with the background color #C0C0C0. There are another additional title rows available in titleLevel2 and titleLevel3 , if they are defined. See also titleColor Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0.8]

titleLevel2

Table Column/Field Titles
titleLevel2
2nd title row Displays a header below titleLevel1 with the format: $lens->titleLevel2 = 'Field1^3^Products^green;Field2^2^Amount^#C0C0C0'; This will display for an additional title header starting at field1 that spans 3 columns, and has the background color green, and a field2 in the same row that spans 2 cells, and with the background color #C0C0C0. There are another additional title rows available in titleLevel1 and titleLevel3, if they are defined. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0.8]

titleLevel3

Table Column/Field Titles
titleLevel3
3rd title row Displays a header below titleLevel2 with the format: $lens->titleLevel3 = 'Field1^3^Title^green;Field2^2^Title 2^#C0C0C0'; This will display for an additional title header starting at field1 that spans 3 columns, and has the background color green, and a field2 in the same row that spans 2 cells, and with the background color #C0C0C0. There are another additional title rows available in titleLevel1 and titleLevel2, if they are defined. Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 2.0.8]

totalFontPrefix

Grouping and totaling of rows
totalFontPrefix
Tags to prefix to column total label This is not for the numeric total, but for the caption of that total. For the tags for the numeric total, see totalNumPrefix and totalNumSuffix. Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

totalFontSuffix

Grouping and totaling of rows
totalFontSuffix
Tags to append to column total label Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

totalNumPrefix

Grouping and totaling of rows
totalNumPrefix
Tags to prefix numeric totals and subtotals Default: `''` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

totalNumSuffix

Grouping and totaling of rows
totalNumSuffix
Tags to append to numeric totals and subtotals Default: `''` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

toUpper

Editing, Updating and Creating Records
toUpper
Convert all strings in text boxes to uppercase (when saving and searching) Default: `false` Useful for databases that require fields to be in uppercase for indexing purposes such as Oracle. Fields that are longer than 64 chars long are not converted to uppercase. Text entered in search screens is also uppercased. You can change this 64 character setting in phplens/adodb/adodb-recordset.inc.php, class ADORecordSet->blobSize property. Also see upperCase. In the most general case, you need to set $lens->upperCase = true; $lens->toUpper = true; because when you have COL = 'somevalue', you need to uppercase both sides like this: UPPER(COL) = UPPER('somevalue') Now upperCase does this for the left hand side(COL) and toUpper does it for the right hand side ('somevalue'). Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]

upperCase

Filtering and Searching
upperCase
Searches will change in the where clause COL='value' to upper(COL)='value' Default: `false` Only fields of type C or X (CHAR, VARCHAR2, CLOB) will be uppercased. In the most general case, you need to set $lens->upperCase = true; $lens->toUpper = true; because when you have COL = 'somevalue', you need to uppercase both sides like this: UPPER(COL) = UPPER('somevalue') Now upperCase does this for the left hand side(COL) and toUpper does it for the right hand side ('somevalue'). Oracle note: For Oracle (oci8) you will need to enable function indexes for best performance. This ensures that the SQL optimizer binds the the upper(COL) index correctly. Syntax `$lens->upperCase = true;` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.3]

urlParams

Programming
urlParams
Additional parameters to append to end of links Default: `true` A named anchor mark is placed at the top of the each phpLens object of the form: <a name=LensBM_$lens->id></a> When the user clicks on a phpLens link, there is no need for the user to scroll to the phpLens object because the reference to the anchor mark will cause your browser to auto-scroll to the correct place. You can replace this bookmark with your own parameters. You will not need to place a ? or & at the beginning of urlParams, because it is done for your automatically. PhpLens will generate the anchor tag at the beginning of the phpLens object. If you are doing special processing of phpLens and want to remove the anchor tag, set: $lens->urlParams = false; Note: Not supported for Netscape 4.77 or earlier because of Netscape brain damage. Also disabled for Opera for similar reasons (tested on Opera 6). Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.9]

validation

Editing, Updating and Creating Records
validation
Javascript or input mask for data and error message on error We provide 3 types of validation. 1. Input mask. For example, #### means enter exactly 4 digits. 2. Special validation functions. For example, =EMAIL means that this field should be checked for the standard internet email format. 3. Regular expression. Regular expression is activated if first character is =. 4. Javascript expression. Javascript is activated if the first character is %. This is since phpLens 3. When we use input mask validation, we can enter in the input mask the following:
X | 0-9 and A-Z, must exist
x | 0-9 and A-Z. This character is optional.
# | 0-9 or . and +/- must exist.
9 | 0-9 or . and +/-. This character is optional
+ | Positive numbers only
& | Any character, must exist
? | Any character, optional
\ | escape character
> | Uppercase
< | Lowercase
Examples
Telephone numbers with no area code. 7 digits must be filled, but some newer phone numbers have 8 digits, so make 1 character optional. | `9###-####`
Car part number with the format: 3 digit number, a hyphen followed by a 3 or 4 letter code | `###-XXXx`
Validation Functions The first character must be the equals (=) character. The code is not case-sensitive.
Description | Code
To validate email of the form: user@domain.com | `=EMAIL`
Credit cards (not yet) | `=CREDITCARD`
To validate email a regular expression is used. This regular expression is defined as a constant called `PHPLENS_EMAIL_REGEX`. You can override it by defining this constant before phplens.inc.php is included in your main php file. The regular expression used is the ugly but powerful: `^(\S+@).+((\.com)|(\.edu)|(\.gov)|(\.int)|(\.mil)|(\.net)|(\.org)|(\.info)|(\.biz)|(\.name)|(\.pro)|(\.museum)|(\.coop)|(\.aero)|(\.[a-z]{2,2}))$` Regular Expressions The first character must be the equals (=) character. All subsequent characters are treated as standard Javascript regular expression characters. /expr/ delimiters are not required.
Value must be either CAR or BOOK, case-insensitive. The $ at the end indicates that no further characters will be accepted. | `([Cc][Aa][Rr])|([Bb][Oo][Oo][Kk])$`
Value must begin with 'A' or 'a' followed by any other characters | `[aA].*`
Remember that the regular expressions are case-sensitive. You do not need to enter the ^ and $ in ^expr$ at the beginning and end of the regular expression as it is done automatically for you by phpLens. The second optional parameter is the error message on error. Javascript Expression The first character must be % to activate this. Any hash (#) character in the expression is substituted with the field value. To check if a value entered is between 10 to 20, use: $lens->validation='Col^%10 <= # && # &;lt;= 20'; Encoding Because ^ is used by regular expressions and phpLens as a seperator, we also allow a raw url encoded format. If the first and last characters of a validation setting are both '/', then the contents are raw url encoded as in the example below: # =^[0-9][0-9]\.[0-9]$ $lens->validation='Col^/%3D%5E%5B0-9%5D%5B0-9%5D%5C.%5B0-9%5D%24/'; Syntax `$lens = "ColumnName^Validation Mask^Invalid Error Message"; $lens->validation = "PHONE^#######9^Phone number must be 7 or 8 digits"; To treat a column as an email column: $lens->validation = 'mailaddress^=EMAIL'; # value must be greater than 0 $lens->validation='Col^%0 < #';` Basic:No Advanced/Enterprise:Yes DynamicEdit:Yes [Version 1.0]

versionLockCol

Editing, Updating and Creating Records
versionLockCol
Name of integer column used to implement versioning, so that optimistic locking can be used To implement locking, we store a version number for each record. Before updating, we check to see if the version number has changed (by someone else). If it has, we abort the save. Otherwise we increment the version number and save. If this column is not defined, or not in the columns retrieved by the SQL statement, this property is ignored. Syntax `$lens->versionLockCol = 'versioncol';` Basic:No Advanced/Enterprise:Yes DynamicEdit:No [Version 1.1]

warnLookupOverflow

Table Cell formating
warnLookupOverflow
Warning to display if lookupLens fails Default: `'No lookupLens mapping'` Basic:Yes Advanced/Enterprise:Yes DynamicEdit:No [Version 1.0]