1: <?php
2: /**
3: * Html Helper class file.
4: *
5: * Simplifies the construction of HTML elements.
6: *
7: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
8: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
9: *
10: * Licensed under The MIT License
11: * For full copyright and license information, please see the LICENSE.txt
12: * Redistributions of files must retain the above copyright notice.
13: *
14: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
15: * @link http://cakephp.org CakePHP(tm) Project
16: * @package Cake.View.Helper
17: * @since CakePHP(tm) v 0.9.1
18: * @license http://www.opensource.org/licenses/mit-license.php MIT License
19: */
20:
21: App::uses('AppHelper', 'View/Helper');
22: App::uses('CakeResponse', 'Network');
23:
24: /**
25: * Html Helper class for easy use of HTML widgets.
26: *
27: * HtmlHelper encloses all methods needed while working with HTML pages.
28: *
29: * @package Cake.View.Helper
30: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html
31: */
32: class HtmlHelper extends AppHelper {
33:
34: /**
35: * Reference to the Response object
36: *
37: * @var CakeResponse
38: */
39: public $response;
40:
41: /**
42: * html tags used by this helper.
43: *
44: * @var array
45: */
46: protected $_tags = array(
47: 'meta' => '<meta%s/>',
48: 'metalink' => '<link href="%s"%s/>',
49: 'link' => '<a href="%s"%s>%s</a>',
50: 'mailto' => '<a href="mailto:%s"%s>%s</a>',
51: 'form' => '<form action="%s"%s>',
52: 'formwithoutaction' => '<form%s>',
53: 'formend' => '</form>',
54: 'input' => '<input name="%s"%s/>',
55: 'textarea' => '<textarea name="%s"%s>%s</textarea>',
56: 'hidden' => '<input type="hidden" name="%s"%s/>',
57: 'checkbox' => '<input type="checkbox" name="%s"%s/>',
58: 'checkboxmultiple' => '<input type="checkbox" name="%s[]"%s />',
59: 'radio' => '<input type="radio" name="%s" id="%s"%s />%s',
60: 'selectstart' => '<select name="%s"%s>',
61: 'selectmultiplestart' => '<select name="%s[]"%s>',
62: 'selectempty' => '<option value=""%s> </option>',
63: 'selectoption' => '<option value="%s"%s>%s</option>',
64: 'selectend' => '</select>',
65: 'optiongroup' => '<optgroup label="%s"%s>',
66: 'optiongroupend' => '</optgroup>',
67: 'checkboxmultiplestart' => '',
68: 'checkboxmultipleend' => '',
69: 'password' => '<input type="password" name="%s"%s/>',
70: 'file' => '<input type="file" name="%s"%s/>',
71: 'file_no_model' => '<input type="file" name="%s"%s/>',
72: 'submit' => '<input%s/>',
73: 'submitimage' => '<input type="image" src="%s"%s/>',
74: 'button' => '<button%s>%s</button>',
75: 'image' => '<img src="%s"%s/>',
76: 'tableheader' => '<th%s>%s</th>',
77: 'tableheaderrow' => '<tr%s>%s</tr>',
78: 'tablecell' => '<td%s>%s</td>',
79: 'tablerow' => '<tr%s>%s</tr>',
80: 'block' => '<div%s>%s</div>',
81: 'blockstart' => '<div%s>',
82: 'blockend' => '</div>',
83: 'hiddenblock' => '<div style="display:none;">%s</div>',
84: 'tag' => '<%s%s>%s</%s>',
85: 'tagstart' => '<%s%s>',
86: 'tagend' => '</%s>',
87: 'tagselfclosing' => '<%s%s/>',
88: 'para' => '<p%s>%s</p>',
89: 'parastart' => '<p%s>',
90: 'label' => '<label for="%s"%s>%s</label>',
91: 'fieldset' => '<fieldset%s>%s</fieldset>',
92: 'fieldsetstart' => '<fieldset><legend>%s</legend>',
93: 'fieldsetend' => '</fieldset>',
94: 'legend' => '<legend>%s</legend>',
95: 'css' => '<link rel="%s" type="text/css" href="%s"%s/>',
96: 'style' => '<style type="text/css"%s>%s</style>',
97: 'charset' => '<meta http-equiv="Content-Type" content="text/html; charset=%s" />',
98: 'ul' => '<ul%s>%s</ul>',
99: 'ol' => '<ol%s>%s</ol>',
100: 'li' => '<li%s>%s</li>',
101: 'error' => '<div%s>%s</div>',
102: 'javascriptblock' => '<script%s>%s</script>',
103: 'javascriptstart' => '<script>',
104: 'javascriptlink' => '<script type="text/javascript" src="%s"%s></script>',
105: 'javascriptend' => '</script>'
106: );
107:
108: /**
109: * Breadcrumbs.
110: *
111: * @var array
112: */
113: protected $_crumbs = array();
114:
115: /**
116: * Names of script & css files that have been included once
117: *
118: * @var array
119: */
120: protected $_includedAssets = array();
121:
122: /**
123: * Options for the currently opened script block buffer if any.
124: *
125: * @var array
126: */
127: protected $_scriptBlockOptions = array();
128:
129: /**
130: * Document type definitions
131: *
132: * @var array
133: */
134: protected $_docTypes = array(
135: 'html4-strict' => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">',
136: 'html4-trans' => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">',
137: 'html4-frame' => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">',
138: 'html5' => '<!DOCTYPE html>',
139: 'xhtml-strict' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
140: 'xhtml-trans' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
141: 'xhtml-frame' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
142: 'xhtml11' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">'
143: );
144:
145: /**
146: * Constructor
147: *
148: * ### Settings
149: *
150: * - `configFile` A file containing an array of tags you wish to redefine.
151: *
152: * ### Customizing tag sets
153: *
154: * Using the `configFile` option you can redefine the tag HtmlHelper will use.
155: * The file named should be compatible with HtmlHelper::loadConfig().
156: *
157: * @param View $View The View this helper is being attached to.
158: * @param array $settings Configuration settings for the helper.
159: */
160: public function __construct(View $View, $settings = array()) {
161: parent::__construct($View, $settings);
162: if (is_object($this->_View->response)) {
163: $this->response = $this->_View->response;
164: } else {
165: $this->response = new CakeResponse();
166: }
167: if (!empty($settings['configFile'])) {
168: $this->loadConfig($settings['configFile']);
169: }
170: }
171:
172: /**
173: * Adds a link to the breadcrumbs array.
174: *
175: * @param string $name Text for link
176: * @param string $link URL for link (if empty it won't be a link)
177: * @param string|array $options Link attributes e.g. array('id' => 'selected')
178: * @return self
179: * @see HtmlHelper::link() for details on $options that can be used.
180: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper
181: */
182: public function addCrumb($name, $link = null, $options = null) {
183: $this->_crumbs[] = array($name, $link, $options);
184: return $this;
185: }
186:
187: /**
188: * Returns a doctype string.
189: *
190: * Possible doctypes:
191: *
192: * - html4-strict: HTML4 Strict.
193: * - html4-trans: HTML4 Transitional.
194: * - html4-frame: HTML4 Frameset.
195: * - html5: HTML5. Default value.
196: * - xhtml-strict: XHTML1 Strict.
197: * - xhtml-trans: XHTML1 Transitional.
198: * - xhtml-frame: XHTML1 Frameset.
199: * - xhtml11: XHTML1.1.
200: *
201: * @param string $type Doctype to use.
202: * @return string|null Doctype string
203: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::docType
204: */
205: public function docType($type = 'html5') {
206: if (isset($this->_docTypes[$type])) {
207: return $this->_docTypes[$type];
208: }
209: return null;
210: }
211:
212: /**
213: * Creates a link to an external resource and handles basic meta tags
214: *
215: * Create a meta tag that is output inline:
216: *
217: * `$this->Html->meta('icon', 'favicon.ico');
218: *
219: * Append the meta tag to `$scripts_for_layout`:
220: *
221: * `$this->Html->meta('description', 'A great page', array('inline' => false));`
222: *
223: * Append the meta tag to custom view block:
224: *
225: * `$this->Html->meta('description', 'A great page', array('block' => 'metaTags'));`
226: *
227: * ### Options
228: *
229: * - `inline` Whether or not the link element should be output inline. Set to false to
230: * have the meta tag included in `$scripts_for_layout`, and appended to the 'meta' view block.
231: * - `block` Choose a custom block to append the meta tag to. Using this option
232: * will override the inline option.
233: *
234: * @param string $type The title of the external resource
235: * @param string|array $url The address of the external resource or string for content attribute
236: * @param array $options Other attributes for the generated tag. If the type attribute is html,
237: * rss, atom, or icon, the mime-type is returned.
238: * @return string A completed `<link />` element.
239: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::meta
240: */
241: public function meta($type, $url = null, $options = array()) {
242: $options += array('inline' => true, 'block' => null);
243: if (!$options['inline'] && empty($options['block'])) {
244: $options['block'] = __FUNCTION__;
245: }
246: unset($options['inline']);
247:
248: if (!is_array($type)) {
249: $types = array(
250: 'rss' => array('type' => 'application/rss+xml', 'rel' => 'alternate', 'title' => $type, 'link' => $url),
251: 'atom' => array('type' => 'application/atom+xml', 'title' => $type, 'link' => $url),
252: 'icon' => array('type' => 'image/x-icon', 'rel' => 'icon', 'link' => $url),
253: 'keywords' => array('name' => 'keywords', 'content' => $url),
254: 'description' => array('name' => 'description', 'content' => $url),
255: );
256:
257: if ($type === 'icon' && $url === null) {
258: $types['icon']['link'] = 'favicon.ico';
259: }
260:
261: if (isset($types[$type])) {
262: $type = $types[$type];
263: } elseif (!isset($options['type']) && $url !== null) {
264: if (is_array($url) && isset($url['ext'])) {
265: $type = $types[$url['ext']];
266: } else {
267: $type = $types['rss'];
268: }
269: } elseif (isset($options['type']) && isset($types[$options['type']])) {
270: $type = $types[$options['type']];
271: unset($options['type']);
272: } else {
273: $type = array();
274: }
275: }
276:
277: $options += $type;
278: $out = null;
279:
280: if (isset($options['link'])) {
281: $options['link'] = $this->assetUrl($options['link']);
282: if (isset($options['rel']) && $options['rel'] === 'icon') {
283: $out = sprintf($this->_tags['metalink'], $options['link'], $this->_parseAttributes($options, array('block', 'link')));
284: $options['rel'] = 'shortcut icon';
285: }
286: $out .= sprintf($this->_tags['metalink'], $options['link'], $this->_parseAttributes($options, array('block', 'link')));
287: } else {
288: $out = sprintf($this->_tags['meta'], $this->_parseAttributes($options, array('block', 'type')));
289: }
290:
291: if (empty($options['block'])) {
292: return $out;
293: }
294: $this->_View->append($options['block'], $out);
295: }
296:
297: /**
298: * Returns a charset META-tag.
299: *
300: * @param string $charset The character set to be used in the meta tag. If empty,
301: * The App.encoding value will be used. Example: "utf-8".
302: * @return string A meta tag containing the specified character set.
303: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::charset
304: */
305: public function charset($charset = null) {
306: if (empty($charset)) {
307: $charset = strtolower(Configure::read('App.encoding'));
308: }
309: return sprintf($this->_tags['charset'], (!empty($charset) ? $charset : 'utf-8'));
310: }
311:
312: /**
313: * Creates an HTML link.
314: *
315: * If $url starts with "http://" this is treated as an external link. Else,
316: * it is treated as a path to controller/action and parsed with the
317: * HtmlHelper::url() method.
318: *
319: * If the $url is empty, $title is used instead.
320: *
321: * ### Options
322: *
323: * - `escape` Set to false to disable escaping of title and attributes.
324: * - `escapeTitle` Set to false to disable escaping of title. (Takes precedence over value of `escape`)
325: * - `confirm` JavaScript confirmation message.
326: *
327: * @param string $title The content to be wrapped by `<a>` tags.
328: * @param string|array $url Cake-relative URL or array of URL parameters, or external URL (starts with http://)
329: * @param array $options Array of options and HTML attributes.
330: * @param string $confirmMessage JavaScript confirmation message. This
331: * argument is deprecated as of 2.6. Use `confirm` key in $options instead.
332: * @return string An `<a />` element.
333: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::link
334: */
335: public function link($title, $url = null, $options = array(), $confirmMessage = false) {
336: $escapeTitle = true;
337: if ($url !== null) {
338: $url = $this->url($url);
339: } else {
340: $url = $this->url($title);
341: $title = htmlspecialchars_decode($url, ENT_QUOTES);
342: $title = h(urldecode($title));
343: $escapeTitle = false;
344: }
345:
346: if (isset($options['escapeTitle'])) {
347: $escapeTitle = $options['escapeTitle'];
348: unset($options['escapeTitle']);
349: } elseif (isset($options['escape'])) {
350: $escapeTitle = $options['escape'];
351: }
352:
353: if ($escapeTitle === true) {
354: $title = h($title);
355: } elseif (is_string($escapeTitle)) {
356: $title = htmlentities($title, ENT_QUOTES, $escapeTitle);
357: }
358:
359: if (!empty($options['confirm'])) {
360: $confirmMessage = $options['confirm'];
361: unset($options['confirm']);
362: }
363: if ($confirmMessage) {
364: $options['onclick'] = $this->_confirm($confirmMessage, 'return true;', 'return false;', $options);
365: } elseif (isset($options['default']) && !$options['default']) {
366: if (isset($options['onclick'])) {
367: $options['onclick'] .= ' ';
368: } else {
369: $options['onclick'] = '';
370: }
371: $options['onclick'] .= 'event.returnValue = false; return false;';
372: unset($options['default']);
373: }
374: return sprintf($this->_tags['link'], $url, $this->_parseAttributes($options), $title);
375: }
376:
377: /**
378: * Creates a link element for CSS stylesheets.
379: *
380: * ### Usage
381: *
382: * Include one CSS file:
383: *
384: * `echo $this->Html->css('styles.css');`
385: *
386: * Include multiple CSS files:
387: *
388: * `echo $this->Html->css(array('one.css', 'two.css'));`
389: *
390: * Add the stylesheet to the `$scripts_for_layout` layout var:
391: *
392: * `$this->Html->css('styles.css', array('inline' => false));`
393: *
394: * Add the stylesheet to a custom block:
395: *
396: * `$this->Html->css('styles.css', array('block' => 'layoutCss'));`
397: *
398: * ### Options
399: *
400: * - `inline` If set to false, the generated tag will be appended to the 'css' block,
401: * and included in the `$scripts_for_layout` layout variable. Defaults to true.
402: * - `once` Whether or not the css file should be checked for uniqueness. If true css
403: * files will only be included once, use false to allow the same
404: * css to be included more than once per request.
405: * - `block` Set the name of the block link/style tag will be appended to.
406: * This overrides the `inline` option.
407: * - `plugin` False value will prevent parsing path as a plugin
408: * - `rel` Defaults to 'stylesheet'. If equal to 'import' the stylesheet will be imported.
409: * - `fullBase` If true the URL will get a full address for the css file.
410: *
411: * @param string|array $path The name of a CSS style sheet or an array containing names of
412: * CSS stylesheets. If `$path` is prefixed with '/', the path will be relative to the webroot
413: * of your application. Otherwise, the path will be relative to your CSS path, usually webroot/css.
414: * @param array $options Array of options and HTML arguments.
415: * @return string CSS `<link />` or `<style />` tag, depending on the type of link.
416: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::css
417: */
418: public function css($path, $options = array()) {
419: if (!is_array($options)) {
420: $rel = $options;
421: $options = array();
422: if ($rel) {
423: $options['rel'] = $rel;
424: }
425: if (func_num_args() > 2) {
426: $options = func_get_arg(2) + $options;
427: }
428: unset($rel);
429: }
430:
431: $options += array(
432: 'block' => null,
433: 'inline' => true,
434: 'once' => false,
435: 'rel' => 'stylesheet'
436: );
437: if (!$options['inline'] && empty($options['block'])) {
438: $options['block'] = __FUNCTION__;
439: }
440: unset($options['inline']);
441:
442: if (is_array($path)) {
443: $out = '';
444: foreach ($path as $i) {
445: $out .= "\n\t" . $this->css($i, $options);
446: }
447: if (empty($options['block'])) {
448: return $out . "\n";
449: }
450: return '';
451: }
452:
453: if ($options['once'] && isset($this->_includedAssets[__METHOD__][$path])) {
454: return '';
455: }
456: unset($options['once']);
457: $this->_includedAssets[__METHOD__][$path] = true;
458:
459: if (strpos($path, '//') !== false) {
460: $url = $path;
461: } else {
462: $url = $this->assetUrl($path, $options + array('pathPrefix' => Configure::read('App.cssBaseUrl'), 'ext' => '.css'));
463: $options = array_diff_key($options, array('fullBase' => null, 'pathPrefix' => null));
464:
465: if (Configure::read('Asset.filter.css')) {
466: $pos = strpos($url, Configure::read('App.cssBaseUrl'));
467: if ($pos !== false) {
468: $url = substr($url, 0, $pos) . 'ccss/' . substr($url, $pos + strlen(Configure::read('App.cssBaseUrl')));
469: }
470: }
471: }
472:
473: if ($options['rel'] === 'import') {
474: $out = sprintf(
475: $this->_tags['style'],
476: $this->_parseAttributes($options, array('rel', 'block')),
477: '@import url(' . $url . ');'
478: );
479: } else {
480: $out = sprintf(
481: $this->_tags['css'],
482: $options['rel'],
483: $url,
484: $this->_parseAttributes($options, array('rel', 'block'))
485: );
486: }
487:
488: if (empty($options['block'])) {
489: return $out;
490: }
491: $this->_View->append($options['block'], $out);
492: }
493:
494: /**
495: * Returns one or many `<script>` tags depending on the number of scripts given.
496: *
497: * If the filename is prefixed with "/", the path will be relative to the base path of your
498: * application. Otherwise, the path will be relative to your JavaScript path, usually webroot/js.
499: *
500: * ### Usage
501: *
502: * Include one script file:
503: *
504: * `echo $this->Html->script('styles.js');`
505: *
506: * Include multiple script files:
507: *
508: * `echo $this->Html->script(array('one.js', 'two.js'));`
509: *
510: * Add the script file to the `$scripts_for_layout` layout var:
511: *
512: * `$this->Html->script('styles.js', array('inline' => false));`
513: *
514: * Add the script file to a custom block:
515: *
516: * `$this->Html->script('styles.js', array('block' => 'bodyScript'));`
517: *
518: * ### Options
519: *
520: * - `inline` Whether script should be output inline or into `$scripts_for_layout`. When set to false,
521: * the script tag will be appended to the 'script' view block as well as `$scripts_for_layout`.
522: * - `block` The name of the block you want the script appended to. Leave undefined to output inline.
523: * Using this option will override the inline option.
524: * - `once` Whether or not the script should be checked for uniqueness. If true scripts will only be
525: * included once, use false to allow the same script to be included more than once per request.
526: * - `plugin` False value will prevent parsing path as a plugin
527: * - `fullBase` If true the url will get a full address for the script file.
528: *
529: * @param string|array $url String or array of javascript files to include
530: * @param array|bool $options Array of options, and html attributes see above. If boolean sets $options['inline'] = value
531: * @return mixed String of `<script />` tags or null if $inline is false or if $once is true and the file has been
532: * included before.
533: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::script
534: */
535: public function script($url, $options = array()) {
536: if (is_bool($options)) {
537: list($inline, $options) = array($options, array());
538: $options['inline'] = $inline;
539: }
540: $options += array('block' => null, 'inline' => true, 'once' => true);
541: if (!$options['inline'] && empty($options['block'])) {
542: $options['block'] = __FUNCTION__;
543: }
544: unset($options['inline']);
545:
546: if (is_array($url)) {
547: $out = '';
548: foreach ($url as $i) {
549: $out .= "\n\t" . $this->script($i, $options);
550: }
551: if (empty($options['block'])) {
552: return $out . "\n";
553: }
554: return null;
555: }
556: if ($options['once'] && isset($this->_includedAssets[__METHOD__][$url])) {
557: return null;
558: }
559: $this->_includedAssets[__METHOD__][$url] = true;
560:
561: if (strpos($url, '//') === false) {
562: $url = $this->assetUrl($url, $options + array('pathPrefix' => Configure::read('App.jsBaseUrl'), 'ext' => '.js'));
563: $options = array_diff_key($options, array('fullBase' => null, 'pathPrefix' => null));
564:
565: if (Configure::read('Asset.filter.js')) {
566: $url = str_replace(Configure::read('App.jsBaseUrl'), 'cjs/', $url);
567: }
568: }
569: $attributes = $this->_parseAttributes($options, array('block', 'once'));
570: $out = sprintf($this->_tags['javascriptlink'], $url, $attributes);
571:
572: if (empty($options['block'])) {
573: return $out;
574: }
575: $this->_View->append($options['block'], $out);
576: }
577:
578: /**
579: * Wrap $script in a script tag.
580: *
581: * ### Options
582: *
583: * - `safe` (boolean) Whether or not the $script should be wrapped in `<![CDATA[ ]]>`
584: * - `inline` (boolean) Whether or not the $script should be added to
585: * `$scripts_for_layout` / `script` block, or output inline. (Deprecated, use `block` instead)
586: * - `block` Which block you want this script block appended to.
587: * Defaults to `script`.
588: *
589: * @param string $script The script to wrap
590: * @param array $options The options to use. Options not listed above will be
591: * treated as HTML attributes.
592: * @return mixed string or null depending on the value of `$options['block']`
593: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::scriptBlock
594: */
595: public function scriptBlock($script, $options = array()) {
596: $options += array('type' => 'text/javascript', 'safe' => true, 'inline' => true);
597: if ($options['safe']) {
598: $script = "\n" . '//<![CDATA[' . "\n" . $script . "\n" . '//]]>' . "\n";
599: }
600: if (!$options['inline'] && empty($options['block'])) {
601: $options['block'] = 'script';
602: }
603: unset($options['inline'], $options['safe']);
604:
605: $attributes = $this->_parseAttributes($options, array('block'));
606: $out = sprintf($this->_tags['javascriptblock'], $attributes, $script);
607:
608: if (empty($options['block'])) {
609: return $out;
610: }
611: $this->_View->append($options['block'], $out);
612: }
613:
614: /**
615: * Begin a script block that captures output until HtmlHelper::scriptEnd()
616: * is called. This capturing block will capture all output between the methods
617: * and create a scriptBlock from it.
618: *
619: * ### Options
620: *
621: * - `safe` Whether the code block should contain a CDATA
622: * - `inline` Should the generated script tag be output inline or in `$scripts_for_layout`
623: *
624: * @param array $options Options for the code block.
625: * @return void
626: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::scriptStart
627: */
628: public function scriptStart($options = array()) {
629: $options += array('safe' => true, 'inline' => true);
630: $this->_scriptBlockOptions = $options;
631: ob_start();
632: }
633:
634: /**
635: * End a Buffered section of JavaScript capturing.
636: * Generates a script tag inline or in `$scripts_for_layout` depending on the settings
637: * used when the scriptBlock was started
638: *
639: * @return mixed depending on the settings of scriptStart() either a script tag or null
640: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::scriptEnd
641: */
642: public function scriptEnd() {
643: $buffer = ob_get_clean();
644: $options = $this->_scriptBlockOptions;
645: $this->_scriptBlockOptions = array();
646: return $this->scriptBlock($buffer, $options);
647: }
648:
649: /**
650: * Builds CSS style data from an array of CSS properties
651: *
652: * ### Usage:
653: *
654: * ```
655: * echo $this->Html->style(array('margin' => '10px', 'padding' => '10px'), true);
656: *
657: * // creates
658: * 'margin:10px;padding:10px;'
659: * ```
660: *
661: * @param array $data Style data array, keys will be used as property names, values as property values.
662: * @param bool $oneline Whether or not the style block should be displayed on one line.
663: * @return string CSS styling data
664: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::style
665: */
666: public function style($data, $oneline = true) {
667: if (!is_array($data)) {
668: return $data;
669: }
670: $out = array();
671: foreach ($data as $key => $value) {
672: $out[] = $key . ':' . $value . ';';
673: }
674: if ($oneline) {
675: return implode(' ', $out);
676: }
677: return implode("\n", $out);
678: }
679:
680: /**
681: * Returns the breadcrumb trail as a sequence of »-separated links.
682: *
683: * If `$startText` is an array, the accepted keys are:
684: *
685: * - `text` Define the text/content for the link.
686: * - `url` Define the target of the created link.
687: *
688: * All other keys will be passed to HtmlHelper::link() as the `$options` parameter.
689: *
690: * @param string $separator Text to separate crumbs.
691: * @param string|array|bool $startText This will be the first crumb, if false it defaults to first crumb in array. Can
692: * also be an array, see above for details.
693: * @return string|null Composed bread crumbs
694: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper
695: */
696: public function getCrumbs($separator = '»', $startText = false) {
697: $crumbs = $this->_prepareCrumbs($startText);
698: if (!empty($crumbs)) {
699: $out = array();
700: foreach ($crumbs as $crumb) {
701: if (!empty($crumb[1])) {
702: $out[] = $this->link($crumb[0], $crumb[1], $crumb[2]);
703: } else {
704: $out[] = $crumb[0];
705: }
706: }
707: return implode($separator, $out);
708: }
709: return null;
710: }
711:
712: /**
713: * Returns breadcrumbs as a (x)html list
714: *
715: * This method uses HtmlHelper::tag() to generate list and its elements. Works
716: * similar to HtmlHelper::getCrumbs(), so it uses options which every
717: * crumb was added with.
718: *
719: * ### Options
720: * - `separator` Separator content to insert in between breadcrumbs, defaults to ''
721: * - `firstClass` Class for wrapper tag on the first breadcrumb, defaults to 'first'
722: * - `lastClass` Class for wrapper tag on current active page, defaults to 'last'
723: *
724: * @param array $options Array of html attributes to apply to the generated list elements.
725: * @param string|array|bool $startText This will be the first crumb, if false it defaults to first crumb in array. Can
726: * also be an array, see `HtmlHelper::getCrumbs` for details.
727: * @return string|null breadcrumbs html list
728: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper
729: */
730: public function getCrumbList($options = array(), $startText = false) {
731: $defaults = array('firstClass' => 'first', 'lastClass' => 'last', 'separator' => '', 'escape' => true);
732: $options = (array)$options + $defaults;
733: $firstClass = $options['firstClass'];
734: $lastClass = $options['lastClass'];
735: $separator = $options['separator'];
736: $escape = $options['escape'];
737: unset($options['firstClass'], $options['lastClass'], $options['separator'], $options['escape']);
738:
739: $crumbs = $this->_prepareCrumbs($startText, $escape);
740: if (empty($crumbs)) {
741: return null;
742: }
743:
744: $result = '';
745: $crumbCount = count($crumbs);
746: $ulOptions = $options;
747: foreach ($crumbs as $which => $crumb) {
748: $options = array();
749: if (empty($crumb[1])) {
750: $elementContent = $crumb[0];
751: } else {
752: $elementContent = $this->link($crumb[0], $crumb[1], $crumb[2]);
753: }
754: if (!$which && $firstClass !== false) {
755: $options['class'] = $firstClass;
756: } elseif ($which == $crumbCount - 1 && $lastClass !== false) {
757: $options['class'] = $lastClass;
758: }
759: if (!empty($separator) && ($crumbCount - $which >= 2)) {
760: $elementContent .= $separator;
761: }
762: $result .= $this->tag('li', $elementContent, $options);
763: }
764: return $this->tag('ul', $result, $ulOptions);
765: }
766:
767: /**
768: * Prepends startText to crumbs array if set
769: *
770: * @param string $startText Text to prepend
771: * @param bool $escape If the output should be escaped or not
772: * @return array Crumb list including startText (if provided)
773: */
774: protected function _prepareCrumbs($startText, $escape = true) {
775: $crumbs = $this->_crumbs;
776: if ($startText) {
777: if (!is_array($startText)) {
778: $startText = array(
779: 'url' => '/',
780: 'text' => $startText
781: );
782: }
783: $startText += array('url' => '/', 'text' => __d('cake', 'Home'));
784: list($url, $text) = array($startText['url'], $startText['text']);
785: unset($startText['url'], $startText['text']);
786: array_unshift($crumbs, array($text, $url, $startText + array('escape' => $escape)));
787: }
788: return $crumbs;
789: }
790:
791: /**
792: * Creates a formatted IMG element.
793: *
794: * This method will set an empty alt attribute if one is not supplied.
795: *
796: * ### Usage:
797: *
798: * Create a regular image:
799: *
800: * `echo $this->Html->image('cake_icon.png', array('alt' => 'CakePHP'));`
801: *
802: * Create an image link:
803: *
804: * `echo $this->Html->image('cake_icon.png', array('alt' => 'CakePHP', 'url' => 'http://cakephp.org'));`
805: *
806: * ### Options:
807: *
808: * - `url` If provided an image link will be generated and the link will point at
809: * `$options['url']`.
810: * - `fullBase` If true the src attribute will get a full address for the image file.
811: * - `plugin` False value will prevent parsing path as a plugin
812: *
813: * @param string $path Path to the image file, relative to the app/webroot/img/ directory.
814: * @param array $options Array of HTML attributes. See above for special options.
815: * @return string completed img tag
816: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::image
817: */
818: public function image($path, $options = array()) {
819: $path = $this->assetUrl($path, $options + array('pathPrefix' => Configure::read('App.imageBaseUrl')));
820: $options = array_diff_key($options, array('fullBase' => null, 'pathPrefix' => null));
821:
822: if (!isset($options['alt'])) {
823: $options['alt'] = '';
824: }
825:
826: $url = false;
827: if (!empty($options['url'])) {
828: $url = $options['url'];
829: unset($options['url']);
830: }
831:
832: $image = sprintf($this->_tags['image'], $path, $this->_parseAttributes($options));
833:
834: if ($url) {
835: return sprintf($this->_tags['link'], $this->url($url), null, $image);
836: }
837: return $image;
838: }
839:
840: /**
841: * Returns a row of formatted and named TABLE headers.
842: *
843: * @param array $names Array of tablenames. Each tablename also can be a key that points to an array with a set
844: * of attributes to its specific tag
845: * @param array $trOptions HTML options for TR elements.
846: * @param array $thOptions HTML options for TH elements.
847: * @return string Completed table headers
848: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::tableHeaders
849: */
850: public function tableHeaders($names, $trOptions = null, $thOptions = null) {
851: $out = array();
852: foreach ($names as $arg) {
853: if (!is_array($arg)) {
854: $out[] = sprintf($this->_tags['tableheader'], $this->_parseAttributes($thOptions), $arg);
855: } else {
856: $out[] = sprintf($this->_tags['tableheader'], $this->_parseAttributes(current($arg)), key($arg));
857: }
858: }
859: return sprintf($this->_tags['tablerow'], $this->_parseAttributes($trOptions), implode(' ', $out));
860: }
861:
862: /**
863: * Returns a formatted string of table rows (TR's with TD's in them).
864: *
865: * @param array $data Array of table data
866: * @param array $oddTrOptions HTML options for odd TR elements if true useCount is used
867: * @param array $evenTrOptions HTML options for even TR elements
868: * @param bool $useCount adds class "column-$i"
869: * @param bool $continueOddEven If false, will use a non-static $count variable,
870: * so that the odd/even count is reset to zero just for that call.
871: * @return string Formatted HTML
872: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::tableCells
873: */
874: public function tableCells($data, $oddTrOptions = null, $evenTrOptions = null, $useCount = false, $continueOddEven = true) {
875: if (empty($data[0]) || !is_array($data[0])) {
876: $data = array($data);
877: }
878:
879: if ($oddTrOptions === true) {
880: $useCount = true;
881: $oddTrOptions = null;
882: }
883:
884: if ($evenTrOptions === false) {
885: $continueOddEven = false;
886: $evenTrOptions = null;
887: }
888:
889: if ($continueOddEven) {
890: static $count = 0;
891: } else {
892: $count = 0;
893: }
894:
895: foreach ($data as $line) {
896: $count++;
897: $cellsOut = array();
898: $i = 0;
899: foreach ($line as $cell) {
900: $cellOptions = array();
901:
902: if (is_array($cell)) {
903: $cellOptions = $cell[1];
904: $cell = $cell[0];
905: }
906:
907: if ($useCount) {
908: if (isset($cellOptions['class'])) {
909: $cellOptions['class'] .= ' column-' . ++$i;
910: } else {
911: $cellOptions['class'] = 'column-' . ++$i;
912: }
913: }
914:
915: $cellsOut[] = sprintf($this->_tags['tablecell'], $this->_parseAttributes($cellOptions), $cell);
916: }
917: $options = $this->_parseAttributes($count % 2 ? $oddTrOptions : $evenTrOptions);
918: $out[] = sprintf($this->_tags['tablerow'], $options, implode(' ', $cellsOut));
919: }
920: return implode("\n", $out);
921: }
922:
923: /**
924: * Returns a formatted block tag, i.e DIV, SPAN, P.
925: *
926: * ### Options
927: *
928: * - `escape` Whether or not the contents should be html_entity escaped.
929: *
930: * @param string $name Tag name.
931: * @param string $text String content that will appear inside the div element.
932: * If null, only a start tag will be printed
933: * @param array $options Additional HTML attributes of the DIV tag, see above.
934: * @return string The formatted tag element
935: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::tag
936: */
937: public function tag($name, $text = null, $options = array()) {
938: if (empty($name)) {
939: return $text;
940: }
941: if (isset($options['escape']) && $options['escape']) {
942: $text = h($text);
943: unset($options['escape']);
944: }
945: if ($text === null) {
946: $tag = 'tagstart';
947: } else {
948: $tag = 'tag';
949: }
950: return sprintf($this->_tags[$tag], $name, $this->_parseAttributes($options), $text, $name);
951: }
952:
953: /**
954: * Returns a formatted existent block of $tags
955: *
956: * @param string $tag Tag name
957: * @return string Formatted block
958: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::useTag
959: */
960: public function useTag($tag) {
961: if (!isset($this->_tags[$tag])) {
962: return '';
963: }
964: $args = func_get_args();
965: array_shift($args);
966: foreach ($args as &$arg) {
967: if (is_array($arg)) {
968: $arg = $this->_parseAttributes($arg);
969: }
970: }
971: return vsprintf($this->_tags[$tag], $args);
972: }
973:
974: /**
975: * Returns a formatted DIV tag for HTML FORMs.
976: *
977: * ### Options
978: *
979: * - `escape` Whether or not the contents should be html_entity escaped.
980: *
981: * @param string $class CSS class name of the div element.
982: * @param string $text String content that will appear inside the div element.
983: * If null, only a start tag will be printed
984: * @param array $options Additional HTML attributes of the DIV tag
985: * @return string The formatted DIV element
986: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::div
987: */
988: public function div($class = null, $text = null, $options = array()) {
989: if (!empty($class)) {
990: $options['class'] = $class;
991: }
992: return $this->tag('div', $text, $options);
993: }
994:
995: /**
996: * Returns a formatted P tag.
997: *
998: * ### Options
999: *
1000: * - `escape` Whether or not the contents should be html_entity escaped.
1001: *
1002: * @param string $class CSS class name of the p element.
1003: * @param string $text String content that will appear inside the p element.
1004: * @param array $options Additional HTML attributes of the P tag
1005: * @return string The formatted P element
1006: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::para
1007: */
1008: public function para($class, $text, $options = array()) {
1009: if (isset($options['escape'])) {
1010: $text = h($text);
1011: }
1012: if ($class && !empty($class)) {
1013: $options['class'] = $class;
1014: }
1015: $tag = 'para';
1016: if ($text === null) {
1017: $tag = 'parastart';
1018: }
1019: return sprintf($this->_tags[$tag], $this->_parseAttributes($options), $text);
1020: }
1021:
1022: /**
1023: * Returns an audio/video element
1024: *
1025: * ### Usage
1026: *
1027: * Using an audio file:
1028: *
1029: * `echo $this->Html->media('audio.mp3', array('fullBase' => true));`
1030: *
1031: * Outputs:
1032: *
1033: * `<video src="http://www.somehost.com/files/audio.mp3">Fallback text</video>`
1034: *
1035: * Using a video file:
1036: *
1037: * `echo $this->Html->media('video.mp4', array('text' => 'Fallback text'));`
1038: *
1039: * Outputs:
1040: *
1041: * `<video src="/files/video.mp4">Fallback text</video>`
1042: *
1043: * Using multiple video files:
1044: *
1045: * ```
1046: * echo $this->Html->media(
1047: * array('video.mp4', array('src' => 'video.ogv', 'type' => "video/ogg; codecs='theora, vorbis'")),
1048: * array('tag' => 'video', 'autoplay')
1049: * );
1050: * ```
1051: *
1052: * Outputs:
1053: *
1054: * ```
1055: * <video autoplay="autoplay">
1056: * <source src="/files/video.mp4" type="video/mp4"/>
1057: * <source src="/files/video.ogv" type="video/ogv; codecs='theora, vorbis'"/>
1058: * </video>
1059: * ```
1060: *
1061: * ### Options
1062: *
1063: * - `tag` Type of media element to generate, either "audio" or "video".
1064: * If tag is not provided it's guessed based on file's mime type.
1065: * - `text` Text to include inside the audio/video tag
1066: * - `pathPrefix` Path prefix to use for relative URLs, defaults to 'files/'
1067: * - `fullBase` If provided the src attribute will get a full address including domain name
1068: *
1069: * @param string|array $path Path to the video file, relative to the webroot/{$options['pathPrefix']} directory.
1070: * Or an array where each item itself can be a path string or an associate array containing keys `src` and `type`
1071: * @param array $options Array of HTML attributes, and special options above.
1072: * @return string Generated media element
1073: */
1074: public function media($path, $options = array()) {
1075: $options += array(
1076: 'tag' => null,
1077: 'pathPrefix' => 'files/',
1078: 'text' => ''
1079: );
1080:
1081: if (!empty($options['tag'])) {
1082: $tag = $options['tag'];
1083: } else {
1084: $tag = null;
1085: }
1086:
1087: if (is_array($path)) {
1088: $sourceTags = '';
1089: foreach ($path as &$source) {
1090: if (is_string($source)) {
1091: $source = array(
1092: 'src' => $source,
1093: );
1094: }
1095: if (!isset($source['type'])) {
1096: $ext = pathinfo($source['src'], PATHINFO_EXTENSION);
1097: $source['type'] = $this->response->getMimeType($ext);
1098: }
1099: $source['src'] = $this->assetUrl($source['src'], $options);
1100: $sourceTags .= $this->useTag('tagselfclosing', 'source', $source);
1101: }
1102: unset($source);
1103: $options['text'] = $sourceTags . $options['text'];
1104: unset($options['fullBase']);
1105: } else {
1106: if (empty($path) && !empty($options['src'])) {
1107: $path = $options['src'];
1108: }
1109: $options['src'] = $this->assetUrl($path, $options);
1110: }
1111:
1112: if ($tag === null) {
1113: if (is_array($path)) {
1114: $mimeType = $path[0]['type'];
1115: } else {
1116: $mimeType = $this->response->getMimeType(pathinfo($path, PATHINFO_EXTENSION));
1117: }
1118: if (preg_match('#^video/#', $mimeType)) {
1119: $tag = 'video';
1120: } else {
1121: $tag = 'audio';
1122: }
1123: }
1124:
1125: if (isset($options['poster'])) {
1126: $options['poster'] = $this->assetUrl($options['poster'], array('pathPrefix' => Configure::read('App.imageBaseUrl')) + $options);
1127: }
1128: $text = $options['text'];
1129:
1130: $options = array_diff_key($options, array(
1131: 'tag' => null,
1132: 'fullBase' => null,
1133: 'pathPrefix' => null,
1134: 'text' => null
1135: ));
1136: return $this->tag($tag, $text, $options);
1137: }
1138:
1139: /**
1140: * Build a nested list (UL/OL) out of an associative array.
1141: *
1142: * @param array $list Set of elements to list
1143: * @param array $options Additional HTML attributes of the list (ol/ul) tag or if ul/ol use that as tag
1144: * @param array $itemOptions Additional HTML attributes of the list item (LI) tag
1145: * @param string $tag Type of list tag to use (ol/ul)
1146: * @return string The nested list
1147: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::nestedList
1148: */
1149: public function nestedList($list, $options = array(), $itemOptions = array(), $tag = 'ul') {
1150: if (is_string($options)) {
1151: $tag = $options;
1152: $options = array();
1153: }
1154: $items = $this->_nestedListItem($list, $options, $itemOptions, $tag);
1155: return sprintf($this->_tags[$tag], $this->_parseAttributes($options), $items);
1156: }
1157:
1158: /**
1159: * Internal function to build a nested list (UL/OL) out of an associative array.
1160: *
1161: * @param array $items Set of elements to list
1162: * @param array $options Additional HTML attributes of the list (ol/ul) tag
1163: * @param array $itemOptions Additional HTML attributes of the list item (LI) tag
1164: * @param string $tag Type of list tag to use (ol/ul)
1165: * @return string The nested list element
1166: * @see HtmlHelper::nestedList()
1167: */
1168: protected function _nestedListItem($items, $options, $itemOptions, $tag) {
1169: $out = '';
1170:
1171: $index = 1;
1172: foreach ($items as $key => $item) {
1173: if (is_array($item)) {
1174: $item = $key . $this->nestedList($item, $options, $itemOptions, $tag);
1175: }
1176: if (isset($itemOptions['even']) && $index % 2 === 0) {
1177: $itemOptions['class'] = $itemOptions['even'];
1178: } elseif (isset($itemOptions['odd']) && $index % 2 !== 0) {
1179: $itemOptions['class'] = $itemOptions['odd'];
1180: }
1181: $out .= sprintf($this->_tags['li'], $this->_parseAttributes($itemOptions, array('even', 'odd')), $item);
1182: $index++;
1183: }
1184: return $out;
1185: }
1186:
1187: /**
1188: * Load Html tag configuration.
1189: *
1190: * Loads a file from APP/Config that contains tag data. By default the file is expected
1191: * to be compatible with PhpReader:
1192: *
1193: * `$this->Html->loadConfig('tags.php');`
1194: *
1195: * tags.php could look like:
1196: *
1197: * ```
1198: * $tags = array(
1199: * 'meta' => '<meta%s>'
1200: * );
1201: * ```
1202: *
1203: * If you wish to store tag definitions in another format you can give an array
1204: * containing the file name, and reader class name:
1205: *
1206: * `$this->Html->loadConfig(array('tags.ini', 'ini'));`
1207: *
1208: * Its expected that the `tags` index will exist from any configuration file that is read.
1209: * You can also specify the path to read the configuration file from, if APP/Config is not
1210: * where the file is.
1211: *
1212: * `$this->Html->loadConfig('tags.php', APP . 'Lib' . DS);`
1213: *
1214: * Configuration files can define the following sections:
1215: *
1216: * - `tags` The tags to replace.
1217: * - `minimizedAttributes` The attributes that are represented like `disabled="disabled"`
1218: * - `docTypes` Additional doctypes to use.
1219: * - `attributeFormat` Format for long attributes e.g. `'%s="%s"'`
1220: * - `minimizedAttributeFormat` Format for minimized attributes e.g. `'%s="%s"'`
1221: *
1222: * @param string|array $configFile String with the config file (load using PhpReader) or an array with file and reader name
1223: * @param string $path Path with config file
1224: * @return mixed False to error or loaded configs
1225: * @throws ConfigureException
1226: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#changing-the-tags-output-by-htmlhelper
1227: */
1228: public function loadConfig($configFile, $path = null) {
1229: if (!$path) {
1230: $path = APP . 'Config' . DS;
1231: }
1232: $file = null;
1233: $reader = 'php';
1234:
1235: if (!is_array($configFile)) {
1236: $file = $configFile;
1237: } elseif (isset($configFile[0])) {
1238: $file = $configFile[0];
1239: if (isset($configFile[1])) {
1240: $reader = $configFile[1];
1241: }
1242: } else {
1243: throw new ConfigureException(__d('cake_dev', 'Cannot load the configuration file. Wrong "configFile" configuration.'));
1244: }
1245:
1246: $readerClass = Inflector::camelize($reader) . 'Reader';
1247: App::uses($readerClass, 'Configure');
1248: if (!class_exists($readerClass)) {
1249: throw new ConfigureException(__d('cake_dev', 'Cannot load the configuration file. Unknown reader.'));
1250: }
1251:
1252: $readerObj = new $readerClass($path);
1253: $configs = $readerObj->read($file);
1254: if (isset($configs['tags']) && is_array($configs['tags'])) {
1255: $this->_tags = $configs['tags'] + $this->_tags;
1256: }
1257: if (isset($configs['minimizedAttributes']) && is_array($configs['minimizedAttributes'])) {
1258: $this->_minimizedAttributes = $configs['minimizedAttributes'] + $this->_minimizedAttributes;
1259: }
1260: if (isset($configs['docTypes']) && is_array($configs['docTypes'])) {
1261: $this->_docTypes = $configs['docTypes'] + $this->_docTypes;
1262: }
1263: if (isset($configs['attributeFormat'])) {
1264: $this->_attributeFormat = $configs['attributeFormat'];
1265: }
1266: if (isset($configs['minimizedAttributeFormat'])) {
1267: $this->_minimizedAttributeFormat = $configs['minimizedAttributeFormat'];
1268: }
1269: return $configs;
1270: }
1271:
1272: }
1273: