Документация для разработчиков

Определение шагов мастера

Чтобы создать мастер, нужно в файле wizard.php определить все шаги и их содержимое. Каждый шаг определяется классом, который обязательно должен наследоваться от класса CWizardStep. В классе шага необходимо переопределить 3 метода:

  • InitStep – вызывается при добавлении шага в мастер. Метод предназначен для инициализации свойств шага: идентификатора (ID), заголовка, подзаголовка, кнопок перехода на следующие шаги и др. В этом методе обязательно нужно определить ID шага;
  • ShowStep – вызывается в момент показа шага пользователю. Метод предназначен для определения содержимого шага: в переменную $this->content необходимо записать весь вывод шага;
  • OnPostForm – вызывается при нажатии на любую из кнопок навигации мастера. В этом методе можно проверить входные данные, вернуть ошибки, изменить текущий шаг, выполнить любые другие действия;

Методы ShowStep и OnPostForm переопределять необязательно. Метод InitStep обязательно должен присутствовать в классе, т.к. в нем с помощью функции SetStepID определяется ID шага. В случае динамического определения шагов устанавливать ID шага в InitStep необязательно.

Класс СWizardBase является оболочкой мастера и содержит методы общие для всех шагов (работа с переменными мастера, управление кнопками навигации и др.). Для каждого подключаемого мастера создаётся экземпляр класса СWizardBase. Для получения доступа к методам класса СWizardBase в теле переопределяемых функций (InitStep, ShowStep, OnPostFrom) нужно получить объект мастера с помощью метода CWizardStep::GetWizard:

$wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
$myVar = $wizard->GetVar("myVar"); //Используем метод мастера (класс CWizardBase)

Для каждого шага, добавляемого в мастер, создаётся экземпляр класса CWizardStep. В переопределяемых функциях шага методы класса CWizardStep доступны через переменную-псевдоним $this. Каждый шаг мастера сам определяет, какие кнопки навигации (Назад, Далее, Готово, Отмена) будут показаны, и на какой шаг они будут вести. Названия кнопок можно изменить по своему усмотрению. Как правило, содержимое шага представляет собой набор полей Web-формы. Для упрощения работы с элементами Web-формы класс CWizardStep содержит методы для создания текстовых полей, переключателей, флажков и др.

Пример определения шагов мастера в файле wizard.php:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MainUserFields extends CWizardStep
{
function InitStep()
{
$this->SetStepID("main_fields");//ID шага

$this->SetTitle("Основные поля пользователя");//Заголовок
$this->SetSubTitle("Введите логин, пароль и e-mail нового пользователя"); //Подзаголовок

//Навигация
$this->SetNextStep("success");
$this->SetCancelStep("cancel");

$wizard =& $this->GetWizard(); // Получаем ссылку на объект мастера
$wizard->SetDefaultVar("active", "Y"); //Устанавливаем значение по умолчанию
}

function OnPostForm()
{
$wizard =& $this->GetWizard();

if ($wizard->IsCancelButtonClick())
return;

$success = true;
$login = $wizard->GetVar("login");
if (strlen($login) < 3)
$this->SetError("Логин должен быть больше 3 символов", "login");
else
{
$obUser = CUser::GetList($by="id", $order="desc", Array("LOGIN_EQUAL" => $login));
if ($obUser->Fetch())
{
$this->SetError("Такой логин уже существует", "login");
$success = false;
}
}

$password = $wizard->GetVar("password");
if (strlen($password) < 6)
{
$this->SetError("Пароль должен быть не меньше 6 символов", "password");
$success = false;
}

$email = $wizard->GetVar("email");
if (strlen($email) < 3 || !check_email($email))
{
$this->SetError("Вы ввели неверный E-mail", "email");
$success = false;
}

if (!$success)
return;

//Добавляем пользователя
$user = new CUser;
$arFields = Array(
"NAME" => $wizard->GetVar("user_name"),
"LAST_NAME" => $wizard->GetVar("user_surname"),
"EMAIL" => $wizard->GetVar("email"),
"LOGIN" => $wizard->GetVar("login"),
"ACTIVE" => ($wizard->GetVar("active") == "Y" ? "Y" : "N"),
"PASSWORD" => $wizard->GetVar("password"),
"CONFIRM_PASSWORD" => $wizard->GetVar("password"),
);

$userID = $user->Add($arFields);
if (intval($userID) > 0)
{
$wizard->SetVar("userID", $userID);
CFile::Delete($photo); //Удаляем временный файл
}
else
$this->SetError($user->LAST_ERROR);
}

function ShowStep()
{
$this->content .= '<table class="wizard-data-table">';

$this->content .= '<tr><th align="right">Активен:</th><td>'.$this->ShowCheckBoxField("active", "Y").'</td></tr>';

$this->content .= '<tr><th align="right"><span class="wizard-required">*</span>Логин (мин. 3 символа):</th><td>';
$this->content .= $this->ShowInputField("text", "login", Array("size" => 25));
$this->content .= '</td></tr>';

$this->content .= '<tr><th align="right"><span class="wizard-required">*</span>Пароль (мин. 6 символов):</th><td>';
$this->content .= $this->ShowInputField("password", "password", Array("size" => 25));
$this->content .='</td></tr>';

$this->content .= '<tr><th align="right"><span class="wizard-required">*</span>E-mail:</th><td>';
$this->content .= $this->ShowInputField("text", "email", Array("size" => 25));
$this->content .= '</td></tr>';

$this->content .= '<tr><th align="right">Имя:</th><td>'.$this->ShowInputField("text", "user_name", Array("size" => 25)).'</td></tr>';
$this->content .= '<tr><th align="right">Фамилия:</th><td>'.$this->ShowInputField("text", "user_surname", Array("size" => 25)).'</td></tr>';

$this->content .= '</table>';
$this->content .= '<br /><div class="wizard-note-box"><span class="wizard-required">*</span> Поля, обязательные для заполнения.</div>';
}
}

class SuccessStep extends CWizardStep
{
function InitStep()
{
$this->SetStepID("success");//ID шага
$this->SetTitle("Работа мастера успешно завершена");//Заголовок
//Навигация
$this->SetCancelStep("success");
$this->SetCancelCaption("Готово");
}

function ShowStep()
{
$this->content .= "Мастер успешно добавил нового пользователя. ";

$wizard =& $this->GetWizard();
$userID = intval($wizard->GetVar("userID"));
if ($userID > 0)
$this->content .= 'Идентификатор нового пользователя
<a target="_blank" href="/bitrix/admin/user_edit.php?ID='.$userID.'&lang='.LANGUAGE_ID.'">'.$userID.'</a>';
}
}

class CancelStep extends CWizardStep
{
function InitStep()
{
$this->SetTitle("Мастер прерван");
$this->SetStepID("cancel");
$this->SetCancelStep("cancel");
$this->SetCancelCaption("Закрыть");
}

function ShowStep()
{
$this->content .= "Мастер создания нового пользователя прерван. Новый пользователь не был создан.";
}
}
?>

После того как мы определили классы в файле wizard.php, их имена необходимо описать в файле .description.php:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
"NAME" => "Мастер создания нового пользователя",
"STEPS" => Array("MainUserFields", "SuccessStep", "CancelStep"), //Описание шагов
);

?>

Система автоматически создаст мастер и добавит в него шаги с названиями, описанные в файле .description.php.

Шаг ввода данных нового пользователя

После заполнения и отправки формы выведется окно с сообщением об удачном добавлении пользователя, либо об ошибке.

Динамическое определение шагов

Статическое описание шагов мастера в файле .description.php, облегчает задачу инициализации шагов мастера, но в то же время уменьшает гибкость. Часто необходимо инициализировать шаги мастера по какому-либо условию. При динамическом определении инициализация шагов происходит непосредственно в файле wizard.php, поэтому описывать названия классов в файле .description.php не нужно. В файле wizard.php необходимо создать объект мастера (экземпляр класса СWizardBase) и затем добавить в него объекты шагов c помощью методов AddStep или AddSteps. Метод Display выведет мастер на экран.

<?
//Создаем мастер
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);

//Добавляем шаги
$wizard->AddStep(new MainUserFields);
$wizard->AddStep(new SuccessStep);
$wizard->AddStep(new CancelStep);

/*
Или с помощью AddSteps:
$wizard->AddSteps(Array("MainUserFields", "SuccessStep", "CancelStep"));
*/

//Выводим
$wizard->Display();
?>

Вторым параметром метод CWizardBase::AddStep может принимать ID добавляемого шага. При инициализации шага с помощью AddStep с указанным вторым параметром, в классе шага необязательно переопределять метод InitStep для установки ID шага с помощью метода SetStepID.

<?
//Создаем мастер
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);

//Добавляем шаги с указанием идентификаторов
$wizard->AddStep(new MainUserFields, "main_fields");
$wizard->AddStep(new SuccessStep, "success");
$wizard->AddStep(new CancelStep, "cancel");

//Выводим
$wizard->Display();
?>

Вы также можете динамически задать свойства мастера и шагов:

<?
//Создаем мастер
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);

//Устнавим значение по уомлчанию для поля Логин
$wizard->SetDefaultVar("login", "new_user");

$mainStep = new MainUserFields;
//Изменим надпись кнопки Далее
$mainStep->SetNextCaption("Создать пользователя");

//Добавляем шаги
$wizard->AddStep($mainStep, "main_fields");
$wizard->AddStep(new SuccessStep, "success");
$wizard->AddStep(new CancelStep, "cancel");

//Выводим
$wizard->Display();
?>


Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2019, «1С-Битрикс», 2019
Наверх