Использование класса Form - energy-coresky/air GitHub Wiki
Класс Form позволяет строить сложные формы, используя иерархические свойства массивов PHP. С его помощью, можно организовать различные манипуляции с формами, валидацию полей форм на javascript и PHP, визуализацию объектов из базы данных – прототипов полей форм (страницы типа show, browse).
Подразумевается, что первоначально поля форм визуализируются сверху вниз, по отношению друг к другу. Формы описываются в гибридных массивах PHP, содержащих числовые и строковые ключи. Если ключ строковый, то он является прототипом атрибута "name" для элемента формы и дополнительно, может содержать правило валидации. Остальные элементы поля формы, описываются в значении к этому ключу, в числовом массиве. Если ключ числовой, а значение – строка, то эта строка, используется без преобразований, во время визуализации формы. Если ключ числовой, а значение – массив, то это поле формы, в котором отсутствует атрибут "name":
# определение формы
$form = [
'<fieldset><legend>Simple form</legend>',
'+fio' => ['Your name'], # input-type=text by default
'sex' => ['Your sex', 'select', ['male', 'female']],
['Go', 'button', 'onclick="return sky.f.ajax(box)"'],
'</fieldset>',
];
# визуализация
echo new Form($form);
<div id="f1-message"></div>
<script>
$(function() { // для валидации формы на javascript
sky.f.set('#f1', {
'fio':'+',
'+':['this field cannot be empty', '']
}, []);
});
</script>
<form method="post" enctype="multipart/form-data" id="f1">
<fieldset><legend>Simple form</legend>
<dl>
<dt>Your name</dt>
<dd><input type="text" value="" name="fio">
<span class="red"></span></dd>
</dl>
<dl>
<dt>Your sex</dt>
<dd><select name="sex">
<option value="0" selected>male</option>
<option value="1">female</option>
</select></dd>
</dl>
<dl>
<dt></dt><dd>
<input type="button" value="Go" onclick="return sky.f.ajax(box)">
</dd>
</dl>
</fieldset>
<input type="hidden" value="WmXsftK" name="_csrf">
</form>Валидация на PHP:
(new Form($form))->validate(); # Ok or Exception
echo '$_POST: <pre>' . html(var_export($_POST, true)) . '</pre>';Формы, также, можно определить в Yaml формате:
#.test определение формы:
- <fieldset><legend>Simple form</legend>
+fio: [Your name] # input-type=text by default
sex: [Your sex, select, [male, female]]
- [Go, button, onclick="return sky.f.ajax(box)"]
- </fieldset>
#.test# визуализация
echo new Form(yml('+ inc(test) filename.yml'));Возможно, вы обратили внимание, что при стиле определения полей форм, представленном выше, нельзя задекларировать два поля формы с одинаковым атрибутом "name", например, name="fname[]", так как ключи массивов всегда уникальны. Проблема решается с помощью метода Form::X(..), который всегда возвращает объект xForm и даже позволяет вставлять несколько элементов формы (подформу):
$subform = [
'fname[]' => ['First name'], # input type="text"
'lname[]' => ['Last name'],
];
$form = [
'Chess game:<br>',
'White player:<br>', Form::X($subform), # числовой ключ массива
'Black player:<br>', Form::X($subform),
];В примере выше, определено 4 поля <input type="text" ... >.
Для изменения порядка визуализации элементов формы (вертикально-горизонтально и обратно), используется массив в массиве:
$form = [
['Phone', [ # здесь "'Phone'," – может отсутствовать
'type' => ['', 'select', ['mobile', 'stationary']],
'num' => ['', '', 'placeholder="Enter 10 digits"'],
]],
['Go', 'submit'],
];Визуализация:
Элементами форм могут быть все элементы ввода HTML, в том числе HTML5. В массиве, описывающем элемент формы, второй элемент - всегда тип элемента. Это может быть прототип атрибута type для тега <input> или имя тега, например для <select>. Первый элемент массива, обычно название поля формы или значение атрибута value, как для submit. Для тега <input type="hidden" name="xxx" value="1"> имеется сокращение: $coolform = ['xxx' => 1];.
Также типом элемента может быть:
ni - no item, нет элемента ввода. Используется для вывода произвольного текста вместо элемента ввода, с учетом стандартного форматирования
echo new Form([[111, 'ni', 222]]);
# output:<form method="post" enctype="multipart/form-data" id="f1">
<dl><dt>111</dt>
<dd>222</dd>
</dl><input type="hidden" value="WmXsftK" name="_csrf">
</form>li - list item, нет элемента ввода. Подобно ni, но используется тег <li>.
custom - custom item. Третьим параметром в массиве, должна быть callback функция для отрисовки элемента, в её параметрах объект формы и имя элемента. Пример из приложения AB.SKY:
# использование в форме:
'company_id' => [L_COMPANY, 'custom', 'draw::lookup']
# метод draw::lookup
static function lookup($form, $name) {
global $sky;
$ok = isset($form->row[$name]) && $form->row[$name];
$the_id = $ok ? $form->row[$name] : '';
$the_val = $ok ? $form->row[$obj = substr($name, 0, -3)] : '';
if ('show' == $sky->_1) # for Form::show_table(..)
return $the_id ? a($the_val, 'javascript:;', "onclick=\"run(['$obj','show&id=$the_id'])\"") : ' ';
return $form->input('hidden', $the_id, 'name="' . $name . '"')
. $form->input('text', $the_val, 'class="psearch" placeholder="type for search..."')
. a('<img src="img/a_del.gif"/>', 'javascript:;');
}chk - элемент checkbox, в котором отсутствует атрибут name, но присутствует <input type="hidden" name=... >. Т.е. когда элемент выбран, методом POST будет передаваться 1, а когда не выбран 0, в отличие от стандартного элемента ввода checkbox, который ничего не передает в postfields данных, когда элемент не выбран.
img - для загрузки изображений. После загрузки произвольной картинки, можно вырезать изображение фиксированных размеров. Используется класс w2/file_t.php и sky.js.
doc - аналогичный функционал, для загрузки произвольных файлов.
Детальнее смотрите Form::draw_form(..) и Form::draw_table(..).
При описании форм, в массиве с фиксированным индексом -1, можно определить пользовательские правила валидации, переопределить существующие в классе по умолчанию и настроить условную валидацию. Также, можно указать префикс атрибутов "name", для всех элементов подформы:
class MyForm {
function form() {
return [
'<fieldset><legend>Юридический адрес</legend>',
Form::X($this->subform('urid_')),
'</fieldset>',
'<fieldset><legend>Фактический адрес</legend>',
Form::X($this->subform('phiz_')),
'</fieldset>',
];
}
private function subform($mk) {
$street_type = ['улица', 'проспект', 'переулок', 'площадь'];
return [
-1 => [
'!' => 'Заполните поля формы!'
[$mk],
'zip' => [t('введите 5 цифр'), '/^\d{5}$/'],
'+' => [t('обязательное поле')],
],
['Область', [
'region' => ['', 'select', sqlf('@select id, name from region')],
'/zip' => ['Почтовый индекс', '', 'style="width:90px"'],
]],
'+city' => ['Населенный пункт'],
[[
'street_type' => ['', 'select', $street_type],
'+street' => [''],
]],
'+house' => ['Дом'],
];
}
}Встроенные валидаторы класса форм:
+ - this field cannot be empty
- - enter valid E-mail
~ - enter valid phone number
. - enter login
* - enter password
# - enter numbers
Сообщения встроенных валидаторов, можно переопределить или локализировать для разных языков мультиязычного приложения, как в примере выше. Также, можно определить пользовательские валидаторы с использованием регулярных выражений. Для определения полей форм с такими валидаторами, необходимо первым символом ключа поля формы, указать "/".
! - показать общее для формы сообщение, если javascript-валидация не прошла, и перемотать страницу вверх, к началу формы. По умолчанию, не работает, требуется явное определение.
В конфигурационном массиве, также, можно настроить условную валидацию. В ключе указывается атрибут name для элемента управления, который скрывает/показывает часть формы. А в значении массив, где указывается начало/конец части формы: 'addr' => ['phiz_region', 'phiz_house']. Смотрите пример ниже - описание javascript метода sky.f.slide(..).
Javascript метод sky.f.slide(..) можно использовать для показа/скрытия части формы. Если элементы части формы, которые могут быть скрыты, содержат валидаторы, необходимо настроить условную валидацию. Когда такая часть формы скрыта, валидация будет отменена и на уровне javascript и на уровне PHP:
$opt = ['совпадает с юридическим', 'не совпадает'];
$form = [
'<fieldset><legend>Юридический адрес</legend>',
Form::X($this->subform('urid_')),
'</fieldset>',
'addr' => ['Фактический адрес', 'radio', $opt, 0, 'onclick="return sky.f.slide(this,\'#sxd\')"'],
'<fieldset id="sxd" style="display:none"><legend>Фактический адрес</legend>',
Form::X($this->subform('phiz_')),
'</fieldset>',
];Метод Form::X(..) : xForm может содержать переменное количество аргументов. Если аргумент один, подразумевается, что в форму, просто вставляется подформа. Этот метод, также, может разделять холст на несколько колонок и вставлять подформы, если аргументов несколько. Первым аргументом должен быть массив, содержащий конфигурацию:
$form = Form::X(
['width="40%"', 'width="30%"', 'width="30%"'],
$subform1, $subform2, $subform3
);Если, как в примере выше, колонок 3 или более, будет использована табличная верстка. Иначе, DIV или TABLE верстку, можно указать явно в конфигурации, в значении массива с ключом opt: 'opt' => Form::OPT_TABLE или 'opt' => Form::OPT_DIV. В значении массива с ключом etc, можно указать дополнительные атрибуты для тегов <table> или <div>: 'etc' => 'class="comment"'. В случае табличной вёрстки, в значениях массива с числовыми ключами 0,1..N, можно указать дополнительные атрибуты для тегов <td>, как в примере выше, смотрите Form::proc_x(..).
В конце концов, вместо подформы (массива PHP), например $subform3 из примера выше, можно вставить любой скаляр или объект xForm. Преобразование будет произведено автоматически: is_array($ary) or $ary = [$ary];. Таким образом, объект xForm - это такое же описание формы как и описание формы в массиве PHP, и такое действие: Form::X(Form::X([Form::X($subform3)])) ничего не изменит.
Методы Form::repeat_begin(string $class) и Form::repeat_end(string $ancor) можно использовать в формах, для повторения части формы на javascript, которая может дублироваться и содержит элементы формы, где атрибут name элементов формы - массив:
$form = [
'<fieldset><legend>All your phones</legend>',
Form::repeat_begin('clsid'),
['Phone', [
'type[]' => ['', 'select', ['mobile', 'stationary']],
'num[]' => ['', '', 'placeholder="Enter 10 digits"'],
]],
Form::repeat_end('Add phone'),
['Go', 'submit'],
'</fieldset>',
];Визуализация:
При визуализации такой формы с заполненными данными, для элементов формы type[] и num[], в $row должны передаваться числовые массивы. Для валидации и сбора значений, переданных в POST запросе, можно воспользоваться методом $post = Form::repeat_val(['type', 'num']). В параметре передается массив имен элементов формы.
Form::A(array $row, array|xForm $form) : string - если валидация не используется, проще воспользоваться этим методом. Метод возвращает строку - визуализацию формы. Параметр $row может содержать пустой массив (для страниц new) или ассоциативный массив (для страниц edit) - ряд значений из таблицы в БД, прототип формы.
Form::show_table(array $row, array $form) - метод можно использовать для визуализации объекта из БД, используя верстку элементов формы. Где $row - строка из таблицы в БД - прототип элементов формы, $form - массив элементов формы. Пример кода из контроллера приложения AB.SKY:
<?php
class c_company extends Controller
{
// ... other class code
function j_show($id) {
global $user;
if (!$row = $this->t_company->row($id))
return 404;
$parent = $row['parent_id'];
$com = $this->t_company->listing($parent ? ['c.id=' => $parent] : ['c.parent_id=' => $id]);
$com['head'] = $parent ? L_PARENTCOMPANY : L_CHILDCOMPANIES;
$f4 = $this->is_mobile ? '' : ' - F4';
return [
'coord' => $coord = $this->m_ary->coord((object)$row, 'company'),
'show' => Form::show_table($row + ['_coord' => $coord], $this->t_company->form($row)),
'e_sale' => $this->t_sale->listing(['s.company_id=' => $id]),
'e_company' => $com,
'e_person' => $this->t_person->listing(['p.company_id=' => $id]),
'e_project' => $this->t_project->listing(['p.company_id=' => $id]),
'e_file' => $this->t_file->listing(['f.obj_id=' => $id, 'f.obj=' => 'com']),
'e_activity'=> $this->t_activity->listing(['a.company_id=' => $id]),
'upd' => 4 & $user->u_com ? draw::btn(L_UPDATE . $f4, "'company','edit&id=$id'", 1) : '',
'right' => draw::btn(t('Add to top'), ['company', $id]),
];
}
}Часть шаблона Jet:
#.show ------------------------------------------------------------------------------
@prt()
@blue(L_COMPANY, $upd, $right)
<div style="border:1px solid #748AAC;">{!$show!}</div>
@inc(_common.map)
<p>@inc(_sale.list)
<p>@inc(.list)
<p>@inc(_person.list)
<p>@inc(_project.list)
<p>@inc(_file.list)
<p>@inc(_activity.list)
#.show
Визуализация:
