Table of Contents

A. Functions

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')

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.

	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);
	}

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

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

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

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

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

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

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)

B. Methods of phpLens

Close   Error   PHPLens   Render   Reset   ResetAll   SetLang   SetState

function Close()

function Error($msg,$severity=LENSERROR)

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

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()

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();

This documentation system is maintained using phpLens