Blame History Permalink

docs/guide-ja/* changes for "render" and "rendering" [ci skip] · c03d902c
Nobuo Kihara authored 11 years ago

c03d902c

start-hello.md 10.7 KB

「こんにちは」と言う

この節では、アプリケーションに新しい「こんにちは」というページを作成する方法を説明します。この目的を達するために、アクションとビューを作成することになります:

アプリケーションがこのページへのリクエストをそのアクションに送付し、
次にそのアクションが "Hello" という言葉をエンドユーザに示すビューを表示します。

このチュートリアルを通じて、次の三つのことを学びます:

リクエストに応えるアクションをどのようにして作るか、
レスポンスの内容を構成するビューをどのようにして作るか、そして、
アプリケーションはどのようにしてリクエストをアクションに送付するか。

アクションを作成する

「こんにちは」のタスクのために、message パラメータをリクエストから読んでそのメッセージをユーザに表示して返す say アクションを作ります。リクエストが message パラメータを提供しない場合は、このアクションは既定値として "Hello" というメッセージを表示するものとします。

Info|情報: アクションは、エンドユーザが直接に参照して実行できるオブジェクトです。アクションはコントローラによってグループ化されます。アクションの実行結果が、エンドユーザが受け取るレスポンスです。

アクションはコントローラの中で宣言されなければなりません。話を簡単にするために、say アクションを既存の SiteController の中で宣言しましょう。このコントローラは controllers/SiteController.php というクラスファイルの中で定義されています。次のようにして、新しいアクションを書き始めます:

<?php

namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
    // ... 既存のコード ...

    public function actionSay($message = 'Hello')
    {
        return $this->render('say', ['message' => $message]);
    }
}

上記のコードで、say アクションは SiteController クラスの中で actionSay という名前のメソッドとして定義されています。 Yii はコントローラクラスの中でアクションのメソッドとアクションでないメソッドを区別するために、action という接頭辞を使います。 action という接頭辞の後の名前がアクション ID にマップされます。

アクションを命名するについては、Yii がアクション ID をどのように取り扱うかを知っているべきです。アクション ID は常に小文字で参照されます。アクション ID が複数の単語を必要とするときは、単語がダッシュ(-)で連結されます (例えば、create-comment)。アクションメソッドの名前は、アクション ID からダッシュを全て削除し、各単語の先頭の文字を大文字にした結果に action という接頭辞を付けたものとします。例えば、アクション ID create-comment に対応するアクションメソッド名は actionCreateComment となります。

私たちの例では、このアクションメソッドは $message というパラメータを取ります。そして、このパラメータは "Hello" という既定値を取ります (PHP で関数やメソッドの引数について既定値をセットするのと全く同じ方法を使います)。アプリケーションは、リクエストを受け取って、当該リクエストの処理を say アクションに任せると決定した場合、リクエストの中に同じ名前の付いたパラメータがあれば、それをこのパラメータに代入します。言い換えれば、もしリクエストに "GoodBye" という値の message パラメータが入っていれば、アクションの $message 変数にその値が割り当てられます。

このアクションメソッドの中では、[[yii\web\Controller::render()|render()]] が呼ばれて say と言う名前のビューファイルがレンダリングされます。 message パラメータも同時にビューに渡され、そこで使用されます。レンダリング結果はアクションメソッドによって返されます。返された結果はアプリケーションによって受け取られ、ブラウザ上でエンドユーザに(完全な HTML ページの一部として)表示されます。

ビューを作成する

ビューは、レスポンスのコンテンツを生成するためにあなたが書くスクリプトです。「こんにちは」のタスクのためには、アクションメソッドから受け取った message パラメータを印字する say ビューを作成します:

<?php
use yii\helpers\Html;
?>
<?= Html::encode($message) ?>

say ビューは views/site/say.php というファイルに保存しなければなりません。アクションの中で [[yii\web\Controller::render()|render()]] メソッドが呼ばれるとき、このメソッドは views/ControllerID/ViewName.php という名前の PHP ファイルを探します。

上記のコードでは、message パラメータが印字される前に [[yii\helpers\Html::encode()|HTML-エンコード]] されていることに注意してください。パラメータはエンドユーザから来るものであり、悪意のある JavaScript コードを埋め込まれてクロスサイトスクリプティング (XSS) 攻撃に使われうるものですから、脆弱性を防止するためにこれは必要な措置です。

当然ながら、say ビューにはもっと多くのコンテンツを入れても構いません。コンテンツには、HTML タグ、平文テキスト、さらには PHP 文を含めることが出来ます。実際、say ビューは [[yii\web\Controller::render()|render()]] メソッドによって実行される PHP スクリプトであるに過ぎません。ビュースクリプトによって描画されたコンテンツはレスポンス結果としてアプリケーションに返されます。そしてアプリケーションがこの結果をエンドユーザに対して出力します。

試してみる

アクションとビューを作成したら、新しいページに下記の URL でアクセスしてみましょう:

http://hostname/index.php?r=site/say&message=Hello+World

この URL は "Hello World" を表示するページになります。このページはアプリケーションの他のページと同じヘッダとフッタを共有します。

URL から message パラメータを省略すると、"Hello" だけを表示するページを見ることになるでしょう。これは、message が actionSay() メソッドにパラメータとして渡され、省略された場合には、既定値である "Hello" が代りに使われるからです。

Info|情報: 新しいページは他のページと同じヘッダとフッタを共有しますが、それは [[yii\web\Controller::render()|render()]] メソッドが say ビューの結果をいわゆるレイアウトに自動的に埋め込むからです。レイアウトは、この場合、views/layouts/main.php にあります。

上記の URL の r パラメータについて、さらに説明が必要でしょう。これはルート、すなわち、特定のアクションを指し示すアプリケーション全体で一意な ID を表します。ルートの書式は ControllerID/ActionID です。アプリケーションはリクエストを受け取ると、このパラメータをチェックし、ControllerID の部分を使って、このリクエストを処理するためにどのコントローラクラスのインスタンスを作成すべきかを決定します。そして、コントローラは ActionID の部分を使って、実際の仕事をするためにどのアクションを呼び出すべきかを決定します。この例で言えば、site/say というルートは、SiteController コントローラクラスと say アクションとして解決されます。結果として、SiteController::actionSay() メソッドがリクエストを処理するために呼び出されます。

Info|情報: アクションと同じく、コントローラもまたアプリケーションの中で一意に定義される ID を持ちます。コントローラ ID も、アクション ID と同じ命名規則を使います。コントローラクラスの名前は、コントローラ ID からダッシュを削除し、各単語の最初の文字を大文字にし、結果として出来る文字列に Controller という接尾辞を追加したものとします。例えば、post-comment というコントローラ ID に対応するコントローラクラスの名前は PostCommentController です。

まとめ

この節では、MVC デザインパターンのうちのコントローラとビューの部分に触れました。特定のリクエストを処理するためのアクションをコントローラの一部として作成しました。また、レスポンスのコンテンツを構成するためにビューも作成しました。この単純な例においては、使用される唯一のデータが message パラメータであったため、モデルは関係してきませんでした。

また、Yii におけるルートについても学びました。ルートはユーザのリクエストとコントローラのアクションとの橋渡しとして働くものです。

次の節では、モデルを作成する方法を学び、そして、HTML フォームを含むページを追加します。