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