Yii源码阅读笔记（二十）

  1   /**
  2      * Begins recording a block.
  3      * This method is a shortcut to beginning [[Block]]
  4      * 数据块开始的标记，该方法是开始[Block]的快捷方式
  5      * 数据块可以在一个地方指定视图内容在另一个地方显示，通常和布局一起使用
  6      * @param string $id the block ID.
  7      * @param boolean $renderInPlace whether to render the block content in place.
  8      * Defaults to false, meaning the captured block will not be displayed.
  9      * @return Block the Block widget instance
 10      */
 11     public function beginBlock($id, $renderInPlace = false)
 12     {
 13         return Block::begin([
 14             ‘id‘ => $id,//数据块唯一标识
 15             ‘renderInPlace‘ => $renderInPlace,//是否显示标记，默认false不显示
 16             ‘view‘ => $this,
 17         ]);
 18     }
 19 
 20     /**
 21      * Ends recording a block.
 22      * 数据块结束的标记
 23      */
 24     public function endBlock()
 25     {
 26         Block::end();
 27     }
 28 
 29     /**
 30      * Begins the rendering of content that is to be decorated by the specified view.
 31      * 开始用指定的view渲染内容，该方法用来实现嵌套布局，传入的第一个参数为布局文件的路径
 32      * This method can be used to implement nested layout. For example, a layout can be embedded
 33      * in another layout file specified as ‘@app/views/layouts/base.php‘ like the following:
 34      *
 35      * ```php
 36      * <?php $this->beginContent(‘@app/views/layouts/base.php‘); ?>
 37      * //...layout content here...
 38      * <?php $this->endContent(); ?>
 39      * ```
 40      *
 41      * @param string $viewFile the view file that will be used to decorate the content enclosed by this widget.
 42      * This can be specified as either the view file path or path alias.
 43      * @param string $viewFile 布局文件
 44      * @param array $params the variables (name => value) to be extracted and made available in the decorative view.
 45      * @param array $params 布局view文件的参数
 46      * @return ContentDecorator the ContentDecorator widget instance
 47      * @see ContentDecorator
 48      */
 49     public function beginContent($viewFile, $params = [])
 50     {
 51         return ContentDecorator::begin([
 52             ‘viewFile‘ => $viewFile,
 53             ‘params‘ => $params,
 54             ‘view‘ => $this,
 55         ]);
 56     }
 57 
 58     /**
 59      * Ends the rendering of content.
 60      * 结束渲染内容
 61      */
 62     public function endContent()
 63     {
 64         ContentDecorator::end();
 65     }
 66 
 67     /**
 68      * Begins fragment caching.
 69      * 开始片段缓存
 70      * This method will display cached content if it is available.
 71      * 该方法将展示可用的缓存内容，否则将开始缓存内容直到出现[endCache()]方法
 72      * If not, it will start caching and would expect an [[endCache()]]
 73      * call to end the cache and save the content into cache.
 74      * A typical usage of fragment caching is as follows,
 75      * 使用缓存的典型例子如下：
 76      * ```php
 77      * if ($this->beginCache($id)) {
 78      *     // ...generate content here
 79      *     $this->endCache();
 80      * }
 81      * ```
 82      *
 83      * @param string $id a unique ID identifying the fragment to be cached.
 84      * @param array $properties initial property values for [[FragmentCache]]
 85      * @return boolean whether you should generate the content for caching.
 86      * False if the cached version is available.
 87      */
 88     public function beginCache($id, $properties = [])
 89     {
 90         $properties[‘id‘] = $id;//缓存唯一标识
 91         $properties[‘view‘] = $this;
 92         /* @var $cache FragmentCache */
 93         $cache = FragmentCache::begin($properties);
 94         if ($cache->getCachedContent() !== false) {//如果从缓存中读取到了缓存的内容，则渲染内容并返回 false，因此将跳过内容生成逻辑，不再进行缓存
 95             $this->endCache();
 96 
 97             return false;
 98         } else {
 99             return true;
100         }
101     }
102 
103     /**
104      * Ends fragment caching.
105      * 结束片段缓存
106      */
107     public function endCache()
108     {
109         FragmentCache::end();
110     }
111 
112     /**
113      * Marks the beginning of a page.
114      * 页面开始标记--用于生成页面布局文件
115      */
116     public function beginPage()
117     {
118         ob_start();
119         ob_implicit_flush(false);
120 
121         $this->trigger(self::EVENT_BEGIN_PAGE);
122     }
123 
124     /**
125      * Marks the ending of a page.
126      * 页面结束标记--用于生成页面布局文件
127      */
128     public function endPage()
129     {
130         $this->trigger(self::EVENT_END_PAGE);
131         ob_end_flush();
132     }