as_propsheet: Property Sheet builder class

Russian version

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 engine uses 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 intra/internet project.

Installing as_propsheet on your site

  1. 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.
  2. Open Your PHP script, where You want to have property sheet.
    Place "require_once('as_propsheet.php');" in the beginning of file
  3. 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 in 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:

Creating TAB-style property sheet

First we create new instance of CPropertySheet class.

$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 with a user defined PHP function's name. This PHP function should draw a whole page, and it can draw "nested" property sheet object(s) somewhere in the page, just by creating new CPropertySheet instance and calling Draw() method.

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']: '';
$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);
$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
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:

$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='', $p1=false, $p2=false, $p3=false, $p4=false) 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.
$p1...$p4 - You can pass up to 4 parameters, that can be used by HTML-drawing function. Used only when user function name passed in {$drawobject} parameter.

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);
Draw($startpage=false) This function draws the whole property sheet. Optional parameter sets initially active page number. If omitted, the first one will be active at start.
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|textarea|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);
If You need both 'width' and 'height' style attributes, You should use last parameter, $addprm (for example, to draw TEXTAREA field of desired size):
$addprm = "style='width:100%; height:120px;' ";

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

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

Version History

1.03.004 (2007-03-01) 1.0.001 (2006-10-24)

Copyright © Alexander Selifonov,