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

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

Чтобы создать мастер, нужно в файле 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();
?>