as_propsheet: Property Sheet builder class

This class set written to simplify constructing "Property Sheet"-like HTML pages, mainly for setup/configuration screens in WEB projects.
as_propsheet may be used for rendering "TAB-style" sheets (any page can be activated by clicking on it's tab in the upper area) or "WIZARD-like" sheets (with "Previous" and "Next" buttons, and optional "Finish" button).

Attention: this property sheet classes use Javascript and DHTML, so browser compatibility should be tested while developing production version of Your site/web application.

Here is an instruction of how to embed "as_propsheet" engine into your intranet or internet project.

Installing as_propsheet on your site

Download distributive zip file and unzip it into temporary folder. If you will use Property Sheet classes in multiple pages, place as_propsheet.php file into one of the folders listed in your PHP.ini "include_path" variable. Otherwise, just place it into the folder with your main PHP-script.
Open Your PHP script, where You want to have property sheet.
Place "require_once('as_propsheet.php');" in the beginning of file
Prepare a few css styles to draw property page elements (see next chapter...)

Preparing CSS styles to draw Property sheet right

as_propsheet uses pre-defined css classes to draw tabs and property pages. They can be found int the sample script as_propsheet_sample.php.
You can substitute default class names by your ones, just by adding operators like $as_cssclass['textfield']='mycssname'; Here is a list of css styles, that must be present:

$as_cssclass['textfield'] (default - 'ibox') - style class to draw all text and password form elements.
$as_cssclass['button'] (default - 'button') - style used to draw button form elements
$as_cssclass['tactive'] (default - 'tblactive') - style for currently active tab in the upper tab panel.
$as_cssclass['tinactive'] (default - 'tblinactive') - style for currently inactive tabs. Note, these two styles above must have zero-width border-bottom, to make seamless look.
$as_cssclass['pagebody'] (default - 'pagebody') - background for all property pages. This style must have zero-width border-top, to seamless look with upper tabs.
$as_cssclass['pagebodywiz'] (default - 'pagebodywiz') - the same as 'pagebody', excluding the top border - it must be present, because this is used in WIZARDSTYLE mode, and no tabs will be drawn.
$as_cssclass['row_header'] (default - 'head') - You'll need this class if 'head' pseudo-fields used in some pages.

Creating TAB-style property sheet

First we create new instance of CPropertySheet class.

require_once('as_propsheet.php');
$sheet = new CPropertySheet('mysheet',800,200);

Now we register all property pages. One page can be registered with a field list, (to do this we create an array of CFormField objects), or it can be registered with another CPropertySheet object, or user PHP function name. This PHP function should draw a whole page. By the way, it can draw "nested" CPropertySheet as a part of page.

Example 1: registering property page as a field list

$fd = array();
$curvalue = isset($cfg['title'])? $cfg['title']: 'My nice site';
$fd[] = new CFormField('title','text','Your site main title',$curvalue,0,100,300);

$curvalue = isset($cfg['siteurl'])? $cfg['siteurl']: 'http://www.MyNiceSyte.net';
$fd[] = new CFormField('siteurl','text','URL for your site',$curvalue,0,100,300);

$curvalue = isset($cfg['shownews'])? $cfg['shownews']: 0;
$fd[] = new CFormField('shownews','checkbox','Show news on main page',$curvalue);
$sheet->AddPage('Page 1: basic parameters',$fd);

Example 2: You can define 'nested' property page and pass it as a parameter in AddPage():

...
$sheet2 = new CPropertySheet('nested2',600,100);
$flds = array();
$flds[] = new CFormField('f11','text','sub-field 1','initial value',0,100,200);
$flds[] = new CFormField('f12','checkbox','check box 12',0);
$sheet2->AddPage('sub-params-1',$flds);
...
$sheet->AddPage('nested property sheet...', $sheet2);

Example 3: registering a page with a user function used to draw it. (There must be a UdfvarPage() function somewhere in Your code )

$sheet->AddPage('User defined parameters','UdfvarPage');

Now it's time to render the PropertySheet

$sheet->Draw();

Of course, start FORM tag (<FORM ...>) should be echoed before Draw() calling, and final </FORM> - after it.

If You use field list, they will be rendered by as_propsheet - one field per row, so if it's not good for You, just write Your own rendering function and pass it's name in AddPage() instead of a field list.

Creating WIZARD-style property sheet

To create Wizard-like sheet, use WIZARDSTYLE constant. And it's a good idea to setup 'Finish' button:

require_once('as_propsheet.php');
$sheet = new CPropertySheet('mysheet',800,200,WIZARDSTYLE);

$sheet->SetFinishButton('FinishWizard()','Finish it!',false);

Classes and methods in as_propsheet

Here is a full method definition of as_propsheet classes.

Class: CPropertySheet

constructor: CPropertySheet($id, $width='',$height='',$sheetstyle=TABSTYLE) $id - must be unique in PHP page, so if You draw more than one Property Sheet, You should use different id's.
$width - "minimal" width of Your property sheet, 800 by default
$height - "minimal" height of Your property sheet, 120 by default.
$sheetstyle - sheet style, may be one of TABSTYLE or WIZARDSTYLE.

Sample: $sheet = new CPropertySheet('mysheet',800,200);

AddPage($tabtitle,$drawobject, $jsfunc_next='') Register new property page in the sheet.
$tabtitle - non=empty string that will be shown on the tab for this page
$drawobject - Here we can pass one of three types of data: CFormField array, another CPropertySheet object, or string with our function name. See propsheet_sample.php for details on every data type.
$jsfunc_next - This javascript function will be fired in WIZARDSTYLE mode, when user presses 'Next' button. It helps to fill next property pages dynamically, depending on previous user input. Besides, You can protect leaving page on some conditions, for example, if some fields have wrong or empty value; in that case your javascript function should return false value. See propsheet_sample.php for the working example - switch to WIZARD style and just try to press 'Next' button.

Sample: $sheet->AddPage('basic parameters',$fieldlist);

SetFinishButton($function,$caption='',$enabled=false) This function needed only in WIZARDSTYLE mode, for setting FINISH button behaviour.
$function - javascript function that will be called by pressing Finish button.
$caption - caption text on the button, "Finish" by default.
$enabled if set to false or 0, Finish button will be initially disabled. In that case, somewhere in Your javascript function must be a code enabling this button on some conditions.

Sample: $sheet->SetFinishButton('FinishPressed()','Finish setup',true);

Class: CPropertyPage, one "property-page" properties)

constructor: CPropertyPage($title,$drawfunc,$evtnext='') $title - caption text for the tab
$drawfunc - object array with field definitions, of user's PHP function name
$evtnext - javascript function name for using when "Next" button pressed in WIZARDSTYLE mode.

constructor is called automatically when you execute $sheet->AddPage()

Class: CFormField, one field definition, used in CPropertyPage

constructor: CFormField($name,$type='text',$prompt='',$initvalue='',$vlist='', $maxlength=10,$width=0,$title='',$onchange='',$addprm='') $type - one of the predefined types: text|password|head|select|checkbox
$prompt - prompt for the field (short description)
$initvalue - initial value for the field
$vlist - available values list for 'select' type. Can be associative array('key'=>value,...) or two-dimensional array ($v[0]=array($key0,$value0), $v[1]=array($key1,$value1),...)
$maxlength - MAXLENGTH tag value for the text/password fields
$width - if passed, additional style will be drawn for the field: style='width:NNN'
$title - TITLE='...' tag contents, used if You want to show tip for the field
$onchange - onChange/onClick event javascript code.
$addprm - any additional html code, it will be drawn inside <input...> tag

Sample: $fields[] = new CFormField('shownews','checkbox','Show news on main page',1);

Here is a simple example. More detailed one can be found in propsheet_sample.php file

require_once('as_propsheet.php');
$sheet = new CPropertySheet('mysheet',800,200);
$fields = array();
$fields[] = new CFormField('siteurl','text','URL for your site',$initvalue,0,100,300);
$fields[] = new CFormField('shownews','checkbox','Show news on main page',1);
$sheet->AddPage('main parameters', $fields);
$sheet->AddPage('UDF parameters', 'DrawMyUDFPage');
$sheet->Draw();

Version History

1.0.001 (2006-10-24)

First release on phpclasses.org

Class: CPropertySheet
constructor: CPropertySheet($id, $width='',$height='',$sheetstyle=TABSTYLE)	$id - must be unique in PHP page, so if You draw more than one Property Sheet, You should use different id's. $width - "minimal" width of Your property sheet, 800 by default $height - "minimal" height of Your property sheet, 120 by default. $sheetstyle - sheet style, may be one of TABSTYLE or WIZARDSTYLE. Sample: $sheet = new CPropertySheet('mysheet',800,200);
AddPage($tabtitle,$drawobject, $jsfunc_next='')	Register new property page in the sheet. $tabtitle - non=empty string that will be shown on the tab for this page $drawobject - Here we can pass one of three types of data: CFormField array, another CPropertySheet object, or string with our function name. See propsheet_sample.php for details on every data type. $jsfunc_next - This javascript function will be fired in WIZARDSTYLE mode, when user presses 'Next' button. It helps to fill next property pages dynamically, depending on previous user input. Besides, You can protect leaving page on some conditions, for example, if some fields have wrong or empty value; in that case your javascript function should return false value. See propsheet_sample.php for the working example - switch to WIZARD style and just try to press 'Next' button. Sample: $sheet->AddPage('basic parameters',$fieldlist);
SetFinishButton($function,$caption='',$enabled=false)	This function needed only in WIZARDSTYLE mode, for setting FINISH button behaviour. $function - javascript function that will be called by pressing Finish button. $caption - caption text on the button, "Finish" by default. $enabled if set to false or 0, Finish button will be initially disabled. In that case, somewhere in Your javascript function must be a code enabling this button on some conditions. Sample: $sheet->SetFinishButton('FinishPressed()','Finish setup',true);
Class: CPropertyPage, one "property-page" properties)
constructor: CPropertyPage($title,$drawfunc,$evtnext='')	$title - caption text for the tab $drawfunc - object array with field definitions, of user's PHP function name $evtnext - javascript function name for using when "Next" button pressed in WIZARDSTYLE mode. constructor is called automatically when you execute $sheet->AddPage()
Class: CFormField, one field definition, used in CPropertyPage
constructor: CFormField($name,$type='text',$prompt='',$initvalue='',$vlist='', $maxlength=10,$width=0,$title='',$onchange='',$addprm='')	$type - one of the predefined types: text\|password\|head\|select\|checkbox $prompt - prompt for the field (short description) $initvalue - initial value for the field $vlist - available values list for 'select' type. Can be associative array('key'=>value,...) or two-dimensional array ($v[0]=array($key0,$value0), $v[1]=array($key1,$value1),...) $maxlength - MAXLENGTH tag value for the text/password fields $width - if passed, additional style will be drawn for the field: style='width:NNN' $title - TITLE='...' tag contents, used if You want to show tip for the field $onchange - onChange/onClick event javascript code. $addprm - any additional html code, it will be drawn inside <input...> tag Sample: $fields[] = new CFormField('shownews','checkbox','Show news on main page',1);