phpLens manual: Methods

A. Functions

These functions can be called at any time.

PHPLensConnect PHPLensPConnect PHPLensPredictState PHPLensLastState

function &PHPLensConnect($id,$sql,$dbms,$server,$user=false,$pwd=false,$db=false,$lang='en_us')
function &PHPLensPConnect($id,$sql,$dbms,$server,$user=false,$pwd=false,$db=false,$lang='en_us')

Two similar functions to connect to a database and return a phpLens object. The PHPLensPConnect function will perform a persistent connection for speed, the other does a normal connect.

Returns: phpLens object or false on failure.

Parameters:

$id: the unique id that identifies the phpLens object. Also the primary key that maps to the phplens configuration table. Must be no more than 10 characters long (note: since phpLens 2.1, it is 38 characters long) and consist of only alphanumeric characters or underscores.
$sql: SQL statement to retrieve the records.
$dbms: RDBMS driver to connect to the database. For the latest legal values, see the ADODB documentation. Possible settings include 'mysql', 'postgres', 'mssql', 'oracle', 'sybase', 'access', 'odbc', 'vfp', 'ibase'.
$server: address of the server (eg. 'localhost'), or the DSN to use.
$user: login id. Optional.
$pwd: password. Optional.
$db: database to connect to. Optional.
$lang: language file to use. Default is en_us, which means it will look for a file called phplens-lang-en_us.inc.php to load. The file must contain the class PHPLens_en_us which holds the text strings to use. So if you want to support Korean, set $lang = 'kr' and create a file called phplens-lang-kr.inc.php which contains the class PHPLens_kr to hold the Korean text strings.

Source for the functions is provided: function &PHPLensConnect ($id,$sql,$dbms,$server,$user=false,$pwd=false,$db=false,$lang='en_us') { $conn = &ADONewConnection($dbms); if (!$conn->Connect($server,$user,$pwd,$db)) return false; return new PHPLens($id,$conn,$sql,$lang); } function &PHPLensPConnect ($id,$sql,$dbms,$server,$user=false,$pwd=false,$db=false,$lang='en_us') { $conn = &ADONewConnection($dbms); if (!$conn->PConnect($server,$user,$pwd,$db)) return false; return new PHPLens($id,$conn,$sql,$lang); }
Example of connecting to MySQL:

$lens = PHPLensPConnect('RandID','select * from table','localhost','root','pwd','db1');

Example of connecting to Oracle:

$lens = PHPLensPConnect('ORARand23','select * from table','','scott','tiger','');

Example of connecting to Microsoft SQL Server:

$lens = PHPLensPConnect('mssql_9','select * from table','192.168.0.1','sa','secret','db');

Example of connecting to MS Access (ODBC) with UK English:

$lens = PHPLensPConnect('access_98','select * from table','AccessDSN','','','','en_uk');

Example of connecting to mssql (ODBC):

$lens = PHPLensPConnect('odbc_mssql','select * from table','DSN','userid','password');

function PHPLensPredictState($id, [$firststate='VIEW'])

Returns the predicted next state of the phpLens object as a string by examining the $_POST and $_GET arrays. This can be called before the phpLens object is created because it reads the state from a session variable. The $id parameter is the unique id used to identify the phpLens object. If the first screen is the create new record or filter/search screen, you need to set the $firststate to 'NEW' or 'FILTER'.

This function is very useful when you want to optimize your SQL statements because you can set different SQL statements to use based on the predicted state.

There are 2 cases where the prediction might not be accurate, on saving a new or updated record. Then the next state should normally be 'VIEW', but if an error is detected before saving, typically because a must fill field has been left empty, then the user will be prompted to edit that must fill field, so the state will not change to 'VIEW'. Thus in the case of saving a new record we return 'NEW?' and on updating a new record we return 'EDIT?'.

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. This works by setting firstState='EDITSAVE'.

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, i suggest using

 substr($this->curState,0,4) == 'EDIT'

See curState for the legal values, and an example of usage is topics.php at phplens.com

Also new to phpLens 2.4.2 is we store the curState value in a HTML comment at the bottom of the phpLens HTML. This is useful if you need to detect what state you are in from a Browser or Web Browser control in Internet Explorer. The generated comment looks like the following:

<!-- LENS_".$this->id.'_STATE='.$this->curState." -->

This allows us to open up phpLens (in the IE Web Browser control) from VB/Delphi/VFP to edit a record (set $this->curState = 'EDITSAVE') and detect when the record is saved by searching for the string "LENS_{$this->id}_STATE=VIEW -->" in the WebControl.object.document.body.innerHTML property and close the VB/Delphi/VFP window.

function PHPLensLastState($id)

Returns the last state of the phpLens object as a string. This can be called before the phpLens object is created because it reads the state from a session variable. The $id parameter is the unique id used to identify the phpLens object. See curState for the legal values.

B. Methods of phpLens

These can only be called as an object method, eg. $lens->Render().

Close Error PHPLens Render Reset ResetAll SetLang SetState

function Close()

Frees some data structures, including the recordset. Does not close the database connection.

function Error($msg,$severity=LENSERROR)

Displays error message $msg, with the severity of the message indicated by {LENSWARNING=-1, LENSERROR=0, LENSERROR_SEVERE=1}. Override this to control or hide Error messages. Alternatively, use the errorHandler property.

function PHPLens($id, $dbconnection, $sql, $lang='en_us')

Constructor for PHPLens class.

Returns: phpLens object.

Parameters:

$id: the unique id that identifies the phpLens object. Also the primary key that maps to the phplens configuration table.
$dbconnection: ADODB database connection object.
$sql: SQL statement to retrieve the records
$lang: String that maps to a language file such as phplens-lang-$lang-inc.php. Source code for the language file is provided for you to customize.

function Render()

Draws the HTML on the screen.

function Reset()

Resets phpLens, resetting all filters and sort orders. Note that the currently selected record is still selected.

function ResetAll()

Resets phpLens, resetting all filters and sort orders, and the currently selected record is de-selected. Added in 3.1.

SetLang($language)

Since phpLens 2.6, you can dynamicly modify the language setting using the SetLang function. For example, you might have a language file phplens-lang-fr.inc.php. You can set this language using:

	$lens = PHPLensPConnect(...);
	$lens->SetLang('fr'); // will include_once this file if located in PHPLENS_DIR.
	$lens->Render();

Or if you are using applets you can put in the $lens->overrideFunction (the SetLensApplet_$id function).

If the language string length is greater than 6 characters, then we assume that a full file path is being passed to SetLang().

function SetState($state)

Sets the current state of phpLens. Must be called before $lens->Render(). See curState for the legal values of $state.

Example:

$lens = new PHPLens(...);
if (isset($_GET['hide'])) $lens->SetState('HIDE');
$lens->Render();