* @since 2.0 */ class View extends Component { /** * @event Event an event that is triggered by [[beginPage()]]. */ const EVENT_BEGIN_PAGE = 'beginPage'; /** * @event Event an event that is triggered by [[endPage()]]. */ const EVENT_END_PAGE = 'endPage'; /** * @event Event an event that is triggered by [[beginBody()]]. */ const EVENT_BEGIN_BODY = 'beginBody'; /** * @event Event an event that is triggered by [[endBody()]]. */ const EVENT_END_BODY = 'endBody'; /** * @event ViewEvent an event that is triggered by [[renderFile()]] right before it renders a view file. */ const EVENT_BEFORE_RENDER = 'beforeRender'; /** * @event ViewEvent an event that is triggered by [[renderFile()]] right after it renders a view file. */ const EVENT_AFTER_RENDER = 'afterRender'; /** * The location of registered JavaScript code block or files. * This means the location is in the head section. */ const POS_HEAD = 1; /** * The location of registered JavaScript code block or files. * This means the location is at the beginning of the body section. */ const POS_BEGIN = 2; /** * The location of registered JavaScript code block or files. * This means the location is at the end of the body section. */ const POS_END = 3; /** * The location of registered JavaScript code block. * This means the JavaScript code block will be enclosed within `jQuery(document).ready()`. */ const POS_READY = 4; /** * This is internally used as the placeholder for receiving the content registered for the head section. */ const PH_HEAD = ''; /** * This is internally used as the placeholder for receiving the content registered for the beginning of the body section. */ const PH_BODY_BEGIN = ''; /** * This is internally used as the placeholder for receiving the content registered for the end of the body section. */ const PH_BODY_END = ''; /** * @var object the context under which the [[renderFile()]] method is being invoked. * This can be a controller, a widget, or any other object. */ public $context; /** * @var mixed custom parameters that are shared among view templates. */ public $params = []; /** * @var array a list of available renderers indexed by their corresponding supported file extensions. * Each renderer may be a view renderer object or the configuration for creating the renderer object. * For example, the following configuration enables both Smarty and Twig view renderers: * * ~~~ * [ * 'tpl' => ['class' => 'yii\smarty\ViewRenderer'], * 'twig' => ['class' => 'yii\twig\ViewRenderer'], * ] * ~~~ * * If no renderer is available for the given view file, the view file will be treated as a normal PHP * and rendered via [[renderPhpFile()]]. */ public $renderers; /** * @var Theme|array the theme object or the configuration array for creating the theme object. * If not set, it means theming is not enabled. */ public $theme; /** * @var array a list of named output blocks. The keys are the block names and the values * are the corresponding block content. You can call [[beginBlock()]] and [[endBlock()]] * to capture small fragments of a view. They can be later accessed somewhere else * through this property. */ public $blocks; /** * @var array a list of currently active fragment cache widgets. This property * is used internally to implement the content caching feature. Do not modify it directly. * @internal */ public $cacheStack = []; /** * @var array a list of placeholders for embedding dynamic contents. This property * is used internally to implement the content caching feature. Do not modify it directly. * @internal */ public $dynamicPlaceholders = []; /** * @var AssetBundle[] list of the registered asset bundles. The keys are the bundle names, and the values * are the registered [[AssetBundle]] objects. * @see registerAssetBundle */ public $assetBundles = []; /** * @var string the page title */ public $title; /** * @var array the registered meta tags. * @see registerMetaTag */ public $metaTags; /** * @var array the registered link tags. * @see registerLinkTag */ public $linkTags; /** * @var array the registered CSS code blocks. * @see registerCss */ public $css; /** * @var array the registered CSS files. * @see registerCssFile */ public $cssFiles; /** * @var array the registered JS code blocks * @see registerJs */ public $js; /** * @var array the registered JS files. * @see registerJsFile */ public $jsFiles; /** * Initializes the view component. */ public function init() { parent::init(); if (is_array($this->theme)) { if (!isset($this->theme['class'])) { $this->theme['class'] = 'yii\base\Theme'; } $this->theme = Yii::createObject($this->theme); } } /** * Renders a view. * * This method delegates the call to the [[context]] object: * * - If [[context]] is a controller, the [[Controller::renderPartial()]] method will be called; * - If [[context]] is a widget, the [[Widget::render()]] method will be called; * - Otherwise, an InvalidCallException exception will be thrown. * * @param string $view the view name. Please refer to [[Controller::findViewFile()]] * and [[Widget::findViewFile()]] on how to specify this parameter. * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file. * @return string the rendering result * @throws InvalidCallException if [[context]] is neither a controller nor a widget. * @throws InvalidParamException if the view cannot be resolved or the view file does not exist. * @see renderFile */ public function render($view, $params = []) { if ($this->context instanceof Controller) { return $this->context->renderPartial($view, $params); } elseif ($this->context instanceof Widget) { return $this->context->render($view, $params); } else { throw new InvalidCallException('View::render() is not supported for the current context.'); } } /** * Renders a view file. * * If [[theme]] is enabled (not null), it will try to render the themed version of the view file as long * as it is available. * * The method will call [[FileHelper::localize()]] to localize the view file. * * If [[renderer]] is enabled (not null), the method will use it to render the view file. * Otherwise, it will simply include the view file as a normal PHP file, capture its output and * return it as a string. * * @param string $viewFile the view file. This can be either a file path or a path alias. * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file. * @param object $context the context that the view should use for rendering the view. If null, * existing [[context]] will be used. * @return string the rendering result * @throws InvalidParamException if the view file does not exist */ public function renderFile($viewFile, $params = [], $context = null) { $viewFile = Yii::getAlias($viewFile); if ($this->theme !== null) { $viewFile = $this->theme->applyTo($viewFile); } if (is_file($viewFile)) { $viewFile = FileHelper::localize($viewFile); } else { throw new InvalidParamException("The view file does not exist: $viewFile"); } $oldContext = $this->context; if ($context !== null) { $this->context = $context; } $output = ''; if ($this->beforeRender($viewFile)) { $ext = pathinfo($viewFile, PATHINFO_EXTENSION); if (isset($this->renderers[$ext])) { if (is_array($this->renderers[$ext])) { $this->renderers[$ext] = Yii::createObject($this->renderers[$ext]); } /** @var ViewRenderer $renderer */ $renderer = $this->renderers[$ext]; $output = $renderer->render($this, $viewFile, $params); } else { Yii::trace("Rendering view file: $viewFile", __METHOD__); $output = $this->renderPhpFile($viewFile, $params); } $this->afterRender($viewFile, $output); } $this->context = $oldContext; return $output; } /** * This method is invoked right before [[renderFile()]] renders a view file. * The default implementation will trigger the [[EVENT_BEFORE_RENDER]] event. * If you override this method, make sure you call the parent implementation first. * @param string $viewFile the view file to be rendered * @return boolean whether to continue rendering the view file. */ public function beforeRender($viewFile) { $event = new ViewEvent($viewFile); $this->trigger(self::EVENT_BEFORE_RENDER, $event); return $event->isValid; } /** * This method is invoked right after [[renderFile()]] renders a view file. * The default implementation will trigger the [[EVENT_AFTER_RENDER]] event. * If you override this method, make sure you call the parent implementation first. * @param string $viewFile the view file to be rendered * @param string $output the rendering result of the view file. Updates to this parameter * will be passed back and returned by [[renderFile()]]. */ public function afterRender($viewFile, &$output) { if ($this->hasEventHandlers(self::EVENT_AFTER_RENDER)) { $event = new ViewEvent($viewFile); $event->output = $output; $this->trigger(self::EVENT_AFTER_RENDER, $event); $output = $event->output; } } /** * Renders a view file as a PHP script. * * This method treats the view file as a PHP script and includes the file. * It extracts the given parameters and makes them available in the view file. * The method captures the output of the included view file and returns it as a string. * * This method should mainly be called by view renderer or [[renderFile()]]. * * @param string $_file_ the view file. * @param array $_params_ the parameters (name-value pairs) that will be extracted and made available in the view file. * @return string the rendering result */ public function renderPhpFile($_file_, $_params_ = []) { ob_start(); ob_implicit_flush(false); extract($_params_, EXTR_OVERWRITE); require($_file_); return ob_get_clean(); } /** * Renders dynamic content returned by the given PHP statements. * This method is mainly used together with content caching (fragment caching and page caching) * when some portions of the content (called *dynamic content*) should not be cached. * The dynamic content must be returned by some PHP statements. * @param string $statements the PHP statements for generating the dynamic content. * @return string the placeholder of the dynamic content, or the dynamic content if there is no * active content cache currently. */ public function renderDynamic($statements) { if (!empty($this->cacheStack)) { $n = count($this->dynamicPlaceholders); $placeholder = ""; $this->addDynamicPlaceholder($placeholder, $statements); return $placeholder; } else { return $this->evaluateDynamicContent($statements); } } /** * Adds a placeholder for dynamic content. * This method is internally used. * @param string $placeholder the placeholder name * @param string $statements the PHP statements for generating the dynamic content */ public function addDynamicPlaceholder($placeholder, $statements) { foreach ($this->cacheStack as $cache) { $cache->dynamicPlaceholders[$placeholder] = $statements; } $this->dynamicPlaceholders[$placeholder] = $statements; } /** * Evaluates the given PHP statements. * This method is mainly used internally to implement dynamic content feature. * @param string $statements the PHP statements to be evaluated. * @return mixed the return value of the PHP statements. */ public function evaluateDynamicContent($statements) { return eval($statements); } /** * Begins recording a block. * This method is a shortcut to beginning [[Block]] * @param string $id the block ID. * @param boolean $renderInPlace whether to render the block content in place. * Defaults to false, meaning the captured block will not be displayed. * @return Block the Block widget instance */ public function beginBlock($id, $renderInPlace = false) { return Block::begin([ 'id' => $id, 'renderInPlace' => $renderInPlace, 'view' => $this, ]); } /** * Ends recording a block. */ public function endBlock() { Block::end(); } /** * Begins the rendering of content that is to be decorated by the specified view. * This method can be used to implement nested layout. For example, a layout can be embedded * in another layout file specified as '@app/view/layouts/base.php' like the following: * * ~~~ * beginContent('@app/view/layouts/base.php'); ?> * ...layout content here... * endContent(); ?> * ~~~ * * @param string $viewFile the view file that will be used to decorate the content enclosed by this widget. * This can be specified as either the view file path or path alias. * @param array $params the variables (name => value) to be extracted and made available in the decorative view. * @return ContentDecorator the ContentDecorator widget instance * @see ContentDecorator */ public function beginContent($viewFile, $params = []) { return ContentDecorator::begin([ 'viewFile' => $viewFile, 'params' => $params, 'view' => $this, ]); } /** * Ends the rendering of content. */ public function endContent() { ContentDecorator::end(); } /** * Begins fragment caching. * This method will display cached content if it is available. * If not, it will start caching and would expect an [[endCache()]] * call to end the cache and save the content into cache. * A typical usage of fragment caching is as follows, * * ~~~ * if ($this->beginCache($id)) { * // ...generate content here * $this->endCache(); * } * ~~~ * * @param string $id a unique ID identifying the fragment to be cached. * @param array $properties initial property values for [[FragmentCache]] * @return boolean whether you should generate the content for caching. * False if the cached version is available. */ public function beginCache($id, $properties = []) { $properties['id'] = $id; $properties['view'] = $this; /** @var $cache FragmentCache */ $cache = FragmentCache::begin($properties); if ($cache->getCachedContent() !== false) { $this->endCache(); return false; } else { return true; } } /** * Ends fragment caching. */ public function endCache() { FragmentCache::end(); } private $_assetManager; /** * Registers the asset manager being used by this view object. * @return \yii\web\AssetManager the asset manager. Defaults to the "assetManager" application component. */ public function getAssetManager() { return $this->_assetManager ?: Yii::$app->getAssetManager(); } /** * Sets the asset manager. * @param \yii\web\AssetManager $value the asset manager */ public function setAssetManager($value) { $this->_assetManager = $value; } /** * Marks the beginning of an HTML page. */ public function beginPage() { ob_start(); ob_implicit_flush(false); $this->trigger(self::EVENT_BEGIN_PAGE); } /** * Marks the ending of an HTML page. */ public function endPage() { $this->trigger(self::EVENT_END_PAGE); $content = ob_get_clean(); foreach(array_keys($this->assetBundles) as $bundle) { $this->registerAssetFiles($bundle); } echo strtr($content, [ self::PH_HEAD => $this->renderHeadHtml(), self::PH_BODY_BEGIN => $this->renderBodyBeginHtml(), self::PH_BODY_END => $this->renderBodyEndHtml(), ]); unset( $this->metaTags, $this->linkTags, $this->css, $this->cssFiles, $this->js, $this->jsFiles ); } /** * Registers all files provided by an asset bundle including depending bundles files. * Removes a bundle from [[assetBundles]] once files are registered. * @param string $name name of the bundle to register */ private function registerAssetFiles($name) { if (!isset($this->assetBundles[$name])) { return; } $bundle = $this->assetBundles[$name]; foreach($bundle->depends as $dep) { $this->registerAssetFiles($dep); } $bundle->registerAssetFiles($this); unset($this->assetBundles[$name]); } /** * Marks the beginning of an HTML body section. */ public function beginBody() { echo self::PH_BODY_BEGIN; $this->trigger(self::EVENT_BEGIN_BODY); } /** * Marks the ending of an HTML body section. */ public function endBody() { $this->trigger(self::EVENT_END_BODY); echo self::PH_BODY_END; } /** * Marks the position of an HTML head section. */ public function head() { echo self::PH_HEAD; } /** * Registers the named asset bundle. * All dependent asset bundles will be registered. * @param string $name the name of the asset bundle. * @param integer|null $position if set, this forces a minimum position for javascript files. * This will adjust depending assets javascript file position or fail if requirement can not be met. * If this is null, asset bundles position settings will not be changed. * See [[registerJsFile]] for more details on javascript position. * @return AssetBundle the registered asset bundle instance * @throws InvalidConfigException if the asset bundle does not exist or a circular dependency is detected */ public function registerAssetBundle($name, $position = null) { if (!isset($this->assetBundles[$name])) { $am = $this->getAssetManager(); $bundle = $am->getBundle($name); $this->assetBundles[$name] = false; // register dependencies $pos = isset($bundle->jsOptions['position']) ? $bundle->jsOptions['position'] : null; foreach ($bundle->depends as $dep) { $this->registerAssetBundle($dep, $pos); } $this->assetBundles[$name] = $bundle; } elseif ($this->assetBundles[$name] === false) { throw new InvalidConfigException("A circular dependency is detected for bundle '$name'."); } else { $bundle = $this->assetBundles[$name]; } if ($position !== null) { $pos = isset($bundle->jsOptions['position']) ? $bundle->jsOptions['position'] : null; if ($pos === null) { $bundle->jsOptions['position'] = $pos = $position; } elseif ($pos > $position) { throw new InvalidConfigException("An asset bundle that depends on '$name' has a higher javascript file position configured than '$name'."); } // update position for all dependencies foreach ($bundle->depends as $dep) { $this->registerAssetBundle($dep, $pos); } } return $bundle; } /** * Registers a meta tag. * @param array $options the HTML attributes for the meta tag. * @param string $key the key that identifies the meta tag. If two meta tags are registered * with the same key, the latter will overwrite the former. If this is null, the new meta tag * will be appended to the existing ones. */ public function registerMetaTag($options, $key = null) { if ($key === null) { $this->metaTags[] = Html::tag('meta', '', $options); } else { $this->metaTags[$key] = Html::tag('meta', '', $options); } } /** * Registers a link tag. * @param array $options the HTML attributes for the link tag. * @param string $key the key that identifies the link tag. If two link tags are registered * with the same key, the latter will overwrite the former. If this is null, the new link tag * will be appended to the existing ones. */ public function registerLinkTag($options, $key = null) { if ($key === null) { $this->linkTags[] = Html::tag('link', '', $options); } else { $this->linkTags[$key] = Html::tag('link', '', $options); } } /** * Registers a CSS code block. * @param string $css the CSS code block to be registered * @param array $options the HTML attributes for the style tag. * @param string $key the key that identifies the CSS code block. If null, it will use * $css as the key. If two CSS code blocks are registered with the same key, the latter * will overwrite the former. */ public function registerCss($css, $options = [], $key = null) { $key = $key ?: md5($css); $this->css[$key] = Html::style($css, $options); } /** * Registers a CSS file. * @param string $url the CSS file to be registered. * @param array $options the HTML attributes for the link tag. * @param string $key the key that identifies the CSS script file. If null, it will use * $url as the key. If two CSS files are registered with the same key, the latter * will overwrite the former. */ public function registerCssFile($url, $options = [], $key = null) { $key = $key ?: $url; $this->cssFiles[$key] = Html::cssFile($url, $options); } /** * Registers a JS code block. * @param string $js the JS code block to be registered * @param integer $position the position at which the JS script tag should be inserted * in a page. The possible values are: * * - [[POS_HEAD]]: in the head section * - [[POS_BEGIN]]: at the beginning of the body section * - [[POS_END]]: at the end of the body section * - [[POS_READY]]: enclosed within jQuery(document).ready(). This is the default value. * Note that by using this position, the method will automatically register the jQuery js file. * * @param string $key the key that identifies the JS code block. If null, it will use * $js as the key. If two JS code blocks are registered with the same key, the latter * will overwrite the former. */ public function registerJs($js, $position = self::POS_READY, $key = null) { $key = $key ?: md5($js); $this->js[$position][$key] = $js; if ($position === self::POS_READY) { JqueryAsset::register($this); } } /** * Registers a JS file. * Please note that when this file depends on other JS files to be registered before, * for example jQuery, you should use [[registerAssetBundle]] instead. * @param string $url the JS file to be registered. * @param array $options the HTML attributes for the script tag. A special option * named "position" is supported which specifies where the JS script tag should be inserted * in a page. The possible values of "position" are: * * - [[POS_HEAD]]: in the head section * - [[POS_BEGIN]]: at the beginning of the body section * - [[POS_END]]: at the end of the body section. This is the default value. * * @param string $key the key that identifies the JS script file. If null, it will use * $url as the key. If two JS files are registered with the same key, the latter * will overwrite the former. */ public function registerJsFile($url, $options = [], $key = null) { $position = isset($options['position']) ? $options['position'] : self::POS_END; unset($options['position']); $key = $key ?: $url; $this->jsFiles[$position][$key] = Html::jsFile($url, $options); } /** * Renders the content to be inserted in the head section. * The content is rendered using the registered meta tags, link tags, CSS/JS code blocks and files. * @return string the rendered content */ protected function renderHeadHtml() { $lines = []; if (!empty($this->metaTags)) { $lines[] = implode("\n", $this->metaTags); } $request = Yii::$app->getRequest(); if ($request instanceof \yii\web\Request && $request->enableCsrfValidation) { $lines[] = Html::tag('meta', '', ['name' => 'csrf-var', 'content' => $request->csrfVar]); $lines[] = Html::tag('meta', '', ['name' => 'csrf-token', 'content' => $request->getCsrfToken()]); } if (!empty($this->linkTags)) { $lines[] = implode("\n", $this->linkTags); } if (!empty($this->cssFiles)) { $lines[] = implode("\n", $this->cssFiles); } if (!empty($this->css)) { $lines[] = implode("\n", $this->css); } if (!empty($this->jsFiles[self::POS_HEAD])) { $lines[] = implode("\n", $this->jsFiles[self::POS_HEAD]); } if (!empty($this->js[self::POS_HEAD])) { $lines[] = Html::script(implode("\n", $this->js[self::POS_HEAD]), ['type' => 'text/javascript']); } return empty($lines) ? '' : implode("\n", $lines); } /** * Renders the content to be inserted at the beginning of the body section. * The content is rendered using the registered JS code blocks and files. * @return string the rendered content */ protected function renderBodyBeginHtml() { $lines = []; if (!empty($this->jsFiles[self::POS_BEGIN])) { $lines[] = implode("\n", $this->jsFiles[self::POS_BEGIN]); } if (!empty($this->js[self::POS_BEGIN])) { $lines[] = Html::script(implode("\n", $this->js[self::POS_BEGIN]), ['type' => 'text/javascript']); } return empty($lines) ? '' : implode("\n", $lines); } /** * Renders the content to be inserted at the end of the body section. * The content is rendered using the registered JS code blocks and files. * @return string the rendered content */ protected function renderBodyEndHtml() { $lines = []; if (!empty($this->jsFiles[self::POS_END])) { $lines[] = implode("\n", $this->jsFiles[self::POS_END]); } if (!empty($this->js[self::POS_END])) { $lines[] = Html::script(implode("\n", $this->js[self::POS_END]), ['type' => 'text/javascript']); } if (!empty($this->js[self::POS_READY])) { $js = "jQuery(document).ready(function(){\n" . implode("\n", $this->js[self::POS_READY]) . "\n});"; $lines[] = Html::script($js, ['type' => 'text/javascript']); } return empty($lines) ? '' : implode("\n", $lines); } }