CakePHP における HtmlHelper の役割は、 HTML に関連するオプションを より簡単、高速に作成し、より弾力的なものに変えることです。 このヘルパーを使うことで、アプリケーションの足どりはより軽くなり、 そしてドメインのルートが置かれている場所に関して、よりフレキシブル なものになるでしょう。
HtmlHelper にある多くのメソッドは $htmlAttributes という 引数を持っています。これにより、いかなる追加属性もタグに 付け加えることができます。これは $htmlAttributes を使う 方法についての簡単な例です。
付けられる属性: <tag class="someClass" />
配列での指定: array('class' => 'someClass')
付けられる属性: <tag name="foo" value="bar" />
配列での指定: array('name' => 'foo', 'value' => 'bar')
ノート
HtmlHelpler は既定ではすべてのビューで使うことができます。 このヘルパーが存在しないという旨のエラーが発生したとき、 たいていの原因はコントローラーで変数 $helpers を手動で 設定した際、名前を書き忘れたことです。
HtmlHelper の果たすもっとも重要なタスクは、適切に定義された マークアップの生成です。 CakePHP はレンダリングと送信にかかる CPU のサイクルを減らすために、ビューをキャッシュすることが できます。この節では、いくつかのHtmlHelperのメソッドと、その 使用方法について説明します。
パラメタ: |
|
---|
HTML 文書の文字セットを特定する meta タグを作成するために使います。 既定では UTF-8 になります。
使用例:
echo $this->Html->charset();
出力結果
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
このように使うと:
echo $this->Html->charset('ISO-8859-1');
以下のようになります。:
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
パラメタ: |
|
---|
CSS のスタイルシートの link タグを生成します。 $options パラメータのキー ‘inline’ を false に設定すると link タグは HTML文書の head タグ内にある css ブロック に追加されます。
block オプションを使用することで、 link タグが追加されるブロックを制御できます。 既定では css ブロックに追加されます。
/app/webroot/css ディレクトリ以下にある特定の CSS ファイルをインクルードするには 以下のようにします。:
echo $this->Html->css('forms');
このコードの出力は以下のようになります。
<link rel="stylesheet" type="text/css" href="/css/forms.css" />
最初の引数は複数のファイルをインクルードするために配列を使用できます。:
echo $this->Html->css(array('forms', 'tables', 'menu'));
上の例は以下のようになります。
<link rel="stylesheet" type="text/css" href="/css/forms.css" />
<link rel="stylesheet" type="text/css" href="/css/tables.css" />
<link rel="stylesheet" type="text/css" href="/css/menu.css" />
ロードしたプラグインからも plugin syntax を使うことで CSS ファイルを インクルードすることができます。 app/Plugin/DebugKit/webroot/css/toolbar.css という CSS ファイルをインクルードするには以下のようにします。:
echo $this->Html->css('DebugKit.toolbar.css');
ロードしたプラグインと名前が共通する CSS ファイルをインクルードするときは 次のようにします。たとえば Blog プラグインを使っているときに、 app/webroot/css/Blog.common.css をインクルードしたい場合は以下のようにします。:
echo $this->Html->css('Blog.common.css', null, array('plugin' => false));
バージョン 2.1 で変更: block オプションが追加されました。 plugin syntax のサポートが追加されました。
パラメタ: |
|
---|
このメソッドは、 RSS または Atom フィードや、 favicon といった外部リソースとリンクする際に有用です。 css() メソッド同様、 array('inline' => false) という風に $attributes の ‘inline’ というキーに false を設定することで、タグをインラインで出力するか meta ブロックに追加するかを 指定することができます。
$attributes のパラメータを使って “type” 属性を設定するとき、 CakePHP では 少しですがショートカットを用意しています。
typeの値 | 変換後の値 |
---|---|
html | text/html |
rss | application/rss+xml |
atom | application/atom+xml |
icon | image/x-icon |
<?php
echo $this->Html->meta(
'favicon.ico',
'/favicon.ico',
array('type' => 'icon')
);
?>
// 出力結果(改行を追加しています)
<link
href="http://example.com/favicon.ico"
title="favicon.ico" type="image/x-icon"
rel="alternate"
/>
<?php
echo $this->Html->meta(
'Comments',
'/comments/index.rss',
array('type' => 'rss')
);
?>
// 出力結果(改行を追加しています)
<link
href="http://example.com/comments/index.rss"
title="Comments"
type="application/rss+xml"
rel="alternate"
/>
このメソッドは meta キーワードと種類を記述することもできます。 以下に例を示します。
<?php
echo $this->Html->meta(
'keywords',
'ここに meta キーワードを書き込む'
);
?>
// 出力結果
<meta name="keywords" content="ここに meta キーワードを書き込む" />
<?php
echo $this->Html->meta(
'description',
'ここに何か説明を書き込む'
);
?>
// 出力結果
<meta name="description" content="ここに何か説明を書き込む" />
独自の meta タグを出力するときは、配列を最初の引数として渡します。 クローラにインデックスを作成させないよう指定するタグを出力する例を 以下に示します。:
echo $this->Html->meta(array('name' => 'robots', 'content' => 'noindex'));
バージョン 2.1 で変更: block オプションが追加されました。
パラメタ: |
|
---|
(X)HTML の DOCTYPE タグを出力します。 以下は指定できる値と その結果をまとめた表です。
$type の値 | 出力されるタグの種類 |
---|---|
html4-strict | HTML4 Strict |
html4-trans | HTML4 Transitional |
html4-frame | HTML4 Frameset |
html5 | HTML5 |
xhtml-strict | XHTML1 Strict |
xhtml-trans | XHTML1 Transitional |
xhtml-frame | XHTML1 Frameset |
xhtml11 | XHTML1.1 |
echo $this->Html->docType();
// 出力結果: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
echo $this->Html->docType('html5');
// 出力結果: <!DOCTYPE html>
echo $this->Html->docType('html4-trans');
// 出力結果: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
バージョン 2.1 で変更: 2.1では既定で出力される DOCTYPE タグが HTML5 のものになりました。
パラメタ: |
|
---|
メソッドに渡した配列のキーと値から CSS のスタイル定義を作成します。 特に動的な CSS の作成に有用です。:
echo $this->Html->style(array(
'background' => '#633',
'border-bottom' => '1px solid #000',
'padding' => '10px'
));
出力は以下のようになります。:
background:#633; border-bottom:1px solid #000; padding:10px;
パラメタ: |
|
---|
書式にのっとった image タグを作成します。画像のパスは /app/webroot/img/ からの相対パスを指定してください。:
echo $this->Html->image('cake_logo.png', array('alt' => 'CakePHP'));
出力は以下のとおりです。
<img src="/img/cake_logo.png" alt="CakePHP" />
リンク付き画像を作成するには、リンク先を $htmlAttributes の url オプションに設定します。:
echo $this->Html->image("recipes/6.jpg", array(
"alt" => "ブラウニー",
'url' => array('controller' => 'recipes', 'action' => 'view', 6)
));
出力は以下のとおりです。
<a href="/recipes/view/6">
<img src="/img/recipes/6.jpg" alt="ブラウニー" />
</a>
電子メールで画像を使用したいときや、絶対パスで画像を指定したいときは fullBase オプションを設定します。:
echo $this->Html->image("logo.png", array('fullBase' => true));
出力は以下のとおりです。
<img src="http://example.com/img/logo.jpg" alt="" />
plugin syntax を使うことで、ロードしたプラグインの画像を インクルードできます。 app/Plugin/DebugKit/webroot/img/icon.png をインクルードするには以下のようにします。:
echo $this->Html->image('DebugKit.icon.png');
ロードしたプラグインと名前が共通する画像をインクルードするときは 次のようにします。たとえば Blog プラグインを使っているときに、 app/webroot/js/Blog.icon.png をインクルードしたい場合は次のようにします。:
echo $this->Html->image('Blog.icon.png', array('plugin' => false));
バージョン 2.1 で変更: fullBase オプションが追加されました。 plugin syntax のサポートが追加されました。
パラメタ: |
|
---|
一般的な HTML のハイパーリンクを作成するためのメソッドです。 $options は、タグの属性や、 $title をエスケープするかどうかの設定に使います。:
echo $this->Html->link('Enter', '/pages/home', array('class' => 'button', 'target' => '_blank'));
出力は以下のようになります。
<a href="/pages/home" class="button" target="_blank">Enter</a>
'full_base'=>true オプションを設定すると、URLをフルパスで出力します。:
echo $this->Html->link(
'Dashboard',
array('controller' => 'dashboards', 'action' => 'index', 'full_base' => true)
);
出力は以下のようになります。
<a href="http://www.yourdomain.com/dashboards/index">Dashboard</a>
$confirmMessage を指定すると、JavaScript の confirm() で表示するダイアログのメッセージを設定できます。:
echo $this->Html->link(
'削除',
array('controller' => 'recipes', 'action' => 'delete', 6),
array(),
"本当にこのレシピを削除しますか?"
);
結果は以下の通りです。
<a href="/recipes/delete/6" onclick="return confirm('本当にこのレシピを削除しますか?');">削除</a>
クエリ文字列も link() で作成できます。:
echo $this->Html->link('画像を表示する', array(
'controller' => 'images',
'action' => 'view',
1,
'?' => array('height' => 400, 'width' => 500))
);
結果は以下の通りです。
<a href="/images/view/1?height=400&width=500">画像を表示する</a>
HTML で特殊な意味を持つ文字が $title に含まれていた場合は、 HTML エンティティに変換されます。これを無効にするには、 $options 配列の escape オプションに false を設定します。:
<?php
echo $this->Html->link(
$this->Html->image("recipes/6.jpg", array("alt" => "Brownies")),
"recipes/view/6",
array('escape' => false)
);
出力は以下のようになります。
<a href="/recipes/view/6">
<img src="/img/recipes/6.jpg" alt="Brownies" />
</a>
そのほかの種類のURLについては、 HtmlHelper::url メソッドの項目も参考にしてください。
パラメタ: |
|
---|
バージョン 2.1 で追加.
フォーマットされた audio/video タグを返します。
<?php echo $this->Html->media('audio.mp3'); ?>
// 出力結果
<audio src="/files/audio.mp3"></audio>
<?php echo $this->Html->media('video.mp4', array(
'fullBase' => true,
'text' => 'Fallback text'
)); ?>
// 出力結果
<video src="http://www.somehost.com/files/video.mp4">Fallback text</video>
<?php echo $this->Html->media(
array('video.mp4', array('src' => 'video.ogg', 'type' => "video/ogg; codecs='theora, vorbis'")),
array('autoplay')
); ?>
// 出力結果
<video autoplay="autoplay">
<source src="/files/video.mp4" type="video/mp4"/>
<source src="/files/video.ogg" type="video/ogg; codecs='theora, vorbis'"/>
</video>
パラメタ: |
|
---|
text を囲った tag 指定したタグを返します。textを指定しなかった場合、 <tag> という開始タグのみを返します。
<?php
echo $this->Html->tag('span', 'Hello World.', array('class' => 'welcome'));
?>
// 出力結果
<span class="welcome">Hello World</span>
// text を指定しなかった場合です。
<?php
echo $this->Html->tag('span', null, array('class' => 'welcome'));
?>
// 出力結果
<span class="welcome">
ノート
text は既定ではエスケープされませんが、 $htmlOptions['escape'] = true と設定することでエスケープすることができます。 以前のバージョンでは、4つ目の引数に boolean $escape = false と設定することで行います。
パラメタ: |
|
---|
div タグで囲ったセクションを作成するために使います。最初の引数で CSS のクラスを設定し、次の引数でdivタグで囲うテキストを設定します。 最後の引数を true に設定すると、 $text をエスケープされた HTML で出力します。
text を指定しなかった場合は開始タグのみを返します。
<?php
echo $this->Html->div('error', 'Please enter your credit card number.');
?>
// 出力結果
<div class="error">Please enter your credit card number.</div>
パラメタ: |
|
---|
text を含め、 CSS のクラスを指定した <p> タグを出力します。 text に何も指定しなかった場合は <p> の開始タグのみを出力します。
<?php
echo $this->Html->para(null, 'Hello World.');
?>
// 出力結果
<p>Hello World.</p>
パラメタ: |
|
---|
ローカルファイルまたは URL で指定したリモートファイルをインクルードします。
デフォルトでは、ドキュメントのインラインに script タグが追加されます。 この動きは $options['inline'] を false にすることで抑制することができ、 ドキュメント内にある他の script ブロック内に追加します。 もし、他のブロックへ出力したい場合は、 $options['block'] を指定すると変更可能です。
$options['once'] は、一回のリクエストで一度だけの読み込みにするか、 何度も読み込みをするかを制御します。デフォルトは true です。
$options を使って、生成する script タグの属性を設定することができます。 この設定は、配列を使ってファイルを指定した場合、 生成されるすべての script タグに適用されます。
このメソッドは、指定された JavaScript ファイルが /app/webroot/js というディレクトリにあると仮定して動作します。:
echo $this->Html->script('scripts');
結果は以下の通りです。
<script type="text/javascript" href="/js/scripts.js"></script>
app/webroot/js にないファイルをリンクする際は絶対パスを指定します。:
echo $this->Html->script('/otherdir/script_file');
リモート URL のリンクを指定することもできます。:
echo $this->Html->script('http://code.jquery.com/jquery.min.js');
結果は以下の通りです。
<script type="text/javascript" href="http://code.jquery.com/jquery.min.js"></script>
最初の引数を複数のファイル名を含む配列にすることもできます。:
echo $this->Html->script(array('jquery', 'wysiwyg', 'scripts'));
結果は以下の通りです。
<script type="text/javascript" href="/js/jquery.js"></script>
<script type="text/javascript" href="/js/wysiwyg.js"></script>
<script type="text/javascript" href="/js/scripts.js"></script>
特定の script ブロックにタグを追加したい場合は block オプションを指定します。
echo $this->Html->script('wysiwyg', array('block' => 'scriptBottom'));
レイアウトで以下のように記述すると、すべての script タグを ‘scriptBottom’ に出力することができます。:
echo $this->fetch('scriptBottom');
plugin syntax を使うことにより、ロードしたプラグインのスクリプトを 使うことができます。 app/Plugin/DebugKit/webroot/js/toolbar.js を インクルードするには以下のようにします。:
echo $this->Html->script('DebugKit.toolbar.js');
ロードしたプラグインと名前を共有するスクリプトファイルは、以下のようにすると インクルードできます。たとえば Blog プラグインを使用しているときに app/webroot/js/Blog.plugins.js をインクルードするには以下のようにします。:
echo $this->Html->script('Blog.plugins.js', array('plugin' => false));
バージョン 2.1 で変更: block オプションが追加されました。 plugin syntax のサポートが追加されました。
パラメタ: |
|
---|
$code を含めた <script> タグを生成します。 $options['inline'] を false 設定すると、コードブロックはビューブロックの script に置かれます。 そのほかのオプションは script タグの属性として追加されます。 たとえば、 $this->Html->scriptBlock('stuff', array('defer' => true)); とすると、 defer="defer" という属性を持った script タグを生成します。
パラメタ: |
|
---|
コードブロックのバッファリングを始めます。コードブロックは scriptStart() と scriptEnd() の間にあるすべてのコードをキャプチャーし、 ひとつの script タグを生成します。オプションは scriptBlock() のものと同様です。
コードブロックのバッファリングを終了し、生成した script 要素を 出力します。コードブロックをオープンする際、 inline => false としていた場合は nullを返します。
scriptStart() と scriptEnd() の使用例を示します。:
$this->Html->scriptStart(array('inline' => false));
echo $this->Js->alert('I am in the javascript');
$this->Html->scriptEnd();
パラメタ: |
|
---|
ネストしたリストを、連想配列から作成します。:
$list = array(
'Languages' => array(
'English' => array(
'American',
'Canadian',
'British',
),
'Spanish',
'German',
)
);
echo $this->Html->nestedList($list);
Output:
// 出力結果 (空白は省かれます)
<ul>
<li>Languages
<ul>
<li>English
<ul>
<li>American</li>
<li>Canadian</li>
<li>British</li>
</ul>
</li>
<li>Spanish</li>
<li>German</li>
</ul>
</li>
</ul>
パラメタ: |
|
---|
<table> タグ内に置くためのヘッダー行を作成します。:
echo $this->Html->tableHeaders(array('Date', 'Title', 'Active'));
結果は以下の通りです。
<tr>
<th>Date</th>
<th>Title</th>
<th>Active</th>
</tr>
echo $this->Html->tableHeaders(
array('Date','Title','Active'),
array('class' => 'status'),
array('class' => 'product_table')
);
結果は以下の通りです。
<tr class="status">
<th class="product_table">Date</th>
<th class="product_table">Title</th>
<th class="product_table">Active</th>
</tr>
バージョン 2.2 で変更: tableHeaders() はセルごとの属性を設定できます。以下をご覧ください。
バージョン 2.2 からは、カラムごとに属性を設定できます。 既定では $thOptions で設定した値が使われます。:
echo $this->Html->tableHeaders(array(
'id',
array('Name' => array('class' => 'highlight')),
array('Date' => array('class' => 'sortable'))
));
結果は以下の通りです。
<tr>
<th>id</th>
<th class="highlight">Name</th>
<th class="sortable">Date</th>
</tr>
パラメタ: |
|
---|
奇数行と偶数行で異なる属性を割り当てた表のセルを作成します。 array() でひとつのセルを囲うと、特定の <td> タグについて属性を 設定できます。:
echo $this->Html->tableCells(array(
array('Jul 7th, 2007', 'Best Brownies', 'Yes'),
array('Jun 21st, 2007', 'Smart Cookies', 'Yes'),
array('Aug 1st, 2006', 'Anti-Java Cake', 'No'),
));
Output:
<tr><td>Jul 7th, 2007</td><td>Best Brownies</td><td>Yes</td></tr>
<tr><td>Jun 21st, 2007</td><td>Smart Cookies</td><td>Yes</td></tr>
<tr><td>Aug 1st, 2006</td><td>Anti-Java Cake</td><td>No</td></tr>
echo $this->Html->tableCells(array(
array('Jul 7th, 2007', array('Best Brownies', array('class' => 'highlight')) , 'Yes'),
array('Jun 21st, 2007', 'Smart Cookies', 'Yes'),
array('Aug 1st, 2006', 'Anti-Java Cake', array('No', array('id' => 'special'))),
));
結果は以下の通りです。
<tr><td>Jul 7th, 2007</td><td class="highlight">Best Brownies</td><td>Yes</td></tr>
<tr><td>Jun 21st, 2007</td><td>Smart Cookies</td><td>Yes</td></tr>
<tr><td>Aug 1st, 2006</td><td>Anti-Java Cake</td><td id="special">No</td></tr>
echo $this->Html->tableCells(
array(
array('Red', 'Apple'),
array('Orange', 'Orange'),
array('Yellow', 'Banana'),
),
array('class' => 'darker')
);
結果は以下の通りです。
<tr class="darker"><td>Red</td><td>Apple</td></tr>
<tr><td>Orange</td><td>Orange</td></tr>
<tr class="darker"><td>Yellow</td><td>Banana</td></tr>
パラメタ: |
|
---|
コントローラーとアクションの組み合わせが指し示す URL を返します。 $url を指定しなかった場合は REQUEST_URI を、それ以外のときは コントローラーとアクションの組み合わせから URL を生成して出力します。 full に true を設定すると、出力結果に ドメイン名を追加します。:
echo $this->Html->url(array(
"controller" => "posts",
"action" => "view",
"bar"
));
// 出力結果
/posts/view/bar
以下に更なる使用例を示します。
名前付き引数と URL の指定:
echo $this->Html->url(array(
"controller" => "posts",
"action" => "view",
"foo" => "bar"
));
// 出力結果
/posts/view/foo:bar
拡張子つきの URL:
echo $this->Html->url(array(
"controller" => "posts",
"action" => "list",
"ext" => "rss"
));
// 出力結果
/posts/list.rss
ドメイン名を含めた ‘/’ で始まる URL:
echo $this->Html->url('/posts', true);
// 出力結果
http://somedomain.com/posts
GET パラメーターとアンカーつきの URL:
echo $this->Html->url(array(
"controller" => "posts",
"action" => "search",
"?" => array("foo" => "bar"),
"#" => "first"
));
// 出力結果
/posts/search?foo=bar#first
より詳しい情報は、API 集の Router::url を確認してください。
フォーマットされた既存の $tag のブロックを返します。:
$this->Html->useTag(
'form',
'http://example.com',
array('method' => 'post', 'class' => 'myform')
);
結果は以下の通りです。
<form action="http://example.com" method="post" class="myform">
HtmlHelper 組み込みのタグ設定は、 XH|TML に準拠したものです。 そのため、 HTML5 に準拠した HTML を生成するためには、新しいタグの設定を 作成して読み込む必要があります。出力されるタグを変更するためには、 app/Config/html5_tags.php というファイルを作成し、以下の内容を記述します。:
$config = array('tags' => array(
'css' => '<link rel="%s" href="%s" %s>',
'style' => '<style%s>%s</style>',
'charset' => '<meta charset="%s">',
'javascriptblock' => '<script%s>%s</script>',
'javascriptstart' => '<script>',
'javascriptlink' => '<script src="%s"%s></script>',
// ...
));
そのあと、 $this->Html->loadConfig('html5_tags'); と記述することでこのタグ設定をロードできます。
CakePHP はパンくずリストを自動生成する組み込みメソッドを持っています。 設置するにはまず、レイアウトテンプレートに以下のようなコードを追加します。:
echo $this->Html->getCrumbs(' > ', 'Home');
$startText のオプションは1つの配列も受け付けます。 これにより、生成された最初のリンクへのさらなる制御を可能にします。:
echo $this->Html->getCrumbs(' > ', array(
'text' => $this->Html->image('home.png'),
'url' => array('controller' => 'pages', 'action' => 'display', 'home'),
'escape' => false
));
text または url でないキーは、 $options パラメータとして link() に渡されます。
バージョン 2.1 で変更: $startText パラメータは配列も受け入れることができます。
ビューでページのそれぞれにパンくずリストを作るため、 以下のコードを加えたとします。:
$this->Html->addCrumb('ユーザー', '/users');
$this->Html->addCrumb('ユーザーの追加', '/users/add');
すると、レイアウトで getCrumbs を書いたたところに、 “Home > ユーザー > ユーザーの追加” というパンくずリストが追加されます。
パラメタ: |
|
---|
(X)HTML のリストとしてパンくずリストを返します。
このメソッドは、リストと要素の作成に HtmlHelper::tag() を使用します。 getCrumbs() と同じように使うには、あらゆるパンくずリストの項目が 加えられたオプションを使用します。 $startText パラメータを設定すると パンくずリストの最初のリンクとテキストを指定することができます。 これは、つねにパンくずリストにトップを含めておきたいときに便利です。 このオプションは getCrumbs() の $startText オプションと同じ働きをします。
バージョン 2.1 で変更: $startText が追加されました。
バージョン 2.3 で変更: ‘separator’と ‘firstClass’ 、 ‘lastClass’ のオプションが追加されました。