Merge pull request cakephp#2919 from okinaka/update-components

[ja] update components.rst

Author: suzuki

ja/controllers/components.rst

@@ -1,22 +1,15 @@
 コンポーネント
 ##############
 
-コンポーネントはコントローラ間で共有されるロジックのパッケージです。もしコントローラ間でコピーアンドペーストしたい箇所があった場合、
-いくつかの機能をコンポーネントでラップできるかもしれません。
+コンポーネントはコントローラ間で共有されるロジックのパッケージです。
+CakePHP には、様々な共通のタスクを支援するための素晴らしいコアコンポーネントが用意されています。
+あなた独自のコンポーネントも作成できます。もしコントローラ間でコピーアンドペーストしたい箇所が
+あった場合、その機能を含むコンポーネントの作成を検討しましょう。コンポーネントを作成することで、
+コントローラのコードを綺麗に保ち、プロジェクト間のコードの再利用につながります。
 
-また、CakePHPには以下の目的で使える素晴らしいコアコンポーネントが準備されています。:
-
-- セキュリティ
-- セッション
-- アクセスコントロール
-- メール
-- クッキー
-- 認証
-- リクエストハンドリング
-- ページ切替
-
-各コアコンポーネントの詳細は各章で説明します。ここでは、独自のコンポーネントを作成する方法を紹介します。
-コンポーネントを作成することでコントローラのコードがクリーンな状態に保たれ、プロジェクト間でコードを再利用し易くなります。
+各コアコンポーネントの詳細はそれぞれの章で説明します。詳しくは、
+:doc:`/core-libraries/toc-components` を参照してください。
+ここでは、独自のコンポーネントを作成する方法を紹介します。
 
 .. _configuring-components:
 
@@ -32,33 +25,44 @@
         public $components = array(
             'Auth' => array(
                 'authorize' => array('controller'),
-                'loginAction' => array('controller' => 'users', 'action' => 'login')
+                'loginAction' => array(
+                    'controller' => 'users',
+                    'action' => 'login'
+                )
             ),
             'Cookie' => array('name' => 'CookieMonster')
         );
 
-これは  ``$components`` 配列でコンポーネントを設定している例です。すべてのコアコンポーネントはこの方法で設定することができます。
-さらに、コントローラの ``beforeFilter()`` メソッドで設定することもできます。これは関数の結果をコンポーネントのプロパティに設定する時に役に立ちます。
+これは  ``$components`` 配列でコンポーネントを設定している例です。
+すべてのコアコンポーネントはこの方法で設定することができます。
+さらに、コントローラの ``beforeFilter()`` メソッドで設定することもできます。
+これは関数の結果をコンポーネントのプロパティに設定する時に役に立ちます。
 上記の例は次のように書き換えられます。::
 
     public function beforeFilter() {
         $this->Auth->authorize = array('controller');
-        $this->Auth->loginAction = array('controller' => 'users', 'action' => 'login');
+        $this->Auth->loginAction = array(
+            'controller' => 'users',
+            'action' => 'login'
+        );
 
         $this->Cookie->name = 'CookieMonster';
     }
 
-しかし、コンポーネントのオプションをコントローラの ``beforeFilter()`` が実行される前に設定することが可能な場合もあります。
-つまり、コンポーネントの中には ``$components`` 配列にオプションを設定することができるものがあります。::
+しかし、コンポーネントのオプションをコントローラの ``beforeFilter()`` が
+実行される前に設定することが可能な場合もあります。
+つまり、コンポーネントの中には ``$components`` 配列にオプションを設定することが
+できるものがあります。::
 
     public $components = array(
         'DebugKit.Toolbar' => array('panels' => array('history', 'session'))
     );
 
 各コンポーネントがどのような設定オプションを提供しているかは関連ドキュメントを参照してください。
 
-共通設定の一つに ``className`` オプションがあります。このオプションを使うとコンポーネントに別名をつけられます。
-この機能は ``$this->Auth`` や他のコンポーネントの参照を独自実装に置き換えたい時に便利です。::
+共通設定の一つに ``className`` オプションがあります。このオプションを使うとコンポーネントに
+別名をつけられます。この機能は ``$this->Auth`` や他のコンポーネントの参照を独自実装に
+置き換えたい時に便利です。::
 
     // app/Controller/PostsController.php
     class PostsController extends AppController {
@@ -72,22 +76,23 @@
     // app/Controller/Component/MyAuthComponent.php
     App::uses('AuthComponent', 'Controller/Component');
     class MyAuthComponent extends AuthComponent {
-        // コアAuthComponentを上書きするコードを追加して
+        // コア AuthComponent を上書きするコードを追加して
     }
 
 上記の例ではコントローラにて ``MyAuthComponent`` に ``$this->Auth`` という *別名* をつけています。
 
 .. note::
 
-    別名を付けられたコンポーネントはコンポーネントが使われるあらゆる場所のインスタンスを置き換えます。これは、他のコンポーネントの内部を含みます。
+    別名を付けられたコンポーネントはコンポーネントが使われるあらゆる場所のインスタンスを置き換えます。
+    これは、他のコンポーネントの内部を含みます。
 
 コンポーネントの使用
 ====================
 
 一旦、コンポーネントをコントローラに読込んでしまえば、使うのは非常に簡単です。
 使用中の各コンポーネントはコントローラのプロパティのように見えます。
-仮に、 :php:class:`SessionComponent` と :php:class:`CookieComponent` をコントローラに読込んだ場合、
-以下のようにアクセスすることができます。::
+もし、 :php:class:`SessionComponent` と :php:class:`CookieComponent` を
+コントローラに読込んだ場合、以下のようにアクセスすることができます。::
 
     class PostsController extends AppController {
         public $components = array('Session', 'Cookie');
@@ -101,15 +106,15 @@
 
 .. note::
 
-    モデルとコンポーネントの両方がコントローラにプロパティとして追加されるので、それらは同じ '名前空間' を共有します。
-    コンポーネントとモデルに同じ名前をつけないように注意して下さい。
+    モデルとコンポーネントの両方がコントローラにプロパティとして追加されるので、それらは同じ
+    '名前空間' を共有します。コンポーネントとモデルに同じ名前をつけないように注意して下さい。
 
 コンポーネントの動的読込み
 --------------------------
 
 すべてのコントローラアクションで全コンポーネントを使えるようにする必要はないかもしれません。
-このような状況では、実行時に :doc:`コンポーネントコレクション </core-libraries/collections>` を使ってコンポーネントを読込むことができます。
-コントローラ内部から以下のようにできます。::
+このような状況では、実行時に :doc:`コンポーネントコレクション </core-libraries/collections>` を
+使ってコンポーネントを読込むことができます。コントローラ内部から以下のようにできます。::
 
     $this->OneTimer = $this->Components->load('OneTimer');
     $this->OneTimer->getTime();
@@ -123,16 +128,20 @@
 コンポーネントのコールバック
 ============================
 
-コンポーネントはまた、いくつかのリクエストライフサイクルにリクエストライフサイクルが増すようなコールバックを提供します。
-コンポーネントが提供するコンポーネントの詳細については、 :ref:`component-api` の基本を参照して下さい。
+コンポーネントはまた、いくつかのリクエストライフサイクルにリクエストライフサイクルが増すような
+コールバックを提供します。コンポーネントが提供するコンポーネントの詳細については、
+:ref:`component-api` の基本を参照して下さい。
+
+.. _creating-a-component:
 
 コンポーネントを作成する
 ========================
 
 アプリケーションの様々な箇所で複雑な数学的処理を必要としているオンラインアプリケーションを仮定して下さい。
 これから、コントローラの様々な箇所で使うための共有ロジックを集約するためのコンポーネントを作成します。
 
-はじめに、新しいコンポーネントファイルとクラスを作成します。 ``/app/Controller/Component/MathComponent.php`` にファイルを作成して下さい。
+はじめに、新しいコンポーネントファイルとクラスを作成します。
+``/app/Controller/Component/MathComponent.php`` にファイルを作成して下さい。
 コンポーネントの基本構造は以下のようになります。::
 
     App::uses('Component', 'Controller');
@@ -144,23 +153,26 @@
 
 .. note::
 
-    すべてのコンポーネントは :php:class:`Component` を継承しなければなりません。継承されていない場合、例外が発生するでしょう。
+    すべてのコンポーネントは :php:class:`Component` を継承しなければなりません。
+    継承されていない場合、例外が発生するでしょう。
 
 コントローラの中にコンポーネントを読み込む
 ------------------------------------------
 
-一旦コンポーネントが完成してしまえば、コントローラの ``$components`` 配列にあるコンポーネント名(Componentの部分を削除する)を置き換えることで使えるようになります。
+一旦コンポーネントが完成してしまえば、コントローラの ``$components`` 配列にあるコンポーネント名
+(Component の部分を削除する) を置き換えることで使えるようになります。
 コントローラはそのコンポーネントに由来する新しいプロパティを自動的に与えられるでしょう。
 そのプロパティを通してインスタンスにアクセスできます。::
 
-    /* 標準の$this->Sessionと同様に新しいコンポーネントを $this->Math で利用できるようにします。*/
+    /* 標準の $this->Session と同様に新しいコンポーネントを
+       $this->Math で利用できるようにします。*/
     public $components = array('Math', 'Session');
 
-``AppController`` の中で宣言されているコンポーネントは他のコントローラで宣言されているコンポーネントとマージされます。
-同じコンポーネントを二度宣言する必要はありません。
+``AppController`` の中で宣言されているコンポーネントは他のコントローラで宣言されているコンポーネントと
+マージされます。同じコンポーネントを二度宣言する必要はありません。
 
-コントローラの中でコンポーネントを読み込む時、コンポーネントのコンストラクタに渡すバラメータを宣言することもできます。
-このパラメータはコンポーネントによってハンドリングされます。::
+コントローラの中でコンポーネントを読み込む時、コンポーネントのコンストラクタに渡すバラメータを
+宣言することもできます。このパラメータはコンポーネントによってハンドリングされます。::
 
     public $components = array(
         'Math' => array(
@@ -170,8 +182,9 @@
         'Session', 'Auth'
     );
 
-上記の例ではprecisionとrandomGeneratorを含む配列が ``MathComponent::__construct()`` の第二引数として渡されます。
-コンポーネントのパブリックプロパティや引数として渡される設定はその配列に基づいた値になります。
+上記の例では precision と randomGenerator を含む配列が ``MathComponent::__construct()`` の
+第二引数として渡されます。コンポーネントのパブリックプロパティや引数として渡される設定はその配列に
+基づいた値になります。
 
 コンポーネントの中で他のコンポーネントを使用する
 ------------------------------------------------
@@ -204,7 +217,9 @@
         }
     }
 
-コントローラから読み込んだコンポーネントと違い、コンポーネントからコンポーネントを読み込んだ場合は、コールバックが呼ばれないことに注意して下さい。
+.. note::
+    コントローラから読み込んだコンポーネントと違い、コンポーネントからコンポーネントを読み込んだ場合は、
+    コールバックが呼ばれないことに注意して下さい。
 
 .. _component-api:
 
@@ -213,39 +228,44 @@
 
 .. php:class:: Component
 
-    コンポーネントの基底クラスは :php:class:`ComponentCollection` を通して共通のハンドリング設定を扱うように他のコンポーネントを遅延読み込みするためのメソッドをいくつか提供しています。
+    コンポーネントの基底クラスは :php:class:`ComponentCollection` を通して共通のハンドリング設定を
+    扱うように他のコンポーネントを遅延読み込みするためのメソッドをいくつか提供しています。
     また、コンポーネントのすべてのコールバックのプロトタイプを提供します。
 
 .. php:method:: __construct(ComponentCollection $collection, $settings = array())
 
-    基底コンポーネントクラスのコンストラクタです。すべての ``$settings`` 、またはパブリックプロパティは ``$settings`` の中で一致した値に変更されます。
+    基底コンポーネントクラスのコンストラクタです。すべての ``$settings`` 、
+    またはパブリックプロパティは ``$settings`` の中で一致した値に変更されます。
 
 コールバック
 ------------
 
 .. php:method:: initialize(Controller $controller)
 
-    initializeメソッドはコントローラの beforeFilter の前に呼び出されます。
+    コントローラの beforeFilter メソッドの前に呼び出されます。
 
 .. php:method:: startup(Controller $controller)
 
-    startupメソッドはコントローラのbeforeFilterの後、コントローラの現在のアクションハンドラの前に呼び出されます。
+    コントローラの beforeFilter メソッドの後、コントローラの現在のアクションハンドラの前に
+    呼び出されます。
 
 .. php:method:: beforeRender(Controller $controller)
 
-    beforeRenderメソッドはコントローラが要求されたアクションのロジックを実行した後で、ビューとレイアウトが描画される前に呼び出されます。
+    コントローラが要求されたアクションのロジックを実行した後、
+    ビューとレイアウトが描画される前に呼び出されます。
 
 .. php:method:: shutdown(Controller $controller)
 
-    shutdownメソッドは出力結果がブラウザに送信される前に呼び出されます。
+    出力結果がブラウザに送信される前に呼び出されます。
 
 .. php:method:: beforeRedirect(Controller $controller, $url, $status=null, $exit=true)
 
-    beforeRedirectメソッドはコントローラのredirectメソッドが呼び出され時に、他のアクションより先に呼びだされます。
-    このメソッドがfalseを返す時、コントローラはリクエストのリダイレクトを中断します。
+    コントローラの redirect メソッドが呼び出された時に、他のアクションより先に呼びだされます。
+    このメソッドが false を返す時、コントローラはリクエストのリダイレクトを中断します。
     $url, $status と $exit 変数はコントローラのメソッドの場合と同じ意味です。また、
-    リダイレクト先のURL文字列を返すか、'url'と'status'と'exit'をキーに持つ連想配列を返すことができます。
-    'status'と'exit'は任意です。
+    リダイレクト先の URL 文字列を返すか、 'url' と 'status' と 'exit' をキーに持つ連想配列を
+    返すことができます。 'status' と 'exit' は任意です。
+
 
 .. meta::
     :title lang=ja: Components