merge from yiisoft/yii2

docs/guide-ja/structure-widgets.md

@@ -1,7 +1,8 @@
 ウィジェット
 ============
 
-ウィジェットは、[ビュー](structure-views.md) で使用される再利用可能な構成ブロックで、複雑かつ構成可能なユーザ・インタフェイス要素をオブジェクト指向のやり方で作成するためのものです。
+ウィジェットは、[ビュー](structure-views.md) で使用される再利用可能な構成ブロックで、
+複雑かつ構成可能なユーザ・インタフェイス要素をオブジェクト指向の流儀で作成するためのものです。
 例えば、日付選択ウィジェットを使うと、入力として日付を選択することを可能にする素敵なデイト・ピッカーを生成することが出来ます。
 このとき、あなたがしなければならないことは、次のようなコードをビューに挿入することだけです:
 
@@ -21,7 +22,7 @@ use yii\jui\DatePicker;
 ## ウィジェットを使う <span id="using-widgets"></span>
 
 ウィジェットは主として [ビュー](structure-views.md) で使われます。
-ビューでウィジェットを使うためには、[[yii\base\Widget::widget()]] メソッドを使うことが出来ます。
+[[yii\base\Widget::widget()]] メソッドを呼んで、ビューでウィジェットを使います。
 このメソッドは、ウィジェットを初期化するための [構成情報](concept-configurations.md) 配列を受け取り、ウィジェットのレンダリング結果を返します。
 例えば、下記のコードは、日本語を使い、入力を `$model` の `from_date` 属性に保存するように構成された日付選択ウィジェットを挿入するものです。
 
@@ -65,7 +66,8 @@ use yii\helpers\Html;
 [[yii\base\Widget::widget()]] がウィジェットのレンダリング結果を返すのとは違って、[[yii\base\Widget::begin()]] メソッドがウィジェットのインスタンスを返すことに注意してください。
 返されたウィジェットのインスタンスを使って、ウィジェットのコンテントを構築することが出来ます。
 
-> Note: いくつかのウィジェットは、[[yii\base\Widget::end()]] が呼ばれるときに内包されるコンテンツを調整するため、[出力バッファリング](http://php.net/manual/ja/book.outcontrol.php) を使用します。
+> Note: いくつかのウィジェットは、[[yii\base\Widget::end()]] が呼ばれるときに囲んだコンテンツを調整するため、
+> [出力バッファリング](http://php.net/manual/ja/book.outcontrol.php) を使用します。
 > この理由から、[[yii\base\Widget::begin()]] と [[yii\base\Widget::end()]] の呼び出しは、同じビュー・ファイルの中で発生するものと想定されています。
 > この規則に従わない場合は、予期しない出力結果が生じ得ます。
 
@@ -78,13 +80,19 @@ use yii\helpers\Html;
 \Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);
 ```
 
-詳細については [依存注入コンテナのガイドの "実際の使いかた" のセクション](concept-di-container.md#practical-usage) を参照してください。
+詳細については [依存注入コンテナのガイドの "実際の使いかた" のセクション](concept-di-container.md#practical-usage)
+を参照してください。
 
 
 ## ウィジェットを作成する <span id="creating-widgets"></span>
 
-ウィジェットを作成するためには、[[yii\base\Widget]] を拡張して、[[yii\base\Widget::init()]] および/または [[yii\base\Widget::run()]] メソッドをオーバーライドします。
-通常、`init()` メソッドはウィジェットのプロパティを正規化するコードを含むべきものであり、`run()` メソッドはウィジェットのレンダリング結果を生成するコードを含むべきものです。
+ウィジェットは必要に従って二つの異なる方法で作成することが出来ます。
+
+### 1: `widget()` メソッドを利用する
+
+ウィジェットを作成するためには、[[yii\base\Widget]] を拡張して、[[yii\base\Widget::init()]] および/または
+[[yii\base\Widget::run()]] メソッドをオーバーライドします。
+通常、`init()` メソッドはウィジェットのプロパティを初期化するコードを含むべきものであり、`run()` メソッドはウィジェットのレンダリング結果を生成するコードを含むべきものです。
 レンダリング結果は、直接に "echo" しても、`run()` の返り値として文字列として返しても構いません。
 
 次の例では、`HelloWidget` が `message` プロパティとして割り当てられたコンテントを HTML エンコードして表示します。
@@ -124,7 +132,23 @@ use app\components\HelloWidget;
 <?= HelloWidget::widget(['message' => 'おはよう']) ?>
 ```
 
-下記は `HelloWidget` の変種で、`begin()` と `end()` の間に包まれたコンテントを受け取り、それを HTML エンコードして表示するものです。
+
+ウィジェットが大きなかたまりのコンテントをレンダーする必要がある場合もあります。
+コンテントを `run()` の中に埋め込むことも出来ますが、もっと良い方法は、コンテントを [view](structure-views.md) に置き、
+[[yii\base\Widget::render()]] を呼んでレンダーする方法です。例えば、
+
+```php
+public function run()
+{
+    return $this->render('hello');
+}
+```
+
+### 2: `begin()` と `end()` のメソッドを利用する
+
+これは上記のものと少し異なるだけのものです。
+下記は `HelloWidget` の変種で、`begin()` と `end()` の間に包まれたコンテントを受け取り、
+それを HTML エンコードして表示するものです。
 
 ```php
 namespace app\components;
@@ -148,10 +172,12 @@ class HelloWidget extends Widget
 }
 ```
 
-ご覧のように、`init()` の中で PHP の出力バッファが開始され、`init()` と `run()` の呼び出しの間の全ての出力がキャプチャされ、`run()` の中で処理されて返されます。
+ご覧のように、`init()` の中で PHP の出力バッファが開始され、`init()` と `run()` の呼び出しの間の全ての出力がキャプチャされ、
+`run()` の中で処理されて返されます。
 
-> Info: [[yii\base\Widget::begin()]] を呼ぶと、ウィジェットの新しいインスタンスが作成され、ウィジェットのコンストラクタの最後で `init()` メソッドが呼ばれます。
-[[yii\base\Widget::end()]] を呼ぶと、`run()` メソッドが呼ばれて、その返り値が `end()` によって echo されます。
+> Info: [[yii\base\Widget::begin()]] を呼ぶと、ウィジェットの新しいインスタンスが作成され、
+  ウィジェットのコンストラクタの最後で `init()` メソッドが呼ばれます。
+  [[yii\base\Widget::end()]] を呼ぶと、`run()` メソッドが呼ばれて、その返り値が `end()` によって echo されます。
 
 次のコードは、この `HelloWidget` の新しい変種をどのように使うかを示すものです:
 
@@ -161,22 +187,17 @@ use app\components\HelloWidget;
 ?>
 <?php HelloWidget::begin(); ?>
 
-    ... タグを含みうるコンテント ...
+    一つまたはそれ以上の <strong>HTML</strong> <pre>タグ</pre> を含みうるサンプル・コンテント
+
+    このコンテントが大きくなりすぎる場合は、サブ・ビューを使います。
+
+    例えば、
+
+    <?php echo $this->render('viewfile'); // 注意: この render() メソッドは \yii\base\View クラスのもの。コードのこの部分はビュー・ファイルの中にあり、Widget クラス・ファイルの中にはない ?>
 
 <?php HelloWidget::end(); ?>
 ```
 
-場合によっては、ウィジェットが大きな固まりのコンテントを表示する必要があるかもしれません。
-コンテントを `run()` メソッドの中に埋め込むことも出来ますが、より良い方法は、コンテントを [ビュー](structure-views.md) の中に置いて、[[yii\base\Widget::render()]] を呼んでレンダリングすることです。
-例えば、
-
-```php
-public function run()
-{
-    return $this->render('hello');
-}
-```
-
 デフォルトでは、ウィジェット用のビューは `WidgetPath/views` ディレクトリの中のファイルに保存すべきものです。
 ここで `WidgetPath` はウィジェットのクラス・ファイルを含むディレクトリを指します。
 したがって、上記の例では、ウィジェット・クラスが `@app/components` に配置されていると仮定すると、`@app/components/views/hello.php` というビュー・ファイルがレンダリングされることになります。
@@ -196,4 +217,5 @@ public function run()
 幸いなことに、Yii はこの問題を解決するのに利用することが出来る [アセット・バンドル](structure-assets.md) のサポートを提供しています。
 
 ウィジェットがビュー・コードだけを含む場合は、[ビュー](structure-views.md) と非常に似たものになります。
-実際のところ、この場合、両者の唯一の違いは、ウィジェットが再配布可能なクラスである一方で、ビューはアプリケーション内に保持することが望ましい素の PHP スクリプトである、というぐらいの事です。
+実際のところ、この場合、両者の唯一の違いは、ウィジェットが再配布可能なクラスである一方で、
+ビューはアプリケーション内に保持することが望ましい素の PHP スクリプトである、というぐらいの事です。