Merge pull request #5691 from softark/docs-ja-2014-10-22

[ci skip] docs/guide-ja/start-hello.md added

docs/guide-ja/README.md

@@ -21,7 +21,7 @@ All Rights Reserved.
 
 * [Yii をインストールする](start-installation.md)
 * [アプリケーションを走らせる](start-workflow.md)
-* [ハローと言う](start-hello.md)
+* [「こんにちは」と言う](start-hello.md)
 * [フォームを扱う](start-forms.md)
 * [データベースを扱う](start-databases.md)
 * [Gii でコードを生成する](start-gii.md)

docs/guide-ja/start-hello.md

@@ -0,0 +1,143 @@
+「こんにちは」と言う
+====================
+
+この章では、アプリケーションに新しい「こんにちは」というページを作成する方法を説明します。
+この目的を達するために、[アクション](structure-controllers.md#creating-actions) と [ビュー](structure-views.md) を作成することになります:
+
+* アプリケーションがこのページへのリクエストをそのアクションに送致(dispatch)し、
+* 次にそのアクションが "Hello" という言葉をエンドユーザに示すビューを表示します。
+
+このチュートリアルを通じて、次の三つのことを学びます:
+
+1. リクエストに応える [アクション](structure-controllers.md) をどのようにして作るか、
+2. レスポンスの内容を構成する [ビュー](structure-views.md) をどのようにして作るか、そして、
+3. アプリケーションはどのようにしてリクエストを [アクション](structure-controllers.md#creating-actions) に送致するか。
+
+
+アクションを作成する<a name="creating-action"></a>
+--------------------
+
+「こんにちは」のタスクのために、`message` パラメータをリクエストから読んでそのメッセージをユーザに表示して返す `say` [アクション](structure-controllers.md#creating-actions) を作ります。
+リクエストが `message` パラメータを提供しない場合は、このアクションは既定値として "Hello" というメッセージを表示するものとします。
+
+> Info|情報: [アクション](structure-controllers.md#creating-actions) は、エンドユーザが直接に参照して実行できるオブジェクトです。
+  アクションは [コントローラ](structure-controllers.md) によってグループ化されます。
+  アクションの実行結果が、エンドユーザが受け取るレスポンスです。
+
+アクションは [コントローラ](structure-controllers.md) の中で宣言されなければなりません。
+話を簡単にするために、`say` アクションを既存の `SiteController` の中で宣言しても構いません。
+このコントローラは `controllers/SiteController.php` というクラスファイルの中で定義されています。
+次のようにして、新しいアクションを書き始めます:
+
+```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` と言う名前の [ビュー](structure-views.md) ファイルが表示されます。
+`message` パラメータも同時にビューに渡され、そこで使用されます。
+表示結果はアクションメソッドによって返されます。
+返された結果はアプリケーションによって受け取られ、ブラウザ上でエンドユーザに(完全な HTML ページの一部として)表示されます。
+
+
+ビューを作成する<a name="creating-view"></a>
+----------------
+
+[ビュー](structure-views.md) は、レスポンスのコンテンツを生成するために書くスクリプトです。
+「こんにちは」のタスクのためには、アクションメソッドから受け取った `message` パラメータを印字する `say` ビューを作成します:
+
+```php
+<?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) 攻撃](http://ja.wikipedia.org/wiki/%E3%82%AF%E3%83%AD%E3%82%B9%E3%82%B5%E3%82%A4%E3%83%88%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0) に使われうるものですから、脆弱性を防止するためにこれは必要な措置です。
+
+当然ながら、`say` ビューにはもっと多くのコンテンツを入れても構いません。
+コンテンツには、HTML タグ、平文テキスト、さらには PHP 文を含めることが出来ます。
+実際、`say` ビューは [[yii\web\Controller::render()|render()]] メソッドによって実行される PHP スクリプトであるに過ぎません。
+ビュースクリプトによって描画されたコンテンツはレスポンス結果としてアプリケーションに返されます。
+そしてアプリケーションがこの結果をエンドユーザに対して出力します。
+
+
+試してみる<a name="trying-it-out"></a>
+----------
+
+アクションとビューを作成したら、新しいページに下記の URL でアクセスしてみましょう:
+
+```
+http://hostname/index.php?r=site/say&message=Hello+World
+```
+
+![Hello World](images/start-hello-world.png)
+
+この URL は "Hello World" を表示するページになります。
+このページはアプリケーションの他のページと同じヘッダとフッタを共有します。
+
+URL から `message` パラメータを省略すると、"Hello" だけを表示するページを見ることになるでしょう。
+これは、`message` が `actionSay()` メソッドにパラメータとして渡され、省略された場合には、既定値である `"Hello"` が代りに使われるからです。
+
+> Info|情報: 新しいページは他のページと同じヘッダとフッタを共有しますが、それは [[yii\web\Controller::render()|render()]] メソッドが `say` ビューの結果をいわゆる [レイアウト](structure-views.md#layouts) に自動的に埋め込むからです。
+レイアウトは、この場合、`views/layouts/main.php` にあります。
+
+上記の URL の `r` パラメータについて、さらに説明が必要でしょう。
+これは [ルート](runtime-routing.md)、すなわち、特定のアクションを指し示すアプリケーション全体で一意な ID を表します。
+ルートの書式は `ControllerID/ActionID` です。
+アプリケーションはリクエストを受け取ると、このパラメータをチェックし、`ControllerID` の部分を使って、このリクエストを処理するためにどのコントローラクラスのインスタンスを作成すべきかを決定します。
+そして、コントローラは `ActionID` の部分を使って、実際の仕事をするためにどのアクションを呼び出すべきかを決定します。
+この例で言えば、`site/say` というルートは、`SiteController` コントローラクラスと `say` アクションとして解決されます。
+結果として、`SiteController::actionSay()` メソッドがリクエストを処理するために呼び出されます。
+
+
+> Info|情報: アクションと同じく、コントローラもまたアプリケーションの中で一意に定義される ID を持ちます。
+  コントローラ ID も、アクション ID と同じ命名規則を使います。
+  コントローラクラスの名前は、コントローラ ID からダッシュを削除し、各単語の最初の文字を大文字にし、結果として出来る文字列に `Controller` という接尾語を追加したものとします。
+  例えば、`post-comment` というコントローラ ID に対応するコントローラクラスの名前は `PostCommentController` です。
+
+
+まとめ<a name="summary"></a>
+------
+
+この章では、MVC デザインパターンのうちのコントローラとビューの部分に触れました。
+特定のリクエストを処理するためのアクションをコントローラの一部として作成しました。
+また、レスポンスのコンテンツを構成するためにビューも作成しました。
+この単純な例においては、使用される唯一のデータが `message` パラメータであったため、モデルは関係してきませんでした。
+
+また、Yii におけるルートについても学びました。ルートはユーザのリクエストとコントローラのアクションとの橋渡しとして働くものです。
+
+次の章では、モデルを作成する方法を学び、そして、HTML フォームを含むページを追加します。