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, соответствующий атрибут не будет отображён.
• Атрибуты, значения которых имеют булевый тип, будут обрабатываться как булевые атрибуты.
• Значения атрибутов будут HTML-кодироваться с помощью 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', 'Pwede na', $options);

// if the value of $type is 'success' it will render
// <div class="btn btn-success">Pwede na</div>

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

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

echo Html::tag('div', 'Save', $options);
// renders '<div class="btn btn-default">Save</div>'

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

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

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

echo Html::tag('div', 'Save', $options);
// renders '<div class="btn btn-success btn-lg">Save</div>'

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

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

Html::addCssClass($options, 'btn-default'); // class 'btn-default' is already present

echo Html::tag('div', 'Save', $options);
// renders '<div class="btn btn-default">Save</div>'

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

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

Html::addCssClass($options, ['theme' => 'btn-success']); // 'theme' key is already taken

echo Html::tag('div', 'Save', $options);
// renders '<div class="btn btn-default">Save</div>'

CSS-стили можно задать аналогичным образом, используя атрибут style:

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

// gives style="width: 100px; height: 200px; position: absolute;"
Html::addCssStyle($options, 'height: 200px; position: absolute;');

// gives 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('Press me!', ['class' => 'teaser']) ?>
<?= Html::submitButton('Submit', ['class' => 'submit']) ?>
<?= Html::resetButton('Reset', ['class' => 'reset']) ?>

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

Поля ввода

Существует две группы методов ввода. Те, которые начинаются с active, называемые активными полями ввода, и те, которые не начинаются с него. Активные поля ввода берут данные из указанной модели и атрибута, в то время как в случае обычного поля ввода данные указываются напрямую.

Наиболее универсальные методы:

type, input name, input value, options
<?= Html::input('text', 'username', $user->name, ['class' => $username]) ?>

type, model, model attribute name, options
<?= 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' => 'I agree']);
<?= Html::activeRadio($model, 'agree', ['class' => 'agreement'])

<?= Html::checkbox('agree', true, ['label' => 'I agree']);
<?= 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')) ?>

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

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

<?= 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')) ?>

Метки и ошибки

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

<?= Html::label('User name', 'username', ['class' => 'label username']) ?>
<?= Html::activeLabel($user, 'username', ['class' => 'label username']) ?>

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

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

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

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

Имена и значения полей ввода

Есть методы для получения имён, идентификаторов и значений полей ввода на основе модели. Они в основном используются во внутреннем коде, но иногда могут быть полезны:

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

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

// my first post
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; }') ?>

Gives you

<style>.danger { color: #f00; }</style>


<?= Html::script('alert("Hello!");', ['defer' => true]);

Gives you

<script defer>alert("Hello!");</script>

Если вы хотите использовать внешний стиль в файле CSS:

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

generates

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

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

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

Для ссылки на файл JavaScript:

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

Так же, как и с CSS, первый аргумент указывает URL включаемого файла. Опции можно передать во втором аргументе. В опциях вы можете указать condition так же, как и в опциях для cssFile.

Гиперссылки

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

<?= Html::a('Profile', ['user/view', 'id' => $id], ['class' => 'profile-link']) ?>

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

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

<?= Html::mailto('Contact us', 'admin@example.com') ?>

Изображения

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

<?= Html::img('@web/images/logo.png', ['alt' => 'My logo']) ?>

generates

<img src="http://example.com/images/logo.png" alt="My logo" />

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

Списки

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

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

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