Справочник по формам

Файл Form Helper содержит функции, которые помогают работать с формами.

• Загрузка этого справочника
• Экранирование значений полей
• Доступные функции

Загрузка этого справочника

Этот справочник загружается с помощью следующего кода:

helper('form');

Экранирование значений полей

Вам может потребоваться использовать HTML и символы, такие как кавычки, внутри элементов формы. Для безопасной работы с ними необходимо использовать функцию общую функцию esc().

Рассмотрим следующий пример:

$string = 'Here is a string containing "quoted" text.';

<input type="text" name="myfield" value="<?= $string ?>" />

Поскольку вышеприведенная строка содержит набор кавычек, это может привести к ошибке в форме. Функция esc() преобразует специальные HTML-символы, чтобы обеспечить безопасное использование:

<input type="text" name="myfield" value="<?= esc($string) ?>" />

Доступные функции

Доступны следующие функции:

form_open([$action = ''[, $attributes = ''[, $hidden = []]]])

Параметры:	$action (строка) – Строка URI действия/цели формы $attributes (смешанный тип) – Атрибуты HTML, в виде массива или экранированной строки $hidden (массив) – Массив определений скрытых полей
Возвращает:	Открывающий тег HTML-формы
Тип возвращаемого значения:	строка

Создаёт открывающий тег формы с адресом сайта, **сгенерированным на основе ваших настроек конфигурации**. Допускает добавление атрибутов формы и скрытых полей ввода, и всегда добавляет атрибут accept-charset, основанный на значении кодировки символов в файле конфигурации.

Основное преимущество использования этого тега вместо ручного кодирования HTML заключается в возможности большей портативности сайта в случае изменения URL-адресов.

Вот простой пример:

echo form_open('email/send');

Этот пример создаст форму, которая указывает на URL вашего сайта плюс сегменты URI «email/send», примерно так:

<form action="http://example.com/index.php/email/send" method="post" accept-charset="utf-8">

Вы также можете добавить {locale}, как показано ниже:

echo form_open('{locale}/email/send');

Этот пример создаст форму, которая указывает на URL вашего сайта плюс текущий локаль запроса с сегментами URI «email/send», примерно так:

<form action="http://example.com/index.php/en/email/send" method="post" accept-charset="utf-8">

Добавление атрибутов

Атрибуты можно добавить, передав ассоциативный массив во второй параметр, например так:

$attributes = ['class' => 'email', 'id' => 'myform'];
echo form_open('email/send', $attributes);

В качестве альтернативы, вы можете указать второй параметр в виде строки:

echo form_open('email/send', 'class="email" id="myform"');

Приведенные примеры создадут форму, похожую на эту:

<form action="http://example.com/index.php/email/send" class="email" id="myform" method="post" accept-charset="utf-8">

Если фильтр CSRF включен form_open() сгенерирует поле CSRF в начале формы. Вы можете указать ID этого поля, передав csrf_id в качестве одного из $attribute массива:

echo form_open('/u/sign-up', ['csrf_id' => 'my-id']);

вернёт:

<form action="http://example.com/index.php/u/sign-up" method="post" accept-charset="utf-8">
<input type="hidden" id="my-id" name="csrf_field" value="964ede6e0ae8a680f7b8eab69136717d" />

Примечание

Для использования автоматического создания поля CSRF необходимо включить фильтр CSRF для страницы формы. В большинстве случаев это достигается с помощью метода GET.

Добавление скрытых полей ввода

Скрытые поля можно добавить, передав ассоциативный массив в третий параметр, например так:

$hidden = ['username' => 'Joe', 'member_id' => '234'];
echo form_open('email/send', '', $hidden);

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

Этот пример создаст форму, похожую на эту:

<form action="http://example.com/index.php/email/send" method="post" accept-charset="utf-8">
    <input type="hidden" name="username" value="Joe" />
    <input type="hidden" name="member_id" value="234" />

form_open_multipart([$action = ''[, $attributes = ''[, $hidden = []]]])

Параметры:	$action (строка) – Строка URI действия/цели формы $attributes (смешанный тип) – Атрибуты HTML, в виде массива или экранированной строки $hidden (массив) – Массив определений скрытых полей
Возвращает:	Открывающий тег HTML-формы с атрибутом multipart
Тип возвращаемого значения:	строка

Эта функция идентична функции form_open() выше, за исключением того, что она добавляет атрибут multipart, необходимый для загрузки файлов с помощью формы.

form_hidden($name[, $value = ''])

Параметры:	$name (строка) – Имя поля $value (строка) – Значение поля
Возвращает:	Тег HTML скрытого поля ввода
Тип возвращаемого значения:	строка

Позволяет генерировать скрытые поля ввода. Можно передать имя и значение в виде строки для создания одного поля:

form_hidden('username', 'johndoe');
// Would produce: <input type="hidden" name="username" value="johndoe" />

… или ассоциативный массив для создания нескольких полей:

$data = [
    'name'  => 'John Doe',
    'email' => 'john@example.com',
    'url'   => 'http://example.com',
];

echo form_hidden($data);

/*
    Would produce:

    <input type="hidden" name="name" value="John Doe" />
    <input type="hidden" name="email" value="john@example.com" />
    <input type="hidden" name="url" value="http://example.com" />
*/

Также можно передать ассоциативный массив в поле значения:

$data = [
    'name'  => 'John Doe',
    'email' => 'john@example.com',
    'url'   => 'http://example.com',
];

echo form_hidden('my_array', $data);

/*
    Would produce:

    <input type="hidden" name="my_array[name]" value="John Doe" />
    <input type="hidden" name="my_array[email]" value="john@example.com" />
    <input type="hidden" name="my_array[url]" value="http://example.com" />
*/

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

$data = [
    'type'  => 'hidden',
    'name'  => 'email',
    'id'    => 'hiddenemail',
    'value' => 'john@example.com',
    'class' => 'hiddenemail',
];

echo form_input($data);

/*
    Would produce:

    <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" />
*/

form_input([$data = ''[, $value = ''[, $extra = ''[, $type = 'text']]]])

Параметры:	$data (массив) – Данные атрибутов поля $value (строка) – Значение поля $extra (смешанный тип) – Дополнительные атрибуты тега в виде массива или строки $type (строка) – Тип поля ввода, например, ‘text’, ‘email’, ‘number’ и т.д.
Возвращает:	Тег HTML текстового поля ввода
Тип возвращаемого значения:	строка

Позволяет генерировать стандартное текстовое поле ввода. Минимально можно передать имя и значение поля в первом и втором параметре:

echo form_input('username', 'johndoe');

Или передать ассоциативный массив, содержащий любые данные, которые вы хотите включить в форму:

$data = [
    'name'      => 'username',
    'id'        => 'username',
    'value'     => 'johndoe',
    'maxlength' => '100',
    'size'      => '50',
    'style'     => 'width:50%',
];

echo form_input($data);

/*
    Would produce:

    <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" />
*/

Если вы хотите добавить в форму дополнительные данные, например, JavaScript, вы можете передать их как строку в третьем параметре:

$js = 'onClick="some_function ()"';
echo form_input('username', 'johndoe', $js);

Или передать их как массив:

$js = ['onClick' => 'some_function ();'];
echo form_input('username', 'johndoe', $js);

Для поддержки расширенного набора полей ввода HTML5 вы можете передать тип ввода в качестве четвёртого параметра:

echo form_input('email', 'joe@example.com', ['placeholder' => 'Email Address...'], 'email');

/*
     Would produce:

    <input type="email" name="email" value="joe@example.com" placeholder="Email Address..." />
*/

form_password([$data = ''[, $value = ''[, $extra = '']]])

Параметры:	$data (массив) – Данные атрибутов поля $value (строка) – Значение поля $extra (смешанный тип) – Дополнительные атрибуты тега в виде массива или строки
Возвращает:	Тег HTML поля ввода пароля
Тип возвращаемого значения:	строка

Эта функция полностью идентична функции form_input() выше, за исключением того, что она использует тип ввода “password”.

form_upload([$data = ''[, $value = ''[, $extra = '']]])

Параметры:	$data (массив) – Данные атрибутов поля $value (строка) – Значение поля $extra (смешанный тип) – Дополнительные атрибуты тега в виде массива или строки
Возвращает:	Тег HTML поля ввода для загрузки файла
Тип возвращаемого значения:	строка

Эта функция полностью идентична функции form_input() выше, за исключением того, что она использует тип ввода “file”, позволяя загружать файлы.

form_textarea([$data = ''[, $value = ''[, $extra = '']]])

Параметры:	$data (массив) – Данные атрибутов поля $value (строка) – Значение поля $extra (смешанный тип) – Дополнительные атрибуты, добавляемые к тегу в виде массива или строкового литерала
Возвращает:	Тег HTML textarea
Тип возвращаемого значения:	строка

Эта функция во всех отношениях идентична функции form_input() выше, за исключением того, что она генерирует тип «textarea».

Примечание

Вместо атрибутов maxlength и size в приведённом выше примере следует указать rows и cols.

form_dropdown([$name = ''[, $options = [][, $selected = [][, $extra = '']]]])

Параметры:	$name (строка) – Имя поля $options (массив) – Ассоциативный массив опций для отображения $selected (массив) – Список полей для маркировки атрибутом selected $extra (смешанный тип) – Дополнительные атрибуты, добавляемые к тегу в виде массива или строкового литерала
Возвращает:	Тег HTML поля выбора (выпадающий список)
Тип возвращаемого значения:	строка

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

Пример:

$options = [
    'small'  => 'Small Shirt',
    'med'    => 'Medium Shirt',
    'large'  => 'Large Shirt',
    'xlarge' => 'Extra Large Shirt',
];

$shirts_on_sale = ['small', 'large'];
echo form_dropdown('shirts', $options, 'large');

/*
    Would produce:

    <select name="shirts">
        <option value="small">Small Shirt</option>
        <option value="med">Medium Shirt</option>
        <option value="large" selected="selected">Large Shirt</option>
        <option value="xlarge">Extra Large Shirt</option>
    </select>
*/

echo form_dropdown('shirts', $options, $shirts_on_sale);

/*
    Would produce:

    <select name="shirts" multiple="multiple">
        <option value="small" selected="selected">Small Shirt</option>
        <option value="med">Medium Shirt</option>
        <option value="large" selected="selected">Large Shirt</option>
        <option value="xlarge">Extra Large Shirt</option>
    </select>
*/

Если вы хотите, чтобы открывающий тег <select> содержал дополнительные данные, такие как атрибут id или JavaScript, вы можете передать его как строку в четвёртом параметре:

$js = 'id="shirts" onChange="some_function();"';
echo form_dropdown('shirts', $options, 'large', $js);

Или вы можете передать его как массив:

$js = [
    'id'       => 'shirts',
    'onChange' => 'some_function();'
];
echo form_dropdown('shirts', $options, 'large', $js);

Если массив, переданный как $options, является многомерным массивом, то form_dropdown() создаст <optgroup> с ключом массива в качестве метки.

form_multiselect([$name = ''[, $options = [][, $selected = [][, $extra = '']]]])

Параметры:	$name (строка) – Имя поля $options (массив) – Ассоциативный массив опций для отображения $selected (массив) – Список полей для маркировки атрибутом selected $extra (смешанный тип) – Дополнительные атрибуты, добавляемые к тегу в виде массива или строкового литерала
Возвращает:	Тег HTML поля множественного выбора
Тип возвращаемого значения:	строка

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

Использование параметров идентично использованию form_dropdown() выше, за исключением, конечно, того, что имя поля должно использовать синтаксис массива POST, например, foo[].

form_fieldset([$legend_text = ''[, $attributes = []]])

Параметры:	$legend_text (строка) – Текст для вставки в тег <legend> $attributes (массив) – Атрибуты для установки в теге <fieldset>
Возвращает:	Открывающий тег HTML fieldset
Тип возвращаемого значения:	строка

Позволяет генерировать поля fieldset/legend.

Пример:

echo form_fieldset('Address Information');
echo "<p>fieldset content here</p>\n";
echo form_fieldset_close();

/*
    Produces:

    <fieldset>
        <legend>Address Information</legend>
        <p>form content here</p>
    </fieldset>
*/

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

$attributes = [
    'id'    => 'address_info',
    'class' => 'address_info'
];

echo form_fieldset('Address Information', $attributes);
echo "<p>fieldset content here</p>\n";
echo form_fieldset_close();

/*
    Produces:

    <fieldset id="address_info" class="address_info">
        <legend>Address Information</legend>
        <p>form content here</p>
    </fieldset>
*/

form_fieldset_close([$extra = ''])

Параметры:	$extra (строка) – Любой текст, добавляемый после закрывающего тега, как есть
Возвращает:	Закрывающий тег HTML fieldset
Тип возвращаемого значения:	строка

Создаёт закрывающий тег </fieldset>. Единственное преимущество использования этой функции заключается в том, что она позволяет передавать данные, которые будут добавлены ниже тега. Например

$string = '</div></div>';
echo form_fieldset_close($string);
// Would produce: </fieldset></div></div>

form_checkbox([$data = ''[, $value = ''[, $checked = false[, $extra = '']]]])

Параметры:	$data (массив) – Данные атрибутов поля $value (строка) – Значение поля $checked (логическое) – Указать, нужно ли отметить чекбокс как выбранный $extra (смешанный тип) – Дополнительные атрибуты, добавляемые к тегу в виде массива или строкового литерала
Возвращает:	Тег HTML чекбокса
Тип возвращаемого значения:	строка

Позволяет генерировать поле чекбокса. Простой пример:

echo form_checkbox('newsletter', 'accept', true);
// Would produce:  <input type="checkbox" name="newsletter" value="accept" checked="checked" />

Третий параметр содержит логическое значение true/false, чтобы определить, нужно ли отметить поле как выбранное.

Аналогично другим функциям формы в этом помощнике, вы также можете передать массив атрибутов в функцию:

$data = [
    'name'    => 'newsletter',
    'id'      => 'newsletter',
    'value'   => 'accept',
    'checked' => true,
    'style'   => 'margin:10px'
];

echo form_checkbox($data);
// Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" />

Также, как и в других функциях, если вы хотите, чтобы тег содержал дополнительные данные, такие как JavaScript, вы можете передать их как строку в четвёртом параметре:

$js = 'onClick="some_function()"';
echo form_checkbox('newsletter', 'accept', true, $js);

Или вы можете передать их как массив:

$js = ['onClick' => 'some_function();'];
echo form_checkbox('newsletter', 'accept', true, $js);

form_radio([$data = ''[, $value = ''[, $checked = false[, $extra = '']]]])

Параметры:	$data (массив) – Данные атрибутов поля $value (строка) – Значение поля $checked (логическое) – Указать, нужно ли отметить радиокнопку как выбранную $extra (смешанный тип) – Дополнительные атрибуты, добавляемые к тегу в виде массива или строкового литерала
Возвращает:	Тег HTML радиокнопки
Тип возвращаемого значения:	строка

Эта функция во всех отношениях идентична функции form_checkbox() выше, за исключением того, что она использует тип ввода «radio».

form_label([$label_text = ''[, $id = ''[, $attributes = []]]])

Параметры:	$label_text (строка) – Текст для вставки в тег <label> $id (строка) – ID элемента формы, для которого создаётся метка $attributes (строка) – Атрибуты HTML
Возвращает:	Тег HTML метки поля
Тип возвращаемого значения:	строка

Позволяет генерировать <label>. Простой пример:

echo form_label('What is your Name', 'username');
// Would produce:  <label for="username">What is your Name</label>

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

Пример:

$attributes = [
    'class' => 'mycustomclass',
    'style' => 'color: #000;'
];

echo form_label('What is your Name', 'username', $attributes);
// Would produce:  <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label>

form_submit([$data = ''[, $value = ''[, $extra = '']]])

Параметры:	$data (строка) – Имя кнопки $value (строка) – Значение кнопки $extra (смешанный тип) – Дополнительные атрибуты, добавляемые к тегу в виде массива или строкового литерала
Возвращает:	Тег HTML input типа submit
Тип возвращаемого значения:	строка

Позволяет генерировать стандартную кнопку отправки. Простой пример:

echo form_submit('mysubmit', 'Submit Post!');
// Would produce:  <input type="submit" name="mysubmit" value="Submit Post!" />

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

form_reset([$data = ''[, $value = ''[, $extra = '']]])

Параметры:	$data (string) – Название кнопки $value (string) – Значение кнопки $extra (mixed) – Дополнительные атрибуты, добавляемые к тегу в виде массива или литеральной строки
Возвращает:	Тег HTML-кнопки сброса
Тип возвращаемого значения:	string

Позволяет генерировать стандартную кнопку сброса. Использование идентично form_submit().

form_button([$data = ''[, $content = ''[, $extra = '']]])

Параметры:	$data (string) – Имя кнопки $content (string) – Текст метки кнопки $extra (mixed) – Дополнительные атрибуты, добавляемые к тегу в виде массива или литеральной строки
Возвращает:	Тег HTML-кнопки
Тип возвращаемого значения:	string

Позволяет генерировать стандартный элемент кнопки. Можно передать имя и содержимое кнопки в первом и втором параметрах:

echo form_button('name','content');
// Would produce: <button name="name" type="button">Content</button>

Или передать ассоциативный массив, содержащий любые данные, которые вы хотите включить в вашу форму:

$data = [
    'name'    => 'button',
    'id'      => 'button',
    'value'   => 'true',
    'type'    => 'reset',
    'content' => 'Reset',
];

echo form_button($data);
// Would produce: <button name="button" id="button" value="true" type="reset">Reset</button>

Если вы хотите, чтобы ваша форма содержала дополнительные данные, такие как JavaScript, вы можете передать их в виде строки в третьем параметре:

$js = 'onClick="some_function()"';
echo form_button('mybutton', 'Click Me', $js);

form_close([$extra = ''])

Параметры:	$extra (string) – Любое содержимое, которое нужно добавить после закрывающего тега, без изменений
Возвращает:	Закрывающий тег HTML формы
Тип возвращаемого значения:	string

Создаёт закрывающий тег </form>. Единственное преимущество использования этой функции — возможность передавать данные, которые будут добавлены под этим тегом. Например:

$string = '</div></div>';
echo form_close($string);
// Would produce:  </form> </div></div>

set_value($field[, $default = ''[, $html_escape = true]])

Параметры:	$field (string) – Имя поля $default (string) – Значение по умолчанию $html_escape (bool) – Нужно ли отключить HTML-экранирование значения
Возвращает:	Значение поля
Тип возвращаемого значения:	string

Позволяет установить значение поля ввода или текстовой области. Вы должны указать имя поля через первый параметр функции. Второй (необязательный) параметр позволяет задать значение по умолчанию для формы. Третий (необязательный) параметр позволяет отключить HTML-экранирование значения, в случае необходимости использования этой функции в сочетании, например, с form_input(), и избежать двойного экранирования.

Пример:

<input type="text" name="quantity" value="<?= set_value('quantity', '0') ?>" size="50" />

В вышеприведённой форме при загрузке будет отображено «0».

set_select($field[, $value = ''[, $default = false]])

Параметры:	$field (string) – Имя поля $value (string) – Значение для проверки $default (string) – Является ли значение значением по умолчанию
Возвращает:	Атрибут ‘selected’ или пустая строка
Тип возвращаемого значения:	string

Если вы используете раскрывающийся список <select>, эта функция позволяет отобразить элемент меню, который был выбран.

Первый параметр должен содержать имя раскрывающегося списка, второй параметр — значение каждого элемента, а третий (необязательный) параметр позволяет установить элемент по умолчанию (используйте булевы значения true/false).

Пример:

<select name="myselect">
    <option value="one" <?= set_select('myselect', 'one', true) ?>>One</option>
    <option value="two" <?= set_select('myselect', 'two') ?>>Two</option>
    <option value="three" <?= set_select('myselect', 'three') ?>>Three</option>
</select>

set_checkbox($field[, $value = ''[, $default = false]])

Параметры:	$field (string) – Имя поля $value (string) – Значение для проверки $default (string) – Является ли значение значением по умолчанию
Возвращает:	Атрибут ‘checked’ или пустая строка
Тип возвращаемого значения:	string

Позволяет отобразить состояние чекбокса, которое было отправлено.

Первый параметр должен содержать имя чекбокса, второй — его значение, а третий (необязательный) параметр позволяет установить значение по умолчанию (используйте булевы значения true/false).

Пример:

<input type="checkbox" name="mycheck" value="1" <?= set_checkbox('mycheck', '1') ?> />
<input type="checkbox" name="mycheck" value="2" <?= set_checkbox('mycheck', '2') ?> />

set_radio($field[, $value = ''[, $default = false]])

Параметры:	$field (string) – Имя поля $value (string) – Значение для проверки $default (string) – Является ли значение значением по умолчанию
Возвращает:	Атрибут ‘checked’ или пустая строка
Тип возвращаемого значения:	string

Позволяет отобразить состояние радиокнопок, которое было отправлено. Эта функция идентична функции set_checkbox() выше.

Пример:

<input type="radio" name="myradio" value="1" <?= set_radio('myradio', '1', true) ?> />
<input type="radio" name="myradio" value="2" <?= set_radio('myradio', '2') ?> />

Примечание

Если вы используете класс валидации форм, вы всегда должны указать правило для вашего поля, даже если оно пустое, для работы функций set_*(). Это связано с тем, что если объект валидации формы определён, управление set_*() передаётся методу класса, а не общей вспомогательной функции.