Page contents

ヘルパー

ヘルパーはプレゼンテーションレイヤーのためのコンポーネントのようなクラスです。 多くのビューやエレメント、レイアウトで共有される表示ロジックを含んでいます。 この章ではヘルパーの作り方とCakePHPのコアヘルパーでできる基本的なタスクの概要を説明します。

CakePHPにはビューの作成に役立ついくつかの特徴的なヘルパーがあります。それらは、 整形式のマークアップ(フォーム含む)、テキスト、時間、数値の整形に役立ったり、Ajax機能をスピードアップさせたりします。 CakePHPのヘルパーに関するさらなる情報は ヘルパー を見て下さい。

ヘルパーの設定と使用

CakePHPでヘルパーを有効にするにはコントローラに認識させる必要があります。各コントローラは $helpers プロパティを持っており、そのプロパティにはビューで利用できるヘルパーの一覧が保持されています。 ビューでヘルパーを使用するにはヘルパーの名前をコントローラの $helpers 配列に追加して下さい。:

<?php
class BakeriesController extends AppController {
    public $helpers = array('Form', 'Html', 'Js', 'Time');
}

プラグインからヘルパーを追加するにはCakePHPの様々な場所で使われている プラグイン記法 を使います。:

<?php
class BakeriesController extends AppController {
    public $helpers = array('Blog.Comment');
}

あるアクションの間だけヘルパーを追加することができます。言い換えると、あるヘルパーの利用を特定のコントローラアクションに限定し、 同じコントローラの他のアクションでは利用できないようにすることができます。このことはコントローラが整理された状態を維持するのに役立つだけでなく、 さらに、ヘルパーを使わない他のアクションの処理コストを抑えることになります。:

<?php
class BakeriesController extends AppController {
    public function bake {
        $this->helpers[] = 'Time';
    }
    public function mix {
        // ここにTimeヘルパーは読み込まれないので利用出来ません
    }
}

もしすべてのコントローラでヘルパーを有効にする必要がある場合ヘルパーの名前を /app/Controller/AppController.php (見つからない場合は作成して下さい)の $helpers 配列に追加して下さい。デフォルトのHtmlヘルパーとFormヘルパーも忘れずに読み込んで下さい。:

<?php
class AppController extends Controller {
    public $helpers = array('Form', 'Html', 'Js', 'Time');
}

ヘルパーにはオプションを渡すことが出来ます。このオプションは属性の値を設定したり、ヘルパーの動作を変えるために使うことができます。:

<?php
class AwesomeHelper extends AppHelper {
    public function __construct(View $view, $settings = array()) {
        parent::__construct($view, $settings);
        debug($settings);
    }
}

class AwesomeController extends AppController {
    public $helpers = array('Awesome' => array('option1' => 'value1'));
}

すべてのヘルパーで共通して使える設定に className オプションがあります。このオプションを設定するとビューの中に別名のヘルパーを作ることができます。 この機能は $this->Html や他の共通ヘルパーの参照を独自の実装に置き換えたい時に役立ちます。:

<?php
// app/Controller/PostsController.php
class PostsController extends AppController {
    public $helpers = array(
        'Html' => array(
            'className' => 'MyHtml'
        )
    );
}

// app/View/Helper/MyHtmlHelper.php
App::uses('HtmlHelper', 'View/Helper');
class MyHtmlHelper extends HtmlHelper {
    // コアHtmlHelperを上書きするためのコードを追加して下さい
}

上記の例ではビューの中で MyHtmlHelper$this->Html別名 になっています。

ノート

別名が付けられたヘルパーはどこで使われていたとしてもそのインスタンスを置き換えます。 それには他のヘルパーの内部も含まれます。

ちなみに

HtmlやSessionの別名を付けられたヘルパーはコアのPagesControllerで使うとうまく動かないでしょう。 そのため、``lib/Cake/Controller/PagesController.php`` を app/Controller/ フォルダにコピーした方が良いです。

ヘルパーを設定することで宣言的にヘルパーを設定することができるようになり、また、 コントローラアクションの外に設定のロジックを置けるようになります。もし、クラス宣言の一部に含めることができない設定項目がある場合、 コントローラのbeforeRenderコールバックの中でそれらを設定することが出来ます。:

<?php
class PostsController extends AppController {
    public function beforeRender() {
        parent::beforeRender();
        $this->helpers['CustomStuff'] = $this->_getCustomStuffSettings();
    }
}

ヘルパーを使う

コントローラの中でどのヘルパーが使いたいのかを一度設定してしまえば、各ヘルパーはビューの中でパブリックプロパティのように扱えます。 例えば HtmlHelper を使っているとします。その場合、次のようにヘルパーにアクセスできます。:

<?php
echo $this->Html->css('styles');

上記の例ではHtmlHelperの css メソッドを呼び出しています。読み込み済みのヘルパーであれば $this->{$helperName} の形式でアクセスすることが出来ます。ビューの内部から動的にヘルパーを読み込む必要に迫られる時が来るかもしません。 その時は、 ビューの HelperCollection を使ってこのようにできます。:

<?php
$mediaHelper = $this->Helpers->load('Media', $mediaSettings);

HelperCollectionは コレクション であり、CakePHPの他の箇所でも使われているコレクションAPIをサポートしています。

コールバックメソッド

ヘルパーはビューの描画工程を増やすようないくつかのコールバックを特徴としています。 さらに情報が欲しい場合は、 ヘルパー API/core-libraries/collections ドキュメントを参照して下さい。

ヘルパーを作る

もし、コアヘルパー(またはgithubやBakeryにあるヘルパー) でやりたいことができなかったとしても、 ヘルパーを作るのは簡単なので大丈夫です。

ここで、アプリケーション内の様々な場所で必要とされるCSSスタイルのリンクを出力するヘルパーを作りたかったとしましょう。 CakePHPの既存のヘルパーの構造にロジックをあわせる為には、``/app/View/Helper`` に新しいクラスを作成する必要があります。 これから作るヘルパーをLinkHelperと呼ぶことにしましょう。実際のPHPクラスファイルはこのようになるでしょう。:

<?php
/* /app/View/Helper/LinkHelper.php */
App::uses('AppHelper', 'View/Helper');

class LinkHelper extends AppHelper {
    public function makeEdit($title, $url) {
        // 特別に整形されたリンクを作るためのロジックはここ...
    }
}

ノート

ヘルパーは AppHelper または Helper を継承するか ヘルパー API で定義されているすべてのコールバックを実装しなければなりません。

他のヘルパーを読み込む

他のヘルパーに既に存在している機能を使いたいと思うかもしれません。その場合、``$helpers`` 配列に使いたいヘルパーを明示することで実現出来ます。フォーマットは、コントローラで指定する場合と同じようにして下さい。:

<?php
/* /app/View/Helper/LinkHelper.php (他のヘルパーを使っている) */
App::uses('AppHelper', 'View/Helper');

class LinkHelper extends AppHelper {
    public $helpers = array('Html');

    public function makeEdit($title, $url) {
        // 整形されたデータを出力するために
        // HTMLヘルパーを使う:

        $link = $this->Html->link($title, $url, array('class' => 'edit'));

        return '<div class="editOuter">' . $link . '</div>';
    }
}

自作のヘルパーを使う

一旦ヘルパーを作って /app/View/Helper/ に配置すると、コントローラで $helpers という特別な変数を使うことでそのヘルパーを読み込めるようになります。:

<?php
class PostsController extends AppController {
    public $helpers = array('Link');
}

一旦コントローラがこの新しいクラスを認識すると、ヘルパーの名前にちなんで名付けられたオブジェクトにアクセスすることで、ビューの中からこのヘルパーを使えるようになります。:

<!-- 新しいヘルパーを使ってリンクを作る -->
<?php echo $this->Link->makeEdit('Change this Recipe', '/recipes/edit/5'); ?>

すべてのヘルパーのための機能を作成する

すべてのヘルパーは特別なクラスAppHelperを(モデルがAppModelを継承し、コントローラがAppControllerを継承するのと同じように)継承します。 すべてのヘルパーで利用できる機能を作成するためには、 /app/View/Helper/AppHelper.php を作成して下さい。:

<?php
App::uses('Helper', 'View');

class AppHelper extends Helper {
    public function customMethod() {
    }
}

ヘルパー API

class Helper

ヘルパーの基底クラスです。いくつかのユーティリティメソッドと他のヘルパーを読み込む機能を提供しています。

Helper::webroot($file)

ファイル名をアプリケーションのwebrootで解決します。テーマがアクティブで現在のテーマのwebrootにファイルが存在しているとき、 テーマのファイルへのパスが返ります。

Helper::url($url, $full = false)

HTMLがエスケープされたURLを生成し、 Router::url() に委譲します。

Helper::value($options = array(), $field = null, $key = 'value')

与えられたinput名に対応する値を取得します。

Helper::domId($options = null, $id = 'id')

現在選択されているフィールドに対応するキャメルケースのid値を生成します。AppHelperにてこのメソッドを上書きすることでCakePHPがID属性を生成する方法を変更することができます。

コールバック

Helper::beforeRenderFile($viewFile)

すべてのビューファイルが描画される前に呼び出されます。これにはエレメント、 ビュー、親ビュー、レイアウトを含みます。

Helper::afterRenderFile($viewFile, $content)

すべてのビューファイルが描画がされた後に呼び出されます。これにはエレメント、 ビュー、親ビュー、レイアウトを含みます。コールバックは描画されたコンテンツがブラウザにどのように描画されるかを変えるために $content を変更して返すことができます。

Helper::beforeRender($viewFile)

beforeRenderメソッドはコントローラのbeforeRenderメソッドの後に呼び出されます。 しかし、コントローラがビューとレイアウトを描画する前です。描画されるファイルを引数として受け取ります。

Helper::afterRender($viewFile)

ビューが描画された後に呼び出されます。しかし、レイアウトの描画開始前でく。

Helper::beforeLayout($layoutFile)

レイアウトの描画開始前に呼び出されます。レイアウトファイル名を引数として受け取ります。

Helper::afterLayout($layoutFile)

レイアウトの描画が完了した時に呼び出されます。レイアウトファイル名を引数として受け取ります。

コアヘルパー

キャッシュヘルパー
ビューコンテンツをキャッシュするためのコアによって使われます。
/core-libraries/helpers/form
HTMLフォームと自動生成されるフォームエレメントを作成します。また、バリデーション問題をハンドリングします。
/core-libraries/helpers/html
整形式のマークアップを作るための便利なメソッドです。画像、リンク、ヘッダタグなど。
/core-libraries/helpers/js
様々なJavascriptライブラリと互換のあるJavascriptを作成するために使われます。
/core-libraries/helpers/number
数値と通貨を整形します。
/core-libraries/helpers/paginator
モデルデータのページ切り替えと並び替え。
/core-libraries/helpers/rss
RSSフィードとXMLデータを出力するための便利なメソッドです。
セッションヘルパー
ビューでセッションの値を読み込んでアクセスします。
/core-libraries/helpers/text
スマートリンク、ハイライト、ワードスマートトランケート。
/core-libraries/helpers/time
近傍検出(来年かどうか?)や、素晴らしい文字列整形(Today, 10:30 am)とタイムゾーンの変換をします。