1 php 2 /** 3 * @link http://www.yiiframework.com/ 4 * @copyright copyright (c) 2008 yii software llc 5 * @license http://www.yiiframework.com/license/ 6 */ 7 8 namespace yii\base; 9 10 use yii; 11 use yii\helpers\filehelper; 12 13 /** 14 * theme represents an application theme. 15 * theme 类，应用的主题 16 * when [[view]] renders a view file, it will check the [[view::theme|active theme]] 17 * to see if there is a themed version of the view file exists. if so, the themed version will be rendered instead. 18 * 视图对象[[view]]渲染视图文件的时候，会检查视图的主题是否存在，如果存在则渲染主题取代默认样式 19 * a theme is a directory consisting of view files which are meant to replace their non-themed counterparts. 20 * 21 * theme uses [[pathmap]] to achieve the view file replacement: 22 * 23 * 1. it first looks for a key in [[pathmap]] that is a substring of the given view file path; 24 * 首先查找关键字，关键字是一个给定的视图路径的字符串 25 * 2. if such a key exists, the corresponding value will be used to replace the corresponding part 26 * in the view file path;关键字存在，则用对应值替换给定的视图文件路径中对应的部分 27 * 3. it will then check if the updated view file exists or not. if so, that file will be used 28 * to replace the original view file.检查替换后的路径对应的文件是否存在，存在就替换原文件 29 * 4. if step 2 or 3 fails, the original view file will be used. 30 * 2和3失败的话，返回原来的路径 31 * for example, if [[pathmap]] is `['@app/views' => '@app/themes/basic']`, 32 * then the themed version for a view file `@app/views/site/index.php` will be 33 * `@app/themes/basic/site/index.php`. 34 * 35 * it is possible to map a single path to multiple paths. for example, 36 * 37 * ~~~ 38 * 'pathmap' => [ 39 * '@app/views' => [ 40 * '@app/themes/christmas', 41 * '@app/themes/basic', 42 * ], 43 * ] 44 * ~~~ 45 * 46 * in this case, the themed version could be either `@app/themes/christmas/site/index.php` or 47 * `@app/themes/basic/site/index.php`. the former has precedence over the latter if both files exist. 48 * 49 * to use a theme, you should configure the [[view::theme|theme]] property of the view application 50 * component like the following: 51 * 52 * ~~~ 53 * 'view' => [ 54 * 'theme' => [ 55 * 'basepath' => '@app/themes/basic', 56 * 'baseurl' => '@web/themes/basic', 57 * ], 58 * ], 59 * ~~~ 60 * 61 * the above configuration specifies a theme located under the themes/basic directory of the web folder 62 * that contains the entry script of the application. if your theme is designed to handle modules, 63 * you may configure the [[pathmap]] property like described above. 64 * 65 * @property string $basepath the root path of this theme. all resources of this theme are located under this 66 * directory. 67 * @property string $baseurl the base url (without ending slash) for this theme. all resources of this theme 68 * are considered to be under this base url. this property is read-only. 69 * 70 * @author qiang xue 71 * @since 2.0 72 */ 73 class theme extends component 74 { 75 /** 76 * @var array the mapping between view directories and their corresponding themed versions. 77 * this property is used by [[applyto()]] when a view is trying to apply the theme. 78 * path aliases can be used when specifying directories. 79 * 路径映射属性 设置替换映射关系 80 * if this property is empty or not set, a mapping [[application::basepath]] to [[basepath]] will be used. 81 */ 82 public $pathmap; 83 84 private $_baseurl;//设置要访问资源的url 85 86 /** 87 * @return string the base url (without ending slash) for this theme. all resources of this theme are considered 88 * to be under this base url. 返回当前主题的基础链接，其他资源都在链接里 89 */ 90 public function getbaseurl() 91 { 92 return $this->_baseurl; 93 } 94 95 /** 96 * @param $url string the base url or path alias for this theme. all resources of this theme are considered 97 * to be under this base url. 设置基础链接 98 */ 99 public function setbaseurl($url)100 {101 $this->_baseurl = rtrim(yii::getalias($url), '/');102 }103 104 private $_basepath;//根路径105 106 /**107 * @return string the root path of this theme. all resources of this theme are located under this directory.108 * 得到当前主题的根路径109 * @see pathmap110 */111 public function getbasepath()112 {113 return $this->_basepath;114 }115 116 /**117 * @param string $path the root path or path alias of this theme. all resources of this theme are located118 * under this directory. 设置当前主题根路径119 * @see pathmap120 */121 public function setbasepath($path)122 {123 $this->_basepath = yii::getalias($path);124 }125 126 /**127 * converts a file to a themed file if possible. 将一个文件替换主题文件128 * if there is no corresponding themed file, the original file will be returned.129 * 没有相应的主题文件，返回原文件。130 * @param string $path the file to be themed131 * @return string the themed file, or the original file if the themed version is not available.132 * @throws invalidconfigexception if [[basepath]] is not set133 */134 public function applyto($path)135 {136 $pathmap = $this->pathmap; //取得路径映射137 if (empty($pathmap)) {//没有设置值 抛出异常138 if (($basepath = $this->getbasepath()) === null) {139 throw new invalidconfigexception('the basepath property must be set.');140 }141 //设置值为[模块根路径=>主题根路径]的形式142 $pathmap = [yii::$app->getbasepath() => [$basepath]];143 }144 145 $path = filehelper::normalizepath($path);//对路径中的/.\进行统一146 147 foreach ($pathmap as $from => $tos) {148 //映射数组中的来源149 $from = filehelper::normalizepath(yii::getalias($from)) . directory_separator;150 if (strpos($path, $from) === 0) {//如果在$path中有可替换的旧值151 $n = strlen($from);152 foreach ((array) $tos as $to) {153 $to = filehelper::normalizepath(yii::getalias($to)) . directory_separator;154 $file = $to . substr($path, $n);//把$path中的$from替换为$to155 if (is_file($file)) {156 return $file; //是文件直接返回157 }158 }159 }160 }161 162 return $path;163 }164 165 /**166 * converts a relative url into an absolute url using [[baseurl]].167 * 将一个相对url转换为绝对url168 * @param string $url the relative url to be converted.要转换的相对url169 * @return string the absolute url 替换后的绝对url170 * @throws invalidconfigexception if [[baseurl]] is not set171 */172 public function geturl($url)173 {174 if (($baseurl = $this->getbaseurl()) !== null) {//url存在，进行转换175 return $baseurl . '/' . ltrim($url, '/');176 } else {//不存在抛出异常177 throw new invalidconfigexception('the baseurl property must be set.');178 }179 }180 181 /**182 * converts a relative file path into an absolute one using [[basepath]].183 * 通过相对路径生成绝对路径184 * @param string $path the relative file path to be converted. 要转换的相对文件路径。185 * @return string the absolute file path 转换后的绝对路径186 * @throws invalidconfigexception if [[baseurl]] is not set187 */188 public function getpath($path)189 {190 if (($basepath = $this->getbasepath()) !== null) {191 //返回拼接的路径192 return $basepath . directory_separator . ltrim($path, '/\\');193 } else {194 throw new invalidconfigexception('the basepath property must be set.');195 }196 }197 }