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

English version

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

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

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

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

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

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

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

Создание 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) 1.0.001 (2006-10-24)

Copyright © Alexander Selifonov, 2006as-works.narod.ru