translate views

zh/reference/views.rst

@@ -1,18 +1,16 @@
-Using Views
-===========
-Views represent the user interface of your application. Views are often HTML files with embedded PHP code that perform tasks related solely to the
-presentation of the data. Views handle the job of providing data to the web browser or other tool that is used to make requests from your application.
+使用视图(Using Views)
+============================
+视图(Views)代表的就是你应用程序的用户界面。视图通常由HTML文件嵌入PHP代码组成，视图提供了为用户请求把数据输出到浏览器的任务。
 
-The :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` is responsible for the managing the view layer of your MVC application.
+:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 负责管理MVC应用程序中的视图层。
 
-A hierarchy of files is supported by the component. This hierarchy allows for common layout points (commonly used views), as well as controller
-named folders defining respective view templates.
+本组件支持文件的层次结构，这个层次结构允许常用的layout布局，以及使用控制器命名的文件夹名称，定义了各自相应的视图模板。
 
 Integrating Views with Controllers
 ----------------------------------
-Phalcon automatically passes the execution to the view component as soon as a particular controller has completed its cycle. The view component
-will look in the views folder for a folder named as the same name of the last controller executed and then for a file named as the last action
-executed. For instance, if a request is made to the URL *http://127.0.0.1/blog/posts/show/301*, Phalcon will parse the URL as follows:
+Phalcon的视图组件会自动通过执行一个特定的控制器完成它的生命周期。视图组件首先要根据最后的控制器名称找到视图文件目录，
+然后通过最后的Action找到视图文件名，然后输出视图内容。举例，如果一个URL请求是 *http://127.0.0.1/blog/posts/show/301* ，
+Phalcon会这样解析这个URL：
 
 +-------------------+-----------+
 | Server Address    | 127.0.0.1 |
@@ -26,7 +24,7 @@ executed. For instance, if a request is made to the URL *http://127.0.0.1/blog/p
 | Parameter         | 301       |
 +-------------------+-----------+
 
-The dispatcher will look for a "PostsController" and its action "showAction". A simple controller file for this example:
+分发器会寻找一个“PostsController”和它的的Action “showAction”。一个简单的控制器文件例子：
 
 .. code-block:: php
 
@@ -48,11 +46,9 @@ The dispatcher will look for a "PostsController" and its action "showAction". A
 
     }
 
-The setVar allows us to create view variables on demand so that they can be used in the view template. The example above demonstrates
-how to pass the $postId parameter to the respective view template.
+setVar方法允许我们创建视图变量，以便我们可以在视图文件中使用它们。上面的演示告诉我们如何把 $postId 这个参数绑定到视图文件上。
 
-:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` uses PHP itself as the template engine, therefore views should have the .phtml extension.
-If the views directory is  *app/views* then view component will find automatically for these 3 view files.
+:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 使用PHP本身作为模板引擎，因此我们建议使用.phtml作为扩展名。如果视图目录是 *app/views* ，视图组件会自动找到以下3个视图文件。
 
 +-------------------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Name              | File                          | Description                                                                                                                                                                                                              |
@@ -64,8 +60,7 @@ If the views directory is  *app/views* then view component will find automatical
 | Main Layout       | app/views/index.phtml         | This is main action it will be shown for every controller or action executed within the application.                                                                                                                     |
 +-------------------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
-You are not required to implement all of the files mentioned above. :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` will simply move to the
-next view level in the hierarchy of files. If all three view files are implemented, they will be processed as follows:
+你并不必要编写上述提到的所有三个视图文件。 :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 会通过视图文件的层次自动查找下一层的视图文件。如果所有三个视图文件都存在，他们将做如下处理：
 
 .. code-block:: html+php
 
@@ -99,13 +94,12 @@ next view level in the hierarchy of files. If all three view files are implement
         </body>
     </html>
 
-Note the lines where the method *$this->getContent()* was called. This method instructs :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>`
-on where to inject the contents of the previous view executed in the hierarchy. For the example above, the output will be:
+请注意视图文件中调用 *$this->getContent()* 方法的那一行。这个方法的位置决定内容在 :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 的层次结构中的上一个视图的哪个位置显示。上述示例将输出以下内容：
 
 .. figure:: ../_static/img/views-1.png
    :align: center
 
-The generated HTML by the request will be:
+生成的HTML内容如下：
 
 .. code-block:: html+php
 
@@ -131,9 +125,9 @@ The generated HTML by the request will be:
         </body>
     </html>
 
-Using Templates
----------------
-Templates are views that can be used to share common view code. They act as controller layouts, so you need to place them in the layouts directory.
+使用模板(Using Templates)
+---------------------------
+Templates也是视图文件的一部分，但他们是可共享的。他们作为控制器的布局文件，你必须把它们放到layouts目录下。
 
 .. code-block:: php
 
@@ -199,7 +193,7 @@ Templates are views that can be used to share common view code. They act as cont
         <p>This is another post content</p>
     </article>
 
-The final output will be the following:
+最后它们将输出如下的HTML内容：
 
 .. code-block:: html+php
 
@@ -244,11 +238,9 @@ The final output will be the following:
 
 Using Partials
 --------------
-Partial templates are another way of breaking the rendering process into simpler more manageable chunks that can be reused by different
-parts of the application. With a partial, you can move the code for rendering a particular piece of a response to its own file.
+局部模板文件是另一种打破视图渲染顺序的方式，它更易于管理，且可在应用程序中重复使用。
 
-One way to use partials is to treat them as the equivalent of subroutines: as a way to move details out of a view so that your code can be
-more easily understood. For example, you might have a view that looks like this:
+作为局部文件的方式之一可以把它们看作是子程序，把你的视图代码分成多个组成部分，更容易被理解。例如，你可能会有这样的想法，看起来像这样：
 
 .. code-block:: html+php
 
@@ -264,8 +256,7 @@ more easily understood. For example, you might have a view that looks like this:
 
 Transfer values from the controller to views
 --------------------------------------------
-:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` is available in each controller using the view variable ($this->view). You can use that
-object to set variables directly to the view from a controller action by using the setVar() method.
+:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 可以在控制器中使用视图变量($this->view)调用。你可以在控制器的Action中使用该对象的setVar()方法设置变量到视图中。
 
 .. code-block:: php
 
@@ -287,8 +278,7 @@ object to set variables directly to the view from a controller action by using t
 
     }
 
-A variable with the name of the first parameter of setView() will be created in the view, ready to be used. The variable can be of any type,
-from a simple string, integer etc. variable to a more complex structure such as array, collection etc.
+setView()的第一个参数名称是将要在视图文件中使用的，变量可以是任意类型。从字符串，整型数字，到一个更复杂的结构，如数组，集合等都可以。
 
 .. code-block:: html+php
 
@@ -305,10 +295,9 @@ from a simple string, integer etc. variable to a more complex structure such as
 
 Control Rendering Levels
 ------------------------
-As seen above, :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` supports a view hierarchy. You might need to control the level of rendering
-produced by the view component. The method Phalcon\Mvc\\View::setRenderLevel() offers this functionality.
+从以上可以看出，:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 支持视图层次结构。你可能需要在视图中控制显示的层次，Phalcon\Mvc\\View::setRenderLevel() 提供这种功能。
 
-This method can be invoked from the controller or from a superior view layer to interfere with the rendering process.
+此方法可以从控制器或从上级视图层调用改变渲染过程。
 
 .. code-block:: php
 
@@ -359,7 +348,7 @@ The available render levels are:
 
 Using models in the view layer
 ------------------------------
-Application models are always available at the view layer. The :doc:`Phalcon\\Loader <../api/Phalcon_Loader>` will instantiate them at runtime automatically:
+应用程序中的模型是可以在视图中直接使用的，因为 :doc:`Phalcon\\Loader <../api/Phalcon_Loader>` 在运行时会自动初始化它们：
 
 .. code-block:: html+php
 
@@ -373,13 +362,11 @@ Application models are always available at the view layer. The :doc:`Phalcon\\Lo
     ?>
     </div>
 
-Although you may perform model manipulation operations such as insert() or update() in the view layer, it is not recommended since it is not
-possible to forward the execution flow to another controller in the case of an error or an exception.
+虽然你可以在视图中执行模型的各种操作，如insert(),update()等，但不建议这么使用。因为它不可以在发生错误或异常的时候从一个控制流程跳转到另一个控制器。
 
 Picking Views
 -------------
-As mentioned above, when :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` is managed by :doc:`Phalcon\\Mvc\\Application <../api/Phalcon_Mvc_Application>`
-the view rendered is the one related with the last controller and action executed. You could override this by using the Phalcon\\Mvc\\View::pick() method:
+正如上面提示的，:doc:`Phalcon\\Mvc\\Application <../api/Phalcon_Mvc_Application>` 管理 :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 进行视图显示，根据相关联的最一个控制器和action来进行视图文件输出。你也可以通过 Phalcon\\Mvc\\View::pick() 方法改变这个显示流程：
 
 .. code-block:: php
 
@@ -398,12 +385,9 @@ the view rendered is the one related with the last controller and action execute
 
 Caching View Fragments
 ----------------------
-Sometimes when you develop dynamic websites and some areas of them are not updated very often, the output is exactly
-the same between requests. :doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` offers caching a part or the whole
-rendered output to increase performance.
+有时候，当你开发动态网站时，网页上的有一些区域是不经常更新的，他们每次都输出相同的内容。:doc:`Phalcon\\Mvc\\View <../api/Phalcon_Mvc_View>` 提供了一种缓存功能，可以局部缓存，也可以缓存整个页面，以提高性能。
 
-:doc:`Phalcon\\\Mvc\\View <../api/Phalcon_Mvc_View>` integrates with :doc:`Phalcon\\Cache <cache>` to provide an easier way
-to cache output fragments. You could manually set the cache handler or set a global handler:
+:doc:`Phalcon\\\Mvc\\View <../api/Phalcon_Mvc_View>` 集成了 :doc:`Phalcon\\Cache <cache>` ，提供了一种更方便的方法来进行缓存操作。你可以手工设置缓存处理，或设置一个全局的缓存规则：
 
 .. code-block:: php
 
@@ -451,11 +435,10 @@ to cache output fragments. You could manually set the cache handler or set a glo
 
     }
 
-When we do not define a key to the cache, the component automatically creates one doing a md5_ to view name currently rendered.
-It is a good practice to define a key for each action so you can easily identify the cache associated with each view.
+当我们没有为缓存定义一个明确的KEY时，组件会自动创建一个针对视图文件名称 md5_ 的KEY。这样定义KEY的方式是非常不错的做法，因为这样你就可以很容易识别到每个Action与视图缓存的对应文件了。
 
-When the View component needs to cache something it will request a cache service to the services container.
-The service name convention for this service is "viewCache":
+当View组件需要缓存一些内容的时候，它将从服务容器请求cache服务。
+这个服务在服务容器中的命名为"viewCache":
 
 .. code-block:: php
 
@@ -478,37 +461,38 @@ The service name convention for this service is "viewCache":
         return $cache;
     }, true);
 
-When using view caching is also useful to prevent that controllers perform the processes that produce the data to be displayed in the views.
+当使用视图后，如果有缓存，应直接输出缓存内存进行显示，而不要使控制器再次执行获取数据。
 
-To achieve this we must identify uniquely each cache with a key. First we verify that the cache does not exist or has expired to make the
-calculations/queries to display data in the view:
+为了实现这一目标，我们必须使用唯一的缓存KEY。首先，我们要先验证缓存的KEY是否存在或是否已过期，整个过程如下：
 
-<?php
-
-class DownloadController extends Phalcon\Mvc\Controller
-{
-
-    public function indexAction()
-    {
-
-        //Check if the cache with key "downloads" exists or has expired
-        if ($this->view->getCache()->exists('downloads')) {
-
-            //Query the latest downloads
-            $latest = Downloads::find(array('order' => 'created_at DESC'));
-
-            $this->view->setVar('latest', $latest);
-        }
-
-        //Enable the cache with the same key "downloads"
-        $this->view->cache(array('key' => 'downloads'));
-    }
-
-}
+.. code-block:: html+php
 
-Disabling the view
-------------------
-If your controller doesn't produce any output in the view (or not even have one) you may disable the view component avoiding unnecessary processing:
+   <?php
+
+   class DownloadController extends Phalcon\Mvc\Controller
+   {
+
+       public function indexAction()
+       {
+
+           //Check if the cache with key "downloads" exists or has expired
+           if ($this->view->getCache()->exists('downloads')) {
+
+               //Query the latest downloads
+               $latest = Downloads::find(array('order' => 'created_at DESC'));
+
+               $this->view->setVar('latest', $latest);
+           }
+
+           //Enable the cache with the same key "downloads"
+           $this->view->cache(array('key' => 'downloads'));
+       }
+
+   }
+
+禁用视图(Disabling the view)
+------------------------------
+如果您的控制器不产生任何输出，您可以禁用视图组件，避免不必要的处理：
 
 .. code-block:: php
 
@@ -529,8 +513,8 @@ If your controller doesn't produce any output in the view (or not even have one)
 
     }
 
-Template Engines
-----------------
+模板引擎(Template Engines)
+----------------------------------
 Template Engines helps designers to create views without use a complicated syntax. Phalcon includes a powerful and fast templating engine
 called :doc:`Volt <volt>`.