Htmlヘルパー ¶

すべてのWebアプリケーションは大量のHTMLマークアップを生成します。マークアップが静的な場合、PHPとHTMLを単一ファイルで混在させることで効率的に実行できますが、動的に生成される場合、追加のヘルプなしに処理することは難しくなります。Yiiは、一般的に使用されるHTMLタグ、そのオプション、およびそのコンテンツを処理するための静的メソッドのセットを提供するHtmlヘルパーという形で、そのようなヘルプを提供します。

注記: マークアップがほぼ静的な場合は、HTMLを直接使用することをお勧めします。すべてをHtmlヘルパーの呼び出しでラップする必要はありません。

基本 ¶

文字列連結による動的HTMLの構築は非常に速く複雑になる可能性があるため、Yiiはタグオプションを操作し、これらのオプションに基づいてタグを構築するためのメソッドのセットを提供します。

タグの生成 ¶

タグを生成するためのコードは次のようになります。

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

最初の引数はタグ名です。2番目の引数は、開始タグと終了タグの間に囲まれるコンテンツです。必要に応じてHTMLを使用できるように、コンテンツは自動的にエンコードされないため、Html::encodeを使用していることに注意してください。3番目の引数は、HTMLオプション、つまりタグ属性の配列です。この配列では、キーは属性の名前（class、href、targetなど）、値はその値です。

上記のコードは、次のHTMLを生成します。

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

開始タグまたは終了タグのみが必要な場合は、Html::beginTag()メソッドとHtml::endTag()メソッドを使用できます。

オプションは、Htmlヘルパーの多くのメソッドやさまざまなウィジェットで使用されます。これらのすべての場合、考慮すべき追加の処理があります。

• 値がnullの場合、対応する属性はレンダリングされません。
• 値がブール型の属性は、ブール属性として扱われます。
• 属性の値は、Html::encode()を使用してHTMLエンコードされます。

• 属性の値が配列の場合、次のようになります。

  • 属性がyii\helpers\Html::$dataAttributesにリストされているデータ属性（`data`や`ng`など）の場合、値の配列の各要素に対して1つずつ属性がレンダリングされます。たとえば、`'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()は重複を防ぐため、同じクラスが2回出現する心配はありません。

$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は2つのコンパクトで使いやすいメソッドを提供します。

$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です。Url::to()で受け入れられるYiiルートとパラメータの形式で指定できます。2番目の引数は使用するメソッドです。`post`がデフォルトです。3番目の引数は、フォームタグのオプションの配列です。この例では、POSTリクエストでフォームデータのエンコーディングを`multipart/form-data`に変更しています。これは、ファイルをアップロードするために必要です。

フォームタグの閉じ方は簡単です。

<?= Html::endForm() ?>

ボタン ¶

ボタンを生成するには、次のコードを使用できます。

<?= Html::button('Press me!', ['class' => 'teaser']) ?>
<?= Html::submitButton('Submit', ['class' => 'submit']) ?>
<?= Html::resetButton('Reset', ['class' => 'reset']) ?>

3つのメソッドすべてに対する最初の引数はボタンのタイトル、2番目の引数はオプションの配列です。タイトルはエンコードされないため、エンドユーザーからのデータを表示する場合は、Html::encode()でエンコードしてください。

入力フィールド ¶

入力メソッドには2つのグループがあります。`active`で始まるもの（アクティブ入力と呼ばれる）と、`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')) ?>

最初の引数は入力の名前、2番目の引数は現在選択されている値、3番目の引数はキーと値のペアの配列です。ここで、配列キーはリストの値、配列値はリストのラベルです。

複数の選択肢を選択可能にしたい場合は、チェックボックスリストを使用できます。

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

ラベルとエラー ¶

入力と同様に、フォームラベルを生成するための2つのメソッドがあります。モデルからデータを取得するアクティブなメソッドと、データを直接受け入れる非アクティブなメソッドです。

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

入力名と値 ¶

モデルに基づいて入力フィールドの名前、ID、値を取得するためのメソッドがあります。これらは主に内部的に使用されますが、場合によっては便利になることもあります。

// 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]');

上記では、最初の引数はモデル、2番目の引数は属性式です。最も単純な形式では、式は単なる属性名ですが、配列インデックスを接頭辞または接尾辞として付けた属性名にすることもできます。これは主に表形式の入力に使用されます。

• `[0]content`は、表形式のデータ入力において、表形式の入力の最初のモデルの`content`属性を表すために使用されます。
• `dates[0]`は、`dates`属性の最初の配列要素を表します。
• `[0]dates[0]`は、表形式の入力の最初のモデルの`dates`属性の最初の配列要素を表します。

接頭辞または接尾辞のない属性名を取得するには、次を使用できます。

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

スタイルとスクリプト ¶

埋め込まれたスタイルとスクリプトをラップするタグを生成するための2つのメソッドがあります。

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

Gives you

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


<?= Html::script('alert("Hello!");') ?>

Gives you

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

CSSファイルで外部スタイルを使用する場合は

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

generates

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

最初の引数はURLです。2番目の引数はオプションの配列です。通常のオプションに加えて、次を指定できます。

• `condition`は、指定された条件で条件付きコメントに``をラップするために使用します。条件付きコメントが必要になることはほとんどないでしょう;)
• `noscript`を`true`に設定すると、``が`

JavaScriptファイルへのリンク

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

CSSと同様に、最初の引数には、含めるファイルのURLを指定します。オプションは2番目の引数として渡すことができます。オプションでは、`cssFile`のオプションと同様に`condition`を指定できます。

ハイパーリンク ¶

ハイパーリンクを簡単に生成するためのメソッドがあります。

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

最初の引数はタイトルです。エンコードされないため、ユーザーが入力したデータを使用する場合は、`Html::encode()`でエンコードする必要があります。2番目の引数は、``タグの`href`属性に含まれるものです。Url::to()で、どのような値を受け入れるかを確認してください。3番目の引数は、タグ属性の配列です。

`mailto`リンクを生成する必要がある場合は、次のコードを使用できます。

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

画像 ¶

イメージタグを生成するには、次を使用します。

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

generates

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

エイリアスに加えて、最初の引数は、Url::to()と同様に、ルート、パラメータ、URLを受け入れることができます。

リスト ¶

順序なしリストは、次のように生成できます。

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

順序付きリストを取得するには、代わりに`Html::ol()`を使用します。