as_propsheet: Классы для вывода Property Sheet-страниц

Данный модуль служит для построения мульти-страничных экранов ввода данных, известных "в миру" как Property Sheet.
as_propsheet может выводить два типа многостраничных экранов: "TAB-style" экраны (для переключения страниц служат "закладки" в верхней части), и "WIZARD-style" экраны (последовательный переход от страницы к странице, с помощью кнопок "Следующий","предыдущий", и "Finish").

ВНИМАНИЕ: для вывода используются JavaScript и возможности DHTML, так что нужно помнить о совместимости с предполагаемыми версиями браузеров, при развертывании финального проекта в интра- или интернет.

Ниже приводится описание работы с классами модуля as_propsheet.

Установка as_propsheet на Вашем сайте

Загрузите дистрибутивный zip файл и распакуйте в любой каталог. Если "движок" Property Sheet будет использоваться во многих файлах, целесообразно поместить файл as_propsheet.php в одну из папок, перечисленных в файле PHP.ini, переменной "include_path". В противном случае достаточно положить его в одну папку со своим проектом.
В начале своего PHP-скрипта вставить строку полдключения модуля:
require_once('as_propsheet.php');
Подготовить несколько CSS-классов, используемых в as_propsheet для правильного отображения элементов на экране (см.следующую часть)

Подготовка CSS стилей для работы с Property sheet

as_propsheet использует предопределенные и описанные вне самого модуля css-классы. Образец их может быть взят в рабочем примере - as_propsheet_sample.php.
Вы можете заменить имена классов "по умолчанию" на свои, добавив до вызова функции рисования (Draw()) операторы вида $as_cssclass['textfield']='mycssname';
Список имен классов задается в глобальной переменной-массиве $as_cssclass:

$as_cssclass['textfield'] (по умолч. - 'ibox') - стиль для вывода текстовых полей ввода (input type=text|password|textarea)
$as_cssclass['button'] (по умолч. - 'button') - стиль для вывода элемента "кнопка" (input type=submit, &ly;button..>
$as_cssclass['tactive'] (по умолч. - 'tblactive') - стиль для "язычка" текущей активной страницы
$as_cssclass['tinactive'] (по умолч. - 'tblinactive') - стиль для неактивных язычков Обратите внимание, эти два стиля должны иметь нулевую нижнюю границу (border-bottom), для обеспечения правильного вида.
$as_cssclass['pagebody'] (по умолч. - 'pagebody') - фоновый стиль для всех страниц (property pages). У этого стиля не должно быть верхней границы (border-top), для обеспечения правильного вида.
$as_cssclass['pagebodywiz'] (по умолч. - 'pagebodywiz') - такой же как 'pagebody', за исключением условия по верхней границе - ее здесь наоборот надо выводить, т.к. этот стиль используется в режиме WIZARD-style, когда верхних "язычков" не будет.
$as_cssclass['row_header'] (по умолч. - 'head') - Этот стиль понадобится, если Вы используете заголовочные блоки внутри одной страницы (реализуются занесением в список полей псевдо-поля типа 'head')

Создание TAB-style экрана

Создаем объект класса CPropertySheet:

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

Теперь зарегистрируем в нем наши страницы свойств (property pages).
Для вывода содержимого страницы передается либо список полей, либо другой объект класса CPropertySheet, (вложенный мульти-страничный экран), либо наша собственная функция на PHP.

Пример 1: регистрация страницы со списком полей

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

Пример 2: Можно в внутри одной страницы выводить вложенный мульти-страничный блок:

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

Пример 3: Следующую страницу будет рисовать наша функция (в нашем примере - UdfvarPage()).

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

Теперь можно сгенерировать и вывести HTML-код:

$sheet->Draw();

Ествественно, стартовый тег формы (<FORM ...>) нужно выводить до вызова Draw(), а закрывающий </FORM> - после.

Переданные списки полей выводятся одно за одним, по полю на строке (заголовок слева, поле-справа), и если такой вид не подходит, надо использовать свою функцию вывода.

Создание WIZARD-style экранов

Создание Визардов мало чем отличается - нужно лишь при создании объекта CPropertySheet использовать константу WIZARDSTYLE, а также вызвать функцию регистрации кнопки "Финиш":

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

$sheet->SetFinishButton('FinishWizard()','Финиш!',false);

Описание классов и их методов модуля as_propsheet

Ниже приводится полный список классов и их методов.

Класс: CPropertySheet

constructor: CPropertySheet($id, $width='',$height='',$sheetstyle=TABSTYLE) $id - уникальный символьный идентификатор таблицы, (уникальность необходима, если на одной HTML странице выводится более одного объекта CPropertySheet).
$width - "минимальная" ширина таблицы со списком страниц, 800 по умолчанию.
$height - "минимальная" высота таблицы со списком страниц, 120 по умолчанию.
$sheetstyle - тип таблицы, TABSTYLE (по умолчанию) или WIZARDSTYLE.

Пример: $sheet = new CPropertySheet('mysheet',800,200);

AddPage($tabtitle,$drawobject, $jsfunc_next='',$p1=false,$p2=false,$p3=false,$p4=false) Регистрирует в таблице одну страницу (Property Page).
$tabtitle - строка с заголовком, выводимым на "язычке" страницы
$drawobject - массив со списком полей (объектов класса CFormField), либо другой объект класса CPropertySheet? либо имя своей функции отрисовки HTML-кода страницы. (См. подробности вызовов в propsheet_sample.php)
$jsfunc_next - Эта javascript функция нужна в режиме WIZARDSTYLE и вызывается перед переходом на следующую страницу (при нажатии на кнопку "следующий"). С ее помощью можно динамически обновить значения полей на следующих страницах в зависимости от введенных ранее, либо проверить корректность заведенных данных и при необходимости блокировать уход со страницы (в этом случае функция долджна вернуть значение false)
См. propsheet_sample.php - переключитесь в режим WIZARDSTYLE, и попробуйте попереключать кнопку 'Next'.
$p2-p4 - пользовательские параметры, которые могут быть использованы для отрисовки HTML-кода. Например, можно вывести аналогичные страницы с формой, но с различным наполнением. Используются, только если в $drawobject передано строка - имя пользовательской функции.

Пример: $sheet->AddPage('basic parameters',$fieldlist);

SetFinishButton($function,$caption='',$enabled=false) Этот метод вызывается только в режиме WIZARDSTYLE, чтобы была сформирована кнопка FINISH.
$function - javascript функция, отрабатываемая при нажатии на финальную кнопку.
$caption - Текст на кнопке, "Finish" по умолч.
$enabled (по умолч. 0), если 0, кнопка Finish будет в выведена с атрибутом disabled. Тогда в Ваших javascript функциях должен быть разблокирующий код (например, в функции перехода с предпоследней на последнюю страницу).

Пример: $sheet->SetFinishButton('FinishPressed()','Finish setup',true);

Draw($startpage=false) Выводит наш многостраничный экран. Необязательный параметр $startpage задает номер "видимой" страницы. Если не задан или false/0, активной будет первая страница.

Класс: CPropertyPage, описание одной страницы "property-page")

constructor: CPropertyPage($title,$drawfunc,$evtnext='') $title - текст в закладке
$drawfunc - список полей|объект CPropertySheet|имя функции
$evtnext - имя javascript функции на событие "Next" (WIZARDSTYLE)

конструктор вызывается автоматически при выполнении CPropertySheet::AddPage()

Класс: CFormField, описание одного редактируемого поля

constructor: CFormField($name,$type='text',$prompt='',$initvalue='',$vlist='', $maxlength=10,$width=0,$title='',$onchange='',$addprm='') $type - один из допустимых типов: text|password|textarea|head|select|checkbox
$prompt - сопроводительный текст перед полем (описание)
$initvalue - начальное значение
$vlist - список доступных значений для поля типа SELECT. Может быть задан как ассоциативный массив - array('key'=>value,...) или двумерный массив : $v[0]=array($key0,$value0); $v[1]=array($key1,$value1),...
$maxlength - значение тега MAXLENGTH для полей типа text/password
$width - если передан, в атрибутах поля будет вставлен дополнительный css-код : style='width:NNN'
$title - всплывающая подсказка (тело тега TITLE='...' )
$onchange - код для событий onChange/onClick для поля.
$addprm - прочий дополнительный HTML-код с атрибутами, вставляется в тело тега <input...>

Пример: $fields[] = new CFormField('shownews','checkbox','Show news on main page',1);
Если нужно задать style-атрибуты для ширины и высоты, ('width','height'), используйте последний параметр, $addprm (например, для вывода поля TEXTAREA нужного размера):
$addprm = "style='width:100%; height:120px;' ";

В конце - простой пример. Более полный см. в 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.03.004 (2007-03-01)

В метод CPropertySheet::AddPage() добавлено 4 пользовательских параметра, позволяющих при соответствующем их использовании в Вашей функции вывода HTML-кода формировать различные страницы, даже если их рисует одна функция.
Fix: CPropertySheet::Draw() имеет дополнительный параметр - номер активной страницы, что не было документировано.

1.0.001 (2006-10-24)

Первый публичный релиз на phpclasses.org

Класс: CPropertySheet
constructor: CPropertySheet($id, $width='',$height='',$sheetstyle=TABSTYLE)	$id - уникальный символьный идентификатор таблицы, (уникальность необходима, если на одной HTML странице выводится более одного объекта CPropertySheet). $width - "минимальная" ширина таблицы со списком страниц, 800 по умолчанию. $height - "минимальная" высота таблицы со списком страниц, 120 по умолчанию. $sheetstyle - тип таблицы, TABSTYLE (по умолчанию) или WIZARDSTYLE. Пример: $sheet = new CPropertySheet('mysheet',800,200);
AddPage($tabtitle,$drawobject, $jsfunc_next='',$p1=false,$p2=false,$p3=false,$p4=false)	Регистрирует в таблице одну страницу (Property Page). $tabtitle - строка с заголовком, выводимым на "язычке" страницы $drawobject - массив со списком полей (объектов класса CFormField), либо другой объект класса CPropertySheet? либо имя своей функции отрисовки HTML-кода страницы. (См. подробности вызовов в propsheet_sample.php) $jsfunc_next - Эта javascript функция нужна в режиме WIZARDSTYLE и вызывается перед переходом на следующую страницу (при нажатии на кнопку "следующий"). С ее помощью можно динамически обновить значения полей на следующих страницах в зависимости от введенных ранее, либо проверить корректность заведенных данных и при необходимости блокировать уход со страницы (в этом случае функция долджна вернуть значение false) См. propsheet_sample.php - переключитесь в режим WIZARDSTYLE, и попробуйте попереключать кнопку 'Next'. $p2-p4 - пользовательские параметры, которые могут быть использованы для отрисовки HTML-кода. Например, можно вывести аналогичные страницы с формой, но с различным наполнением. Используются, только если в $drawobject передано строка - имя пользовательской функции. Пример: $sheet->AddPage('basic parameters',$fieldlist);
SetFinishButton($function,$caption='',$enabled=false)	Этот метод вызывается только в режиме WIZARDSTYLE, чтобы была сформирована кнопка FINISH. $function - javascript функция, отрабатываемая при нажатии на финальную кнопку. $caption - Текст на кнопке, "Finish" по умолч. $enabled (по умолч. 0), если 0, кнопка Finish будет в выведена с атрибутом disabled. Тогда в Ваших javascript функциях должен быть разблокирующий код (например, в функции перехода с предпоследней на последнюю страницу). Пример: $sheet->SetFinishButton('FinishPressed()','Finish setup',true);
Draw($startpage=false)	Выводит наш многостраничный экран. Необязательный параметр $startpage задает номер "видимой" страницы. Если не задан или false/0, активной будет первая страница.
Класс: CPropertyPage, описание одной страницы "property-page")
constructor: CPropertyPage($title,$drawfunc,$evtnext='')	$title - текст в закладке $drawfunc - список полей\|объект CPropertySheet\|имя функции $evtnext - имя javascript функции на событие "Next" (WIZARDSTYLE) конструктор вызывается автоматически при выполнении CPropertySheet::AddPage()
Класс: CFormField, описание одного редактируемого поля
constructor: CFormField($name,$type='text',$prompt='',$initvalue='',$vlist='', $maxlength=10,$width=0,$title='',$onchange='',$addprm='')	$type - один из допустимых типов: text\|password\|textarea\|head\|select\|checkbox $prompt - сопроводительный текст перед полем (описание) $initvalue - начальное значение $vlist - список доступных значений для поля типа SELECT. Может быть задан как ассоциативный массив - array('key'=>value,...) или двумерный массив : $v[0]=array($key0,$value0); $v[1]=array($key1,$value1),... $maxlength - значение тега MAXLENGTH для полей типа text/password $width - если передан, в атрибутах поля будет вставлен дополнительный css-код : style='width:NNN' $title - всплывающая подсказка (тело тега TITLE='...' ) $onchange - код для событий onChange/onClick для поля. $addprm - прочий дополнительный HTML-код с атрибутами, вставляется в тело тега <input...> Пример: $fields[] = new CFormField('shownews','checkbox','Show news on main page',1); Если нужно задать style-атрибуты для ширины и высоты, ('width','height'), используйте последний параметр, $addprm (например, для вывода поля TEXTAREA нужного размера): $addprm = "style='width:100%; height:120px;' ";