Permalink
Newer
Older
100644 237 lines (212 sloc) 7.75 KB
@gwoo
Oct 13, 2009
1
<?php
2
/**
3
* Lithium: the most rad php framework
4
*
@davidpersson
Jan 13, 2015
5
* @copyright Copyright 2015, Union of RAD (http://union-of-rad.org)
@gwoo
Oct 13, 2009
6
* @license http://opensource.org/licenses/bsd-license.php The BSD License
7
*/
8
9
namespace lithium\template;
10
11
use lithium\util\String;
@gwoo
Oct 13, 2009
12
13
/**
14
* Abstract class for template helpers to extend.
15
* Supplies the basic functionality of _render and _options,
16
* as well as escaping.
17
*
18
*/
@gwoo
Oct 13, 2009
19
abstract class Helper extends \lithium\core\Object {
20
21
/**
22
* Maps helper method names to content types as defined by the `Media` class, where key are
23
* method names, and values are the content type that the method name outputs a link to.
24
*
25
* @var array
26
*/
27
public $contentMap = array();
28
29
/**
30
* Holds string templates which will be merged into the rendering context.
31
*
32
* @var array
33
*/
34
protected $_strings = array();
35
Apr 27, 2010
36
/**
37
* The Renderer object this Helper is bound to.
38
*
39
* @var lithium\template\view\Renderer
40
* @see lithium\template\view\Renderer
41
*/
@gwoo
Oct 13, 2009
42
protected $_context = null;
43
44
/**
45
* This property can be overwritten with any class dependencies a helper subclass has.
46
*
47
* @var array
48
*/
49
protected $_classes = array();
50
Apr 27, 2010
51
/**
52
* Auto configuration properties.
53
*
54
* @var array
55
*/
@gwoo
Oct 13, 2009
56
protected $_autoConfig = array('classes' => 'merge', 'context');
57
58
/**
59
* List of minimized HTML attributes.
60
*
61
* @var array
62
*/
63
protected $_minimized = array(
64
'compact', 'checked', 'declare', 'readonly', 'disabled', 'selected', 'defer', 'ismap',
65
'nohref', 'noshade', 'nowrap', 'multiple', 'noresize', 'async', 'autofocus'
@gwoo
Oct 13, 2009
66
);
67
71
* @param array $config Configuration options.
72
* @return void
73
*/
74
public function __construct(array $config = array()) {
@gwoo
Oct 13, 2009
75
$defaults = array('handlers' => array(), 'context' => null);
76
parent::__construct($config + $defaults);
77
}
78
79
/**
80
* Imports local string definitions into rendering context.
81
*
82
* @return void
83
*/
84
protected function _init() {
85
parent::_init();
86
87
if (!$this->_context) {
88
return;
89
}
90
$this->_context->strings($this->_strings);
91
92
if ($this->_config['handlers']) {
93
$this->_context->handlers($this->_config['handlers']);
94
}
95
}
96
97
/**
98
* Escapes values according to the output type of the rendering context. Helpers that output to
99
* non-HTML/XML contexts should override this method accordingly.
100
*
101
* @param string $value
102
* @param mixed $method
103
* @param array $options
@gwoo
Oct 13, 2009
104
* @return mixed
105
*/
106
public function escape($value, $method = null, array $options = array()) {
@gwoo
Oct 13, 2009
107
$defaults = array('escape' => true);
108
$options += $defaults;
109
110
if ($options['escape'] === false) {
111
return $value;
112
}
113
if (is_array($value)) {
114
return array_map(array($this, __FUNCTION__), $value);
115
}
@gwoo
Oct 13, 2009
116
return htmlspecialchars($value, ENT_QUOTES, 'UTF-8');
117
}
118
119
/**
120
* Takes the defaults and current options, merges them and returns options which have
121
* the default keys removed and full set of options as the scope.
122
*
123
* @param array $defaults
124
* @param array $scope the complete set of options
125
* @return array $scope, $options
126
*/
127
protected function _options(array $defaults, array $scope) {
128
$scope += $defaults;
129
$options = array_diff_key($scope, $defaults);
130
return array($scope, $options);
131
}
132
133
/**
134
* Render a string template after applying context filters
135
* Use examples in the Html::link() method:
136
* `return $this->_render(__METHOD__, 'link', compact('title', 'url', 'options'), $scope);`
137
*
138
* @param string $method name of method that is calling the render (for context filters)
139
* @param string $string template key (in Helper::_strings) to render
140
* @param array $params associated array of template inserts {:key} will be replaced by value
141
* @param array $options Available options:
142
* - `'handlers'` _array_: Before inserting `$params` inside the string template,
143
* `$this->_context`'s handlers are applied to each value of `$params` according
144
* to the key (e.g `$params['url']`, which is processed by the `'url'` handler
145
* via `$this->_context->applyHandler()`).
146
* The `'handlers'` option allow to set custom mapping beetween `$params`'s key and
147
* `$this->_context`'s handlers. e.g. the following handler:
148
* `'handlers' => array('url' => 'path')` will make `$params['url']` to be
149
* processed by the `'path'` handler instead of the `'url'` one.
150
* @return string Rendered HTML
151
*/
152
protected function _render($method, $string, $params, array $options = array()) {
155
if (isset($params['options']['scope'])) {
156
$options['scope'] = $params['options']['scope'];
157
unset($params['options']['scope']);
158
}
159
160
if ($this->_context) {
161
foreach ($params as $key => $value) {
162
$handler = isset($options['handlers'][$key]) ? $options['handlers'][$key] : $key;
163
$params[$key] = $this->_context->applyHandler(
164
$this, $method, $handler, $value, $options
166
}
167
$strings = $this->_context->strings();
@gwoo
Oct 13, 2009
168
}
169
return String::insert(isset($strings[$string]) ? $strings[$string] : $string, $params);
170
}
171
172
/**
173
* Converts a set of parameters to HTML attributes into a string.
174
*
175
* @see lithium\template\view\Renderer::__call()
176
* @param array|string $params The parameters where key is the attribute name and
177
* the value the attribute value. When string will simply prepend
178
* with the prepend-string (by default `' '`) unless $params is
179
* falsey in which case an empty string is returned. This
180
* alternative syntax is used by the method internally.
181
* @param string $method When used as a context handler, the method the handler was
182
* called for I.e. `'wrap'`. Currently not used by the method.
183
* @param array $options Available options are:
184
* - `'escape'` _boolean_: Indicates whether the output should be
185
* HTML-escaped. Defaults to `true`.
186
* - `'prepend'` _string_: String to prepend to each attribute pair.
187
* and the final result. Defaults to `' '`.
188
* - `'append'` _string_: String to append to result. Defaults to `''`.
189
* @return string Attribute string.
190
*/
191
protected function _attributes($params, $method = null, array $options = array()) {
@gwoo
Oct 13, 2009
192
$defaults = array('escape' => true, 'prepend' => ' ', 'append' => '');
193
$options += $defaults;
194
$result = array();
196
if (!is_array($params)) {
197
return !$params ? '' : $options['prepend'] . $params;
198
}
@gwoo
Oct 13, 2009
199
foreach ($params as $key => $value) {
200
if ($next = $this->_attribute($key, $value, $options)) {
201
$result[] = $next;
202
}
@gwoo
Oct 13, 2009
203
}
204
return $result ? $options['prepend'] . implode(' ', $result) . $options['append'] : '';
205
}
206
207
/**
208
* Convert a key/value pair to a valid HTML attribute.
209
*
210
* @param string $key The key name of the HTML attribute.
211
* @param mixed $value The HTML attribute value.
212
* @param array $options The options used when converting the key/value pair to attributes:
213
* - `'escape'` _boolean_: Indicates whether `$key` and `$value` should be
214
* HTML-escaped. Defaults to `true`.
215
* - `'format'` _string_: The format string. Defaults to `'%s="%s"'`.
216
* @return string Returns an HTML attribute/value pair, in the form of `'$key="$value"'`.
217
*/
218
protected function _attribute($key, $value, array $options = array()) {
219
$defaults = array('escape' => true, 'format' => '%s="%s"');
@gwoo
Oct 13, 2009
220
$options += $defaults;
221
222
if (in_array($key, $this->_minimized)) {
223
$isMini = ($value === 1 || $value === true || $value === $key);
224
if (!($value = $isMini ? $key : $value)) {
225
return null;
226
}
@gwoo
Oct 13, 2009
227
}
@gwoo
Oct 13, 2009
229
230
if ($options['escape']) {
231
return sprintf($options['format'], $this->escape($key), $this->escape($value));
@gwoo
Oct 13, 2009
232
}
233
return sprintf($options['format'], $key, $value);
@gwoo
Oct 13, 2009
234
}
235
}
236
237
?>