Updating copyrights. Happy New Year.
[squirrelmail.git] / class / template / PHP_Template.class.php
1 <?php
2
3 /**
4 * Copyright 2003, Paul James
5 *
6 * This file contains some methods from the Smarty templating engine version
7 * 2.5.0 by Monte Ohrt <monte@ispi.net> and Andrei Zmievski <andrei@php.net>.
8 *
9 * The SquirrelMail (Foowd) template implementation.
10 * Derived from the foowd template implementation and adapted
11 * for squirrelmail
12 * @copyright 2005-2012 The SquirrelMail Project Team
13 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
14 * @version $Id$
15 * @package squirrelmail
16 *
17 */
18
19 /**
20 * The SquirrelMail PHP Template class. Extends the base
21 * Template class for use with PHP template pages.
22 *
23 * @author Paul James
24 * @author Monte Ohrt <monte at ispi.net>
25 * @author Andrei Zmievski <andrei at php.net>
26 * @author Paul Lesniewski <paul at squirrelmail.org>
27 * @package squirrelmail
28 *
29 */
30 class PHP_Template extends Template
31 {
32
33 /**
34 * The templates values array
35 *
36 * @var array
37 *
38 */
39 var $values = array();
40
41
42 /**
43 * Constructor
44 *
45 * Please do not call directly. Use Template::construct_template().
46 *
47 * @param string $template_id the template ID
48 *
49 */
50 function PHP_Template($template_id) {
51 //FIXME: find a way to test that this is ONLY ever called
52 // from parent's construct_template() method (I doubt it
53 // is worth the trouble to parse the current stack trace)
54 // if (???)
55 // trigger_error('Please do not use default PHP_Template() constructor. Instead, use Template::construct_template().', E_USER_ERROR);
56
57 parent::Template($template_id);
58
59 }
60
61 /**
62 * Assigns values to template variables
63 *
64 * @param array|string $tpl_var the template variable name(s)
65 * @param mixed $value the value to assign
66 FIXME: Proposed idea to add a parameter here that turns variable
67 encoding on, so that we can make sure output is always
68 run through something like htmlspecialchars() (maybe even nl2br()?)
69 *
70 */
71 function assign($tpl_var, $value = NULL) {
72
73 if (is_array($tpl_var))
74 {
75 foreach ($tpl_var as $key => $val)
76 {
77 if ($key != '')
78 $this->values[$key] = $val;
79 }
80 }
81 else
82 {
83 if ($tpl_var != '')
84 $this->values[$tpl_var] = $value;
85 }
86
87 }
88
89 /**
90 * Assigns values to template variables by reference
91 *
92 * @param string $tpl_var the template variable name
93 * @param mixed $value the referenced value to assign
94 FIXME: Proposed idea to add a parameter here that turns variable
95 encoding on, so that we can make sure output is always
96 run through something like htmlspecialchars() (maybe even nl2br()?)
97 *
98 */
99 function assign_by_ref($tpl_var, &$value) {
100
101 if ($tpl_var != '')
102 $this->values[$tpl_var] = &$value;
103
104 }
105
106 /**
107 * Clears the values of all assigned varaiables.
108 *
109 */
110 function clear_all_assign() {
111
112 $this->values = array();
113
114 }
115
116 /**
117 * Returns assigned variable value(s).
118 *
119 * @param string $varname If given, the value of that variable
120 * is returned, assuming it has been
121 * previously assigned. If not specified
122 * an array of all assigned variables is
123 * returned. (optional)
124 *
125 * @return mixed Desired single variable value or list of all
126 * assigned variable values.
127 *
128 */
129 function get_template_vars($varname=NULL) {
130
131 // just looking for one value
132 //
133 if (!empty($varname)) {
134 if (!empty($this->values[$varname]))
135 return $this->values[$varname];
136 else
137 // FIXME: this OK? What does Smarty do?
138 return NULL;
139 }
140
141
142 // return all variable values
143 //
144 return $this->values;
145
146 }
147
148 /**
149 * Appends values to template variables
150 *
151 * @param array|string $tpl_var the template variable name(s)
152 * @param mixed $value the value to append
153 * @param boolean $merge when $value is given as an array,
154 * this indicates whether or not that
155 * array itself should be appended as
156 * a new template variable value or if
157 * that array's values should be merged
158 * into the existing array of template
159 * variable values
160 FIXME: Proposed idea to add a parameter here that turns variable
161 encoding on, so that we can make sure output is always
162 run through something like htmlspecialchars() (maybe even nl2br()?)
163 *
164 */
165 function append($tpl_var, $value = NULL, $merge = FALSE)
166 {
167 if (is_array($tpl_var))
168 {
169 foreach ($tpl_var as $_key => $_val)
170 {
171 if ($_key != '')
172 {
173 if(isset($this->values[$_key]) && !is_array($this->values[$_key]))
174 settype($this->values[$_key],'array');
175
176 if($merge && is_array($_val))
177 {
178 // FIXME: Tentative testing seems to indicate that
179 // this does not mirror Smarty behavior; Smarty
180 // seems to append the full array as a new element
181 // instead of merging, so this behavior is technically
182 // more "correct", but Smarty seems to differ
183 foreach($_val as $_mkey => $_mval)
184 $this->values[$_key][$_mkey] = $_mval;
185 }
186 else
187 $this->values[$_key][] = $_val;
188 }
189 }
190 }
191 else
192 {
193 if ($tpl_var != '' && isset($value))
194 {
195 if(isset($this->values[$tpl_var]) && !is_array($this->values[$tpl_var]))
196 settype($this->values[$tpl_var],'array');
197
198 if($merge && is_array($value))
199 {
200 foreach($value as $_mkey => $_mval)
201 $this->values[$tpl_var][$_mkey] = $_mval;
202 }
203 else
204 $this->values[$tpl_var][] = $value;
205 }
206 }
207 }
208
209 /**
210 * Appends values to template variables by reference
211 *
212 * @param string $tpl_var the template variable name
213 * @param mixed $value the referenced value to append
214 * @param boolean $merge when $value is given as an array,
215 * this indicates whether or not that
216 * array itself should be appended as
217 * a new template variable value or if
218 * that array's values should be merged
219 * into the existing array of template
220 * variable values
221 FIXME: Proposed idea to add a parameter here that turns variable
222 encoding on, so that we can make sure output is always
223 run through something like htmlspecialchars() (maybe even nl2br()?)
224 *
225 */
226 function append_by_ref($tpl_var, &$value, $merge = FALSE)
227 {
228 if ($tpl_var != '' && isset($value))
229 {
230 if(!@is_array($this->values[$tpl_var]))
231 settype($this->values[$tpl_var],'array');
232
233 if ($merge && is_array($value))
234 {
235 foreach($value as $_key => $_val)
236 $this->values[$tpl_var][$_key] = &$value[$_key];
237 }
238 else
239 $this->values[$tpl_var][] = &$value;
240 }
241 }
242
243 /**
244 * Applys the template and generates final output destined
245 * for the user's browser
246 *
247 * @param string $filepath The full file path to the template to be applied
248 *
249 * @return string The output for the given template
250 *
251 */
252 function apply_template($filepath) {
253
254 // place values array directly in scope
255 // ($t? let's try to be more verbose please :-) )
256 //
257 $t = &$this->values;
258
259 ob_start();
260 include($filepath);
261 $contents = ob_get_contents();
262 ob_end_clean();
263 return $contents;
264
265 }
266
267 }
268