From 256b2e0e07984a1d65ff7c43ee40678c2f930e13 Mon Sep 17 00:00:00 2001 From: dereuromark Date: Thu, 24 Nov 2016 01:29:46 +0100 Subject: [PATCH] Start fixing up ViewBuilder API. Also fixed a few wrong doc blocks. --- src/View/ViewBuilder.php | 354 ++++++++++++++++++++++++++++++++++----- 1 file changed, 310 insertions(+), 44 deletions(-) diff --git a/src/View/ViewBuilder.php b/src/View/ViewBuilder.php index d7e6c3b0708..cabd5caeadb 100644 --- a/src/View/ViewBuilder.php +++ b/src/View/ViewBuilder.php @@ -113,209 +113,475 @@ class ViewBuilder implements JsonSerializable, Serializable */ protected $_helpers = []; + /** + * Sets path for template files. + * + * @param string $path Path for view files. + * @return $this + */ + public function setTemplatePath($path) + { + $this->_templatePath = $path; + + return $this; + } + + /** + * Gets path for template files. + * + * @return string + */ + public function getTemplatePath() + { + return $this->_templatePath; + } + /** * Get/set path for template files. * + * @deprecated 3.4.0 Use setTemplatePath()/getTemplatePath() instead. * @param string|null $path Path for view files. If null returns current path. * @return string|self */ public function templatePath($path = null) { - if ($path === null) { - return $this->_templatePath; + if ($path !== null) { + return $this->setTemplatePath($path); } - $this->_templatePath = $path; + return $this->getTemplatePath(); + } + + /** + * Sets path for layout files. + * + * @param string $path Path for layout files. + * @return $this + */ + public function setLayoutPath($path) + { + $this->_layoutPath = $path; return $this; } + /** + * Gets path for layout files. + * + * @return string + */ + public function getLayoutPath() + { + return $this->_layoutPath; + } + /** * Get/set path for layout files. * + * @deprecated 3.4.0 Use setLayoutPath()/getLayoutPath() instead. * @param string|null $path Path for layout files. If null returns current path. * @return string|self */ public function layoutPath($path = null) { - if ($path === null) { - return $this->_layoutPath; + if ($path !== null) { + return $this->setLayoutPath($path); } - $this->_layoutPath = $path; + return $this->getLayoutPath(); + } + + /** + * Turns on or off CakePHP's conventional mode of applying layout files. + * On by default. Setting to off means that layouts will not be + * automatically applied to rendered views. + * + * @param bool $enable Boolean to turn on/off. + * @return $this + */ + public function enableAutoLayout($enable) + { + $this->_autoLayout = (bool)$enable; return $this; } + /** + * Returns if CakePHP's conventional mode of applying layout files is enabled. + * Disabled means that layouts will not be automatically applied to rendered views. + * + * @return bool + */ + public function isAutoLayoutEnabled() + { + return $this->_autoLayout; + } + /** * Turns on or off CakePHP's conventional mode of applying layout files. * On by default. Setting to off means that layouts will not be * automatically applied to rendered views. * - * @param bool|null $autoLayout Boolean to turn on/off. If null returns current value. + * @deprecated 3.4.0 Use enableAutoLayout()/isAutoLayoutEnabled() instead. + * @param bool|null $enable Boolean to turn on/off. If null returns current value. * @return bool|self */ - public function autoLayout($autoLayout = null) + public function autoLayout($enable = null) { - if ($autoLayout === null) { - return $this->_autoLayout; + if ($enable !== null) { + return $this->enableAutoLayout($enable); } - $this->_autoLayout = (bool)$autoLayout; + return $this->isAutoLayoutEnabled(); + } + + /** + * Sets the plugin name to use. + * + * `False` to remove current plugin name is deprecated as of 3.4.0. Use directly `null` instead. + * + * @param string|null|false $name Plugin name. + * Use null or false to remove the current plugin name. + * @return $this + */ + public function setPlugin($name) + { + $this->_plugin = $name; return $this; } + /** + * Gets the plugin name to use. + * + * @return string + */ + public function getPlugin() + { + return $this->_plugin; + } + /** * The plugin name to use * + * @deprecated 3.4.0 Use setPlugin()/getPlugin() instead. * @param string|null|false $name Plugin name. If null returns current plugin. * Use false to remove the current plugin name. * @return string|self */ public function plugin($name = null) { - if ($name === null) { - return $this->_plugin; + if ($name !== null) { + return $this->setPlugin($name); } - $this->_plugin = $name; + return $this->getPlugin(); + } + + /** + * Sets the helpers to use. + * + * @param array $helpers Helpers to use. + * @param bool $merge Whether or not to merge existing data with the new data. + * @return $this + */ + public function setHelpers(array $helpers, $merge = true) + { + if ($merge) { + $helpers = array_merge($this->_helpers, $helpers); + } + $this->_helpers = $helpers; return $this; } + /** + * Gets the helpers to use. + * + * @return array + */ + public function getHelpers() + { + return $this->_helpers; + } + /** * The helpers to use * + * @deprecated 3.4.0 Use setHelpers()/getHelpers() instead. * @param array|null $helpers Helpers to use. * @param bool $merge Whether or not to merge existing data with the new data. * @return array|self */ public function helpers(array $helpers = null, $merge = true) { - if ($helpers === null) { - return $this->_helpers; - } - if ($merge) { - $helpers = array_merge($this->_helpers, $helpers); + if ($helpers !== null) { + return $this->setHelpers($helpers, $merge); } - $this->_helpers = $helpers; + + return $this->getHelpers(); + } + + /** + * Sets the view theme to use. + * + * `False` to remove current theme is deprecated as of 3.4.0. Use directly `null` instead. + * + * @param string|null|false $theme Theme name. + * Use null or false to remove the current theme. + * @return $this + */ + public function setTheme($theme) + { + $this->_theme = $theme; return $this; } + /** + * Gets the view theme to use. + * + * @return string + */ + public function getTheme() + { + return $this->_theme; + } + /** * The view theme to use. * + * @deprecated 3.4.0 Use setTheme()/getTheme() instead. * @param string|null|false $theme Theme name. If null returns current theme. * Use false to remove the current theme. * @return string|self */ public function theme($theme = null) { - if ($theme === null) { - return $this->_theme; + if ($theme !== null) { + return $this->setTheme($theme); } - $this->_theme = $theme; + return $this->getTheme(); + } + + /** + * Sets the name of the view file to render. The name specified is the + * filename in /src/Template/ without the .ctp extension. + * + * @param string $name View file name to set. + * @return $this + */ + public function setTemplate($name) + { + $this->_template = $name; return $this; } + /** + * Gets the name of the view file to render. The name specified is the + * filename in /src/Template/ without the .ctp extension. + * + * @return string + */ + public function getTemplate() + { + return $this->_template; + } + /** * Get/set the name of the view file to render. The name specified is the * filename in /src/Template/ without the .ctp extension. * + * @deprecated 3.4.0 Use setTemplate()/getTemplate() * @param string|null $name View file name to set. If null returns current name. * @return string|self */ public function template($name = null) { - if ($name === null) { - return $this->_template; + if ($name !== null) { + return $this->setTemplate($name); } - $this->_template = $name; + return $this->getTemplate(); + } + + /** + * Sets the name of the layout file to render the view inside of. + * The name specified is the filename of the layout in /src/Template/Layout + * without the .ctp extension. + * + * @param string $name Layout file name to set. + * @return $this + */ + public function setLayout($name) + { + $this->_layout = $name; return $this; } + /** + * Gets the name of the layout file to render the view inside of. + * + * @return string + */ + public function getLayout() + { + return $this->_layout; + } + /** * Get/set the name of the layout file to render the view inside of. * The name specified is the filename of the layout in /src/Template/Layout * without the .ctp extension. * + * @deprecated 3.4.0 Use setLayout()/getLayout() instead. * @param string|null $name Layout file name to set. If null returns current name. * @return string|self */ public function layout($name = null) { - if ($name === null) { - return $this->_layout; + if ($name !== null) { + return $this->setLayout($name); } - $this->_layout = $name; + return $this->getLayout(); + } + + /** + * Sets additional options for the view. + * + * This lets you provide custom constructor arguments to application/plugin view classes. + * + * @param array $options An array of options. + * @param bool $merge Whether or not to merge existing data with the new data. + * @return $this + */ + public function setOptions(array $options, $merge = true) + { + if ($merge) { + $options = array_merge($this->_options, $options); + } + $this->_options = $options; return $this; } + /** + * Gets additional options for the view. + * + * @return array + */ + public function getOptions() + { + return $this->_options; + } + /** * Set additional options for the view. * * This lets you provide custom constructor arguments to application/plugin view classes. * + * @deprecated 3.4.0 Use setOptions()/getOptions() instead. * @param array|null $options Either an array of options or null to get current options. * @param bool $merge Whether or not to merge existing data with the new data. * @return array|self */ public function options(array $options = null, $merge = true) { - if ($options === null) { - return $this->_options; + if ($options !== null) { + return $this->setOptions($options, $merge); } - if ($merge) { - $options = array_merge($this->_options, $options); - } - $this->_options = $options; + + return $this->getOptions(); + } + + /** + * Sets the view name. + * + * @param string $name The name of the view. + * @return $this + */ + public function setName($name) + { + $this->_name = $name; return $this; } + /** + * Gets the view name. + * + * @return string + */ + public function getName() + { + return $this->_name; + } + /** * Get/set the view name * + * @deprecated 3.4.0 Use setName()/getName() instead. * @param string|null $name The name of the view - * @return array|self + * @return string|self */ public function name($name = null) { - if ($name === null) { - return $this->_name; + if ($name !== null) { + return $this->setName($name); } - $this->_name = $name; + + return $this->getName(); + } + + /** + * Sets the view classname. + * + * Accepts either a short name (Ajax) a plugin name (MyPlugin.Ajax) + * or a fully namespaced name (App\View\AppView). + * + * @param string $name The class name for the view. + * @return $this + */ + public function setClassName($name) + { + $this->_className = $name; return $this; } + /** + * Gets the view classname. + * + * @return string + */ + public function getClassName() + { + return $this->_className; + } + /** * Get/set the view classname. * * Accepts either a short name (Ajax) a plugin name (MyPlugin.Ajax) * or a fully namespaced name (App\View\AppView). * + * @deprecated 3.4.0 Use setClassName()/getClassName() instead. * @param string|null $name The class name for the view. Can * be a plugin.class name reference, a short alias, or a fully * namespaced name. - * @return array|self + * @return string|self */ public function className($name = null) { - if ($name === null) { - return $this->_className; + if ($name !== null) { + return $this->setClassName($name); } - $this->_className = $name; - return $this; + return $this->getClassName(); } /**