[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2012 Open Source Matters, Inc. <https://www.joomla.org>
   7   * @license    GNU General Public License version 2 or later; see LICENSE.txt
   8   */
   9  
  10  namespace Joomla\CMS\Layout;
  11  
  12  use Joomla\Registry\Registry;
  13  
  14  // phpcs:disable PSR1.Files.SideEffects
  15  \defined('JPATH_PLATFORM') or die;
  16  // phpcs:enable PSR1.Files.SideEffects
  17  
  18  /**
  19   * Base class for rendering a display layout
  20   *
  21   * @link   https://docs.joomla.org/Special:MyLanguage/Sharing_layouts_across_views_or_extensions_with_JLayout
  22   * @since  3.0
  23   */
  24  class BaseLayout implements LayoutInterface
  25  {
  26      /**
  27       * Options object
  28       *
  29       * @var    Registry
  30       * @since  3.2
  31       */
  32      protected $options = null;
  33  
  34      /**
  35       * Data for the layout
  36       *
  37       * @var    array
  38       * @since  3.5
  39       */
  40      protected $data = array();
  41  
  42      /**
  43       * Debug information messages
  44       *
  45       * @var    array
  46       * @since  3.2
  47       */
  48      protected $debugMessages = array();
  49  
  50      /**
  51       * Set the options
  52       *
  53       * @param   array|Registry  $options  Array / Registry object with the options to load
  54       *
  55       * @return  BaseLayout  Instance of $this to allow chaining.
  56       *
  57       * @since   3.2
  58       */
  59      public function setOptions($options = null)
  60      {
  61          // Received Registry
  62          if ($options instanceof Registry) {
  63              $this->options = $options;
  64          } elseif (\is_array($options)) {
  65              // Received array
  66              $this->options = new Registry($options);
  67          } else {
  68              $this->options = new Registry();
  69          }
  70  
  71          return $this;
  72      }
  73  
  74      /**
  75       * Get the options
  76       *
  77       * @return  Registry  Object with the options
  78       *
  79       * @since   3.2
  80       */
  81      public function getOptions()
  82      {
  83          // Always return a Registry instance
  84          if (!($this->options instanceof Registry)) {
  85              $this->resetOptions();
  86          }
  87  
  88          return $this->options;
  89      }
  90  
  91      /**
  92       * Function to empty all the options
  93       *
  94       * @return  BaseLayout  Instance of $this to allow chaining.
  95       *
  96       * @since   3.2
  97       */
  98      public function resetOptions()
  99      {
 100          return $this->setOptions(null);
 101      }
 102  
 103      /**
 104       * Method to escape output.
 105       *
 106       * @param   string  $output  The output to escape.
 107       *
 108       * @return  string  The escaped output.
 109       *
 110       * @note the ENT_COMPAT flag was replaced by ENT_QUOTES in Joomla 4.0 to also escape single quotes
 111       *
 112       * @since   3.0
 113       */
 114      public function escape($output)
 115      {
 116          return $output === null ? '' : htmlspecialchars($output, ENT_QUOTES, 'UTF-8');
 117      }
 118  
 119      /**
 120       * Get the debug messages array
 121       *
 122       * @return  array
 123       *
 124       * @since   3.2
 125       */
 126      public function getDebugMessages()
 127      {
 128          return $this->debugMessages;
 129      }
 130  
 131      /**
 132       * Method to render the layout.
 133       *
 134       * @param   array  $displayData  Array of properties available for use inside the layout file to build the displayed output
 135       *
 136       * @return  string  The necessary HTML to display the layout
 137       *
 138       * @since   3.0
 139       */
 140      public function render($displayData)
 141      {
 142          // Automatically merge any previously data set if $displayData is an array
 143          if (\is_array($displayData)) {
 144              $displayData = array_merge($this->data, $displayData);
 145          }
 146  
 147          return '';
 148      }
 149  
 150      /**
 151       * Render the list of debug messages
 152       *
 153       * @return  string  Output text/HTML code
 154       *
 155       * @since   3.2
 156       */
 157      public function renderDebugMessages()
 158      {
 159          return implode("\n", $this->debugMessages);
 160      }
 161  
 162      /**
 163       * Add a debug message to the debug messages array
 164       *
 165       * @param   string  $message  Message to save
 166       *
 167       * @return  self
 168       *
 169       * @since   3.2
 170       */
 171      public function addDebugMessage($message)
 172      {
 173          $this->debugMessages[] = $message;
 174  
 175          return $this;
 176      }
 177  
 178      /**
 179       * Clear the debug messages array
 180       *
 181       * @return  self
 182       *
 183       * @since   3.5
 184       */
 185      public function clearDebugMessages()
 186      {
 187          $this->debugMessages = array();
 188  
 189          return $this;
 190      }
 191  
 192      /**
 193       * Render a layout with debug info
 194       *
 195       * @param   mixed  $data  Data passed to the layout
 196       *
 197       * @return  string
 198       *
 199       * @since    3.5
 200       */
 201      public function debug($data = array())
 202      {
 203          $this->setDebug(true);
 204  
 205          $output = $this->render($data);
 206  
 207          $this->setDebug(false);
 208  
 209          return $output;
 210      }
 211  
 212      /**
 213       * Method to get the value from the data array
 214       *
 215       * @param   string  $key           Key to search for in the data array
 216       * @param   mixed   $defaultValue  Default value to return if the key is not set
 217       *
 218       * @return  mixed   Value from the data array | defaultValue if doesn't exist
 219       *
 220       * @since   3.5
 221       */
 222      public function get($key, $defaultValue = null)
 223      {
 224          return $this->data[$key] ?? $defaultValue;
 225      }
 226  
 227      /**
 228       * Get the data being rendered
 229       *
 230       * @return  array
 231       *
 232       * @since   3.5
 233       */
 234      public function getData()
 235      {
 236          return $this->data;
 237      }
 238  
 239      /**
 240       * Check if debug mode is enabled
 241       *
 242       * @return  boolean
 243       *
 244       * @since   3.5
 245       */
 246      public function isDebugEnabled()
 247      {
 248          return $this->getOptions()->get('debug', false) === true;
 249      }
 250  
 251      /**
 252       * Method to set a value in the data array. Example: $layout->set('items', $items);
 253       *
 254       * @param   string  $key    Key for the data array
 255       * @param   mixed   $value  Value to assign to the key
 256       *
 257       * @return  self
 258       *
 259       * @since   3.5
 260       */
 261      public function set($key, $value)
 262      {
 263          $this->data[(string) $key] = $value;
 264  
 265          return $this;
 266      }
 267  
 268      /**
 269       * Set the the data passed the layout
 270       *
 271       * @param   array  $data  Array with the data for the layout
 272       *
 273       * @return  self
 274       *
 275       * @since   3.5
 276       */
 277      public function setData(array $data)
 278      {
 279          $this->data = $data;
 280  
 281          return $this;
 282      }
 283  
 284      /**
 285       * Change the debug mode
 286       *
 287       * @param   boolean  $debug  Enable / Disable debug
 288       *
 289       * @return  self
 290       *
 291       * @since   3.5
 292       */
 293      public function setDebug($debug)
 294      {
 295          $this->options->set('debug', (bool) $debug);
 296  
 297          return $this;
 298      }
 299  }