Html-помощник ¶

Каждое веб-приложение формирует большое количество HTML-разметки. Если разметка статическая, её можно эффективно сформировать смешиванием PHP и HTML в одном файле, но когда разметка динамическая, становится сложно формировать её без дополнительной помощи. Yii предоставляет такую помощь в виде Html-помощника, который обеспечивает набор статических методов для обработки часто-используемых HTML тэгов, их атрибутов и содержимого.

Примечание: Если ваша разметка близка к статической, лучше использовать непосредственно HTML. Нет никакой необходимости в том, чтобы всё подряд оборачивать вызовами Html-помощника.

Основы ¶

Так как формирование динамической HTML-разметки при помощи конкатенации строк очень быстро вносит хаос в проект, Yii предоставляет набор методов для управления атрибутами тэгов и формирования тэгов на основе этих атрибутов.

Формирование тэгов ¶

Код формирования тэга выглядит следующим образом:

<?= Html::tag('p', Html::encode($user->name), ['class' => 'username']) ?>

Здесь первый аргумент - это название тэга. Второй - содержимое, которое будет заключено между открывающим и закрывающим тэгами. Заметьте, что мы используем Html::encode. Это связано с тем, что содержимое не экранируется автоматически, чтобы можно было по-необходимости использовать чистый HTML. Третий аргумент - это массив настроек для HTML-кода, а другими словами - массив атрибутов для тэга. В этом массиве ключи являются названиями атрибутов, например class, href или target, а значения в массиве являются значениями этих атрибутов.

Вышеприведённый код сформирует следующую HTML-разметку:

<p class="username">samdark</p>

В тех случаях, когда вам необходимо только закрыть или открыть тэг, можно использовать методы Html::beginTag() и Html::endTag().

Дополнительные атрибуты используются во многих методах Html-помощника и в различных виджетах. Во всех этих случаях в дело вступают механизмы дополнительной обработки данных, о которых следует знать:

• Если значение равно null, соответствующий атрибут не будет выведен.
• Атрибуты, значения которых имеют тип boolean, будут интерпретированы как логические атрибуты.
• Значения атрибутов будут экранированы с использованием метода Html::encode().

• Если в качестве значения атрибута передан массив, он будет обработан следующим образом:

  • Если атрибут является одним из атрибутов данных, указанных в yii\helpers\Html::$dataAttributes, например data или ng, то будет сформирован список атрибутов по одному для каждого элемента массива. Например, код 'data' => ['id' => 1, 'name' => 'yii'] сформирует data-id="1" data-name="yii"; а код 'data' => ['params' => ['id' => 1, 'name' => 'yii'], 'status' => 'ok'] сформирует data-params='{"id":1,"name":"yii"}' data-status="ok". Заметьте, что в последнем примере используется формат JSON для формирования вывода вложенного массива.

  • Если атрибут НЕ является атрибутом данных, значение будет сконвертировано в формат JSON. Например, код ['params' => ['id' => 1, 'name' => 'yii'] сформирует params='{"id":1,"name":"yii"}'.

Формирование CSS классов и стилей ¶

При формировании атрибутов для HTML-тэгов часто приходится начинать с некоторых атрибутов по умолчанию, которые затем необходимо изменять. Для того, чтобы добавить или удалить CSS-класс, можно использовать следующий подход:

$options = ['class' => 'btn btn-default'];

if ($type === 'success') {
    Html::removeCssClass($options, 'btn-default');
    Html::addCssClass($options, 'btn-success');
}

echo Html::tag('div', 'Всё получилось!', $options);

// в случае, если $type содержит строку 'success', будет сформирован вывод
// <div class="btn btn-success">Всё получилось!</div>

Можно указать несколько CSS-классов, используя синтаксис массива:

$options = ['class' => ['btn', 'btn-default']];

echo Html::tag('div', 'Сохранить', $options);
// выведет '<div class="btn btn-default">Сохранить</div>'

При добавлении или удалении классов тоже можно использовать массивы:

$options = ['class' => 'btn'];

if ($type === 'success') {
    Html::addCssClass($options, ['btn-success', 'btn-lg']);
}

echo Html::tag('div', 'Сохранить', $options);
// выведет '<div class="btn btn-success btn-lg">Сохранить</div>'

Html::addCssClass() предотвращает дублирование классов, поэтому можно не беспокоиться, что какой-либо класс будет добавлен дважды:

$options = ['class' => 'btn btn-default'];

Html::addCssClass($options, 'btn-default'); // класс 'btn-default' уже добавлен

echo Html::tag('div', 'Сохранить', $options);
// выведет '<div class="btn btn-default">Сохранить</div>'

Если CSS-класс задаётся с помощью массива, можно использовать именованные ключи массива для обозначения логического предназначения класса. В этом случае класс с таким же ключом будет проигнорирован во время использования Html::addCssClass():

$options = [
    'class' => [
        'btn',
        'theme' => 'btn-default',
    ]
];

Html::addCssClass($options, ['theme' => 'btn-success']); // ключ 'theme' уже использован

echo Html::tag('div', 'Сохранить', $options);
// отобразит '<div class="btn btn-default">Сохранить</div>'

CSS-стили могут быть установлены схожим образом с помощью атрибута style:

$options = ['style' => ['width' => '100px', 'height' => '100px']];

// в результате будет style="width: 100px; height: 200px; position: absolute;"
Html::addCssStyle($options, 'height: 200px; position: absolute;');

// в результате будет style="position: absolute;"
Html::removeCssStyle($options, ['width', 'height']);

При использовании метода addCssStyle() можно указать массив, пары ключ-значение которого соответствуют названиям и значениям CSS-свойств, или строку, например width: 100px; height: 200px;. Эти два формата могут быть преобразованы друг в друга с помощью методов cssStyleFromArray() и cssStyleToArray(). Метод removeCssStyle() принимает на вход массив атрибутов, которые следует удалить. Если удаляется всего один атрибут, его можно передать строкой.

Экранирование контента ¶

Для корректного и безопасного отображения контента специальные символы в HTML-коде должны быть экранированы. В чистом PHP это осуществляется с помощью функций htmlspecialchars и htmlspecialchars_decode. Проблема использования этих функций заключается в том, что приходится указывать кодировку и дополнительные флаги во время каждого вызова. Поскольку флаги всё время одинаковы, а кодировка остаётся одной и той же в пределах приложения, Yii в целях безопасности предоставляет два компактных и простых в использовании метода:

$userName = Html::encode($user->name);
echo $userName;

$decodedUserName = Html::decode($userName);

Формы ¶

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

Примечание: Рассмотрите возможность использования ActiveForm, если работаете с моделями и нуждаетесь в валидации данных.

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

Открывающий тэг формы может быть выведен с помощью метода beginForm() как показано ниже:

<?= Html::beginForm(['order/update', 'id' => $id], 'post', ['enctype' => 'multipart/form-data']) ?>

Первый аргумент - это URL-адрес, на который будет отправлена форма. Он может быть задан в виде Yii-маршрута и параметров, подходящих для передачи в метод Url::to(). Второй аргумент - способ отправки данных: по умолчанию это post. Третий аргумент - массив атрибутов формы. В данном примере мы изменяем способ кодирования данных в POST-запросе на multipart/form-data. Это необходимо для загрузки файлов.

Закрыть тэг формы можно простым кодом:

<?= Html::endForm() ?>

Кнопки ¶

Для формирования кнопок можно использовать следующий код:

<?= Html::button('Нажми меня!', ['class' => 'teaser']) ?>
<?= Html::submitButton('Отправить', ['class' => 'submit']) ?>
<?= Html::resetButton('Сбросить', ['class' => 'reset']) ?>

Первый аргумент во всех трёх методах - это название кнопки, а второй - её атрибуты. Название кнопки не экранируется, поэтому при получении данных от конечных пользователей экранируйте их с помощью метода Html::encode().

Поля ввода ¶

Методы формирования полей ввода делятся на две группы. Первые начинаются со слова active и называются "active inputs", а вторые не содержат в своём названии слова active. "Active inputs" формируют поля ввода, которые получают данные из указанного атрибута модели, в то время как обычные методы формирования полей ввода непосредственно принимают данные.

Наиболее общие методы для формирования полей ввода:

// тип, название поля ввода, установленное в поле значение, атрибуты поля ввода
<?= Html::input('text', 'username', $user->name, ['class' => $username]) ?>

// тип, модель, атрибут модели, атрибуты поля ввода
<?= Html::activeInput('text', $user, 'name', ['class' => $username]) ?>

Если вам заранее известен тип поля ввода, удобнее будет пользоваться этими вспомогательными методами:

• yii\helpers\Html::buttonInput()
• yii\helpers\Html::submitInput()
• yii\helpers\Html::resetInput()
• yii\helpers\Html::textInput(), yii\helpers\Html::activeTextInput()
• yii\helpers\Html::hiddenInput(), yii\helpers\Html::activeHiddenInput()
• yii\helpers\Html::passwordInput() / yii\helpers\Html::activePasswordInput()
• yii\helpers\Html::fileInput(), yii\helpers\Html::activeFileInput()
• yii\helpers\Html::textarea(), yii\helpers\Html::activeTextarea()

Сигнатура методов для формирования радио-переключателей и чекбоксов немного отличается:

<?= Html::radio('agree', true, ['label' => 'Я согласен']) ?>
<?= Html::activeRadio($model, 'agree', ['class' => 'agreement']) ?>

<?= Html::checkbox('agree', true, ['label' => 'Я согласен']) ?>
<?= Html::activeCheckbox($model, 'agree', ['class' => 'agreement']) ?>

Выпадающие и обычные списки могут быть сформированы следующим образом:

<?= Html::dropDownList('list', $currentUserId, ArrayHelper::map($userModels, 'id', 'name')) ?>
<?= Html::activeDropDownList($users, 'id', ArrayHelper::map($userModels, 'id', 'name')) ?>

<?= Html::listBox('list', $currentUserId, ArrayHelper::map($userModels, 'id', 'name')) ?>
<?= Html::activeListBox($users, 'id', ArrayHelper::map($userModels, 'id', 'name')) ?>

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

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

<?= Html::checkboxList('roles', [16, 42], ArrayHelper::map($roleModels, 'id', 'name')) ?>
<?= Html::activeCheckboxList($user, 'role', ArrayHelper::map($roleModels, 'id', 'name')) ?>

Если нет, используйте радио-переключатель:

<?= Html::radioList('roles', [16, 42], ArrayHelper::map($roleModels, 'id', 'name')) ?>
<?= Html::activeRadioList($user, 'role', ArrayHelper::map($roleModels, 'id', 'name')) ?>

Тэги label и отображение ошибок ¶

Так же как и для полей ввода, есть два метода формирования тэгов label для форм. Есть "active label", считывающий данные из модели и обычный тэг "label", принимающий на вход непосредственно сами данные:

<?= Html::label('Имя пользователя', 'username', ['class' => 'label username']) ?>
<?= Html::activeLabel($user, 'username', ['class' => 'label username'])

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

<?= Html::errorSummary($posts, ['class' => 'errors']) ?>

Для отображения одной отдельной ошибки:

<?= Html::error($post, 'title', ['class' => 'error']) ?>

Атрибуты name и value для полей ввода ¶

Также имеются методы для получения значений атрибутов id, name и value для полей ввода, сформированных на основе моделей. Эти методы используются в основном внутренними механизмами, но иногда могут оказаться подходящими и для прямого использования:

// Post[title]
echo Html::getInputName($post, 'title');

// post-title
echo Html::getInputId($post, 'title');

// моё первое сообщение
echo Html::getAttributeValue($post, 'title');

// $post->authors[0]
echo Html::getAttributeValue($post, '[0]authors[0]');

В вышеприведённом коде первый аргумент - это модель, а второй аргумент - выражение для поиска атрибута модели. В самом простом случае оно представляет собой название атрибута модели, а вообще это может быть название, которому предшествует (и/или после которого следует) индекс массива. Такой формат используется в основном для табличного ввода данных:

• [0]content используется для табличного ввода данных, чтобы указать на атрибут "content" первой модели табличного ввода;
• dates[0] указывает на первый элемент массива, с помощью которого задан атрибут модели "dates";
• [0]dates[0] указывает на первый элемент массива, с помощью которого задан атрибут "dates" первой модели табличного ввода.

Для того, чтобы получить название атрибута модели в чистом виде (без суффиксов и префиксов), можно использовать следующий подход:

// dates
echo Html::getAttributeName('dates[0]');

Подключение встроенных стилей и скриптов ¶

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

<?= Html::style('.danger { color: #f00; }', ['media' => 'print']) ?>

Результатом будет:

<style media="print">.danger { color: #f00; }</style>


<?= Html::script('alert("Привет!");') ?>

Результатом будет:

<script>alert("Привет!");</script>

Если вы хотите подключить внешний CSS-файл:

<?= Html::cssFile('@web/css/ie5.css', ['condition' => 'IE 5']) ?>

В результате получится:

<!--[if IE 5]>
    <link href="https://example.com/css/ie5.css" />
<![endif]-->

Первый аргумент - URL-адрес. Второй - массив настроек. Помимо обычных настроек можно указать следующие:

• condition для оборачивания тэга <link с помощью условных комментариев с определённым условием. Надеемся, что вам никогда не понадобятся условные комментарии ;)
• noscript может быть установлен в значение true, чтобы обернуть тэг <link с помощью тэга <noscript>, таким образом скрипт будет подключён только в том случае, если у пользователя в браузере нет поддержки JavaScript или же пользователь сам отключил его.

Для подключения JavaScript-файла используйте код:

<?= Html::jsFile('@web/js/main.js') ?>

Как и в случае с CSS, первый аргумент указывает ссылку на файл, который должен быть подключен. Настройки задаются во втором аргументе. Можно указать настройку condition таким же образом, каким она указывается для метода cssFile.

Ссылки ¶

Существует удобный метод формирования ссылок:

<?= Html::a('Профиль', ['user/view', 'id' => $id], ['class' => 'profile-link']) ?>

Первый аргумент - это текст ссылки. Он не экранируется, поэтому при использовании данных, полученных от конечных пользователей, необходимо экранировать его с помощью Html::encode(). Второй аргумент - это содержимое атрибута href тэга <a. Смотрите Url::to() для получения подробностей относительно значений, которые могут быть переданы в качестве второго аргумента. Третий аргумент - массив атрибутов для тэга.

Если нужно сформировать ссылку mailto, можно использовать следующий подход:

<?= Html::mailto('Обратная связь', 'admin@example.com') ?>

Изображения ¶

Для формирования тэга изображения используйте следующий код:

<?= Html::img('@web/images/logo.png', ['alt' => 'Наш логотип']) ?>

в результате получится:

<img src="https://example.com/images/logo.png" alt="Наш логотип" />

Помимо псевдонимов первый аргумент может принимать маршруты, параметры и URL-адреса таким же образом как и метод Url::to().

Списки ¶

Неупорядоченные списки могут быть сформированы следующим образом:

<?= Html::ul($posts, ['item' => function($item, $index) {
    return Html::tag(
        'li',
        $this->render('post', ['item' => $item]),
        ['class' => 'post']
    );
}]) ?>

Для формирования упорядоченных списков используйте Html::ol().