<?php /** * @link http://www.yiiframework.com/ * @copyright Copyright (c) 2008 Yii Software LLC * @license http://www.yiiframework.com/license/ */ namespace yii\base; use Yii; use yii\helpers\FileHelper; /** * Theme represents an application theme. * * When [[View]] renders a view file, it will check the [[Application::theme|active theme]] * to see if there is a themed version of the view file exists. If so, the themed version will be rendered instead. * * A theme is a directory consisting of view files which are meant to replace their non-themed counterparts. * * Theme uses [[pathMap]] to achieve the view file replacement: * * 1. It first looks for a key in [[pathMap]] that is a substring of the given view file path; * 2. If such a key exists, the corresponding value will be used to replace the corresponding part * in the view file path; * 3. It will then check if the updated view file exists or not. If so, that file will be used * to replace the original view file. * 4. If Step 2 or 3 fails, the original view file will be used. * * For example, if [[pathMap]] is `['/web/views' => '/web/themes/basic']`, * then the themed version for a view file `/web/views/site/index.php` will be * `/web/themes/basic/site/index.php`. * * It is possible to map a single path to multiple paths. For example, * * ~~~ * 'pathMap' => [ * '/web/views' => [ * '/web/themes/christmas', * '/web/themes/basic', * ], * ] * ~~~ * * In this case, the themed version could be either `/web/themes/christmas/site/index.php` or * `/web/themes/basic/site/index.php`. The former has precedence over the latter if both files exist. * * To use a theme, you should configure the [[View::theme|theme]] property of the "view" application * component like the following: * * ~~~ * 'view' => [ * 'theme' => [ * 'basePath' => '@webroot/themes/basic', * 'baseUrl' => '@web/themes/basic', * ], * ], * ~~~ * * The above configuration specifies a theme located under the "themes/basic" directory of the Web folder * that contains the entry script of the application. If your theme is designed to handle modules, * you may configure the [[pathMap]] property like described above. * * @author Qiang Xue <qiang.xue@gmail.com> * @since 2.0 */ class Theme extends Component { /** * @var string the root path or path alias of this theme. All resources of this theme are located * under this directory. This property must be set if [[pathMap]] is not set. * @see pathMap */ public $basePath; /** * @var string the base URL (or path alias) for this theme. All resources of this theme are considered * to be under this base URL. This property must be set. It is mainly used by [[getUrl()]]. */ public $baseUrl; /** * @var array the mapping between view directories and their corresponding themed versions. * If not set, it will be initialized as a mapping from [[Application::basePath]] to [[basePath]]. * This property is used by [[applyTo()]] when a view is trying to apply the theme. * Path aliases can be used when specifying directories. */ public $pathMap; /** * Initializes the theme. * @throws InvalidConfigException if [[basePath]] is not set. */ public function init() { parent::init(); if (empty($this->pathMap)) { if ($this->basePath !== null) { $this->basePath = Yii::getAlias($this->basePath); $this->pathMap = [Yii::$app->getBasePath() => [$this->basePath]]; } else { throw new InvalidConfigException('The "basePath" property must be set.'); } } $paths = []; foreach ($this->pathMap as $from => $tos) { $from = FileHelper::normalizePath(Yii::getAlias($from)); foreach ((array)$tos as $to) { $to = FileHelper::normalizePath(Yii::getAlias($to)); $paths[$from . DIRECTORY_SEPARATOR][] = $to . DIRECTORY_SEPARATOR; } } $this->pathMap = $paths; if ($this->baseUrl === null) { throw new InvalidConfigException('The "baseUrl" property must be set.'); } else { $this->baseUrl = rtrim(Yii::getAlias($this->baseUrl), '/'); } } /** * Converts a file to a themed file if possible. * If there is no corresponding themed file, the original file will be returned. * @param string $path the file to be themed * @return string the themed file, or the original file if the themed version is not available. */ public function applyTo($path) { $path = FileHelper::normalizePath($path); foreach ($this->pathMap as $from => $tos) { if (strpos($path, $from) === 0) { $n = strlen($from); foreach ($tos as $to) { $file = $to . substr($path, $n); if (is_file($file)) { return $file; } } } } return $path; } /** * Converts a relative URL into an absolute URL using [[baseUrl]]. * @param string $url the relative URL to be converted. * @return string the absolute URL */ public function getUrl($url) { return $this->baseUrl . '/' . ltrim($url, '/'); } }