Форма

Компонента формы поддерживает следующие возможности:

1. Отображение управляющих элементов (поле ввода, текстовое поле, календарь, radio-кнопки, выпадающий список)
2. Отправка введенных данных (сохранение добавляемого или редактируемого элемента)
3. Валидация данных.
4. Обработка результатов отправки данных (успех или ошибка)

Создание формы

Компонента формы поддерживает следующие возможности:

1. Класс контроллера, наследуемый от AMI_ModForm
2. Класс отображения, наследуемый от AMI_ModFormViewAdm

Пример классов компонент формы:

class AmiSample_FormAdm extends AMI_ModFormAdm{
    /**
     * Save action dispatcher.
     *
     * @param  array &$aEvent  Event data
     * @return void
     */
    protected function _save(array &$aEvent){
        parent::_save($aEvent);
        if(is_object($this->oModelItem)){
            AMI::getSingleton('response')->addStatusMessage('origin_data', array('data' => d::getDumpAsString($this->oModelItem->getOriginData())));
            AMI::getSingleton('response')->addStatusMessage('difference_from_origin', array('data' => d::getDumpAsString($this->oModelItem->getDiffFromOrigin())));
        }
    }
}

class AmiSample_FormViewAdm extends AMI_ModFormViewAdm{
    protected function getModLocalePath(){
        return '_local/plugins_distr/' . $this->getModId() .  '/templates/form.lng';
    }

    public function __construct(){
        parent::__construct();

        $this->addField(array('name' => 'id', 'type' => 'hidden'));
        $this->addField(array('name' => 'nickname'));
        $this->addField(array('name' => 'mod_action', 'value' => 'form_save', 'type' => 'hidden'));
    }
}

Определение списка и порядка полей

Для добавления поля на форму необходимо использовать метод  addField. Пример:

$this->addField(array('name' => 'id', 'type' => 'hidden'));
$this->addField(array('name' => 'nickname'));
$this->addField(array('name' => 'birth', 'type' => 'date', 'validate' => array('custom', 'stop_on_error')));
$this->addField(array('name' => 'creation_date', 'type' => 'date', 'display_by_action' => 'edit'));

Параметром метода является ассоциативный массив:

Порядок элементов формы задается при помощи формирования позиций элементов, аналогично заданию порядка столбцов в табличном списке.

При добавлении поля создается позиция элемента. Если параметр position не указан явно, то позиция элемента добавляется там, где происходило последнее добавление элементов.

Для создания собственного элемента управления, необходимо передать значение html в массиве параметров. Пример:

$this->addField(array('name' => 'my_ctrl', 'html' => $ctrlHtml));

Валидация полей формы на стороне клиента

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

$this->addField(array('name' => 'birth', 'type' => 'date', 'validate' => array('custom')));

В этом случае при проверке поля будет посылаться сообщение «ON_FORM_FIELD_VALIDATE», которое можно перехватить и проверить на правильность. В случае, если проверка не прошла, достаточно установить флаг error массива параметров в ‘true’. Например: можно в плагин в файл {{templates/form.adm.js}}}} добавить код:

AMI.Message.addListener(
    'ON_FORM_FIELD_VALIDATE',
    function(oParameters){
	if(oParameters.oField.value.substr(-4)>1995){
       alert(AMI.Template.Locale.get('form_validate_birth_too_young'));
	     oParameters.error = true;
	     return(false);
	}
        return true;
    }
);

А в файл templates/client.lng:

%%form_validate_birth_too_young%en%%
User too young!
%%form_validate_birth_too_young%ru%%
Пользователь слишком молод!

И дата рождения пользователя будет проверяться, и в случае неудачи отобразится соответствующее сообщение.

Вкладки

Имеется возможность вставить на форму переключаемые области, выполненные в виде вкладок. Для этого сначала нужно зарезервировать на форме область под вкладки.

$this->addTabContainer('tabset');

Параметром является уникальное имя области, необходимое для добавления вкладок в эту область и позиционирования других элементов формы, относительно области вкладок.

При необходимости область вкладок можно позиционировать, задав позицию вторым параметром.

$this->addTabContainer('tabset', 'header.after');

Добавление вкладки в область вкладок:

$this->addTab('tabname1', 'tabset', self::TAB_STATE_ACTIVE);
$this->addTab('tabname2', 'tabset');

Первый параметр – уникальное имя вкладки, предназначенный для позиционирования полей внутри вкладки.

Второй параметр – имя области вкладок, в которой данная вкладка размещается.

Третий, необязательный, параметр – исходное состояние вкладки:

AMI_ModFormView::TAB_STATE_ACTIVE – текущая, выбранная вкладка.

AMI_ModFormView::TAB_STATE_NORMAL – обычная неактивная вкладка (по умолчанию).

AMI_ModFormView::TAB_STATE_DISABLED – “выключенная” вкладка.

Для полей формы вкладки можно рассматривать как секции, и добавление поля на вкладку аналогично включению поля в секцию.

$this->addField(array('name' => 'myfield1’, 'position' => 'tabname1.end'));

Для того, чтобы назначить вкладке читаемый заголовок, необходимо в языковом файле формы установить значения переменных form_tab_имяВкладки.

%%form_tab_tabname1%en%%
Tab title
%%form_tab_tabname1%ru%%
Заголовок вкладки

Примеры реализации

Задача. Есть модель, содержащая 4 свойства: id, nickname, birth, about. Необходимо создать классы компонента формы, отображающих все 4 эти свойства: id – скрытое поле, nickname – поле ввода, birth – календарь, about – визуальный редактор. При этом поля nickname и birth располагаются на одной вкладке формы, а поле about – на другой вкладке.

class AmiSample_FormAdm extends AMI_ModFormAdm{
    /**
     * Save action dispatcher.
     *
     * @param  array &$aEvent  Event data
     * @return void
     */
    protected function _save(array &$aEvent){
        parent::_save($aEvent);
        // Выдаем список исходных данных и изменившиеся данные из этого списка
        if(is_object($this->oModelItem)){
            AMI::getSingleton('response')->addStatusMessage('origin_data', array('data' => d::getDumpAsString($this->oModelItem->getOriginData())));
            AMI::getSingleton('response')->addStatusMessage('difference_from_origin', array('data' => d::getDumpAsString($this->oModelItem->getDiffFromOrigin())));
        }
    }
}

class AmiSample_FormViewAdm extends AMI_ModFormViewAdm{
    protected function getModLocalePath(){
        return '_local/plugins_distr/' . $this->getModId() .  '/templates/form.lng';
    }

    public function __construct(){
        parent::__construct();

        $this->addField(array('name' => 'id', 'type' => 'hidden'));

        // Добавляется область вкладки
        $this->addTabContainer ('tabs');

        // Добавляются вкладки
        $this->addTab ('general_tab', ‘tabs’, self::TAB_STATE_ACTIVE);
        $this->addTab ('about_tab', ‘tabs’);

        // Добавляются поля во вкладки
        $this->addField(array('name' => 'nickname', ‘position’ => ‘general_tab.end’));
        $this->addField(array('name' => 'birth', 'type' => 'date', ‘position’ => ‘general_tab.end’));
        $this->addField(array('about' => 'birth', 'type' => 'htmleditor', ‘cols’ => 80, ‘rows’ => 6, ‘position’ => ‘about_tab.end’));
        $this->addField(array('name' => 'mod_action', 'value' => 'form_save', 'type' => 'hidden'));
    }
}

Подробное описание логики работы примера в более сложном виде описано в главе «Пример реализации плагина».