Class HtmlHelper
Html Helper class for easy use of HTML widgets.
HtmlHelper encloses all methods needed while working with HTML pages.
- AppHelper
-
HtmlHelper
Link: http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/View/Helper/HtmlHelper.php
Properties summary
-
$_crumbsprotectedarrayBreadcrumbs. -
$_docTypesprotectedarrayDocument type definitions -
$_includedAssetsprotectedarrayNames of script & css files that have been included once -
$_scriptBlockOptionsprotectedarrayOptions for the currently opened script block buffer if any. -
$_tagsprotectedarrayhtml tags used by this helper. -
$responsepublicReference to the Response object
Method Summary
-
__construct() public
Constructor -
_nestedListItem() protected
Internal function to build a nested list (UL/OL) out of an associative array. -
_prepareCrumbs() protected
Prepends startText to crumbs array if set -
addCrumb() public
Adds a link to the breadcrumbs array. -
charset() public
Returns a charset META-tag. -
css() public
Creates a link element for CSS stylesheets. -
div() public
Returns a formatted DIV tag for HTML FORMs. -
docType() public
Returns a doctype string. -
getCrumbList() public
Returns breadcrumbs as a (x)html list -
getCrumbs() public
Returns the breadcrumb trail as a sequence of »-separated links. -
image() public
Creates a formatted IMG element. -
link() public
Creates an HTML link. -
loadConfig() public
Load Html tag configuration. -
media() public
Returns an audio/video element -
meta() public
Creates a link to an external resource and handles basic meta tags -
nestedList() public
Build a nested list (UL/OL) out of an associative array. -
para() public
Returns a formatted P tag. -
script() public
Returns one or many<script>tags depending on the number of scripts given. -
scriptBlock() public
Wrap $script in a script tag. -
scriptEnd() public
End a Buffered section of JavaScript capturing. Generates a script tag inline or in
$scripts_for_layoutdepending on the settings used when the scriptBlock was started -
scriptStart() public
Begin a script block that captures output until HtmlHelper::scriptEnd() is called. This capturing block will capture all output between the methods and create a scriptBlock from it.
-
style() public
Builds CSS style data from an array of CSS properties -
tableCells() public
Returns a formatted string of table rows (TR's with TD's in them). -
tableHeaders() public
Returns a row of formatted and named TABLE headers. -
tag() public
Returns a formatted block tag, i.e DIV, SPAN, P. -
useTag() public
Returns a formatted existent block of $tags
Method Detail
__construct() public ¶
__construct( View $View , array $settings = array() )
Constructor
Settings
configFileA file containing an array of tags you wish to redefine.
Customizing tag sets
Using the configFile option you can redefine the tag HtmlHelper will use.
The file named should be compatible with HtmlHelper::loadConfig().
Parameters
-
View$View - The View this helper is being attached to.
- array $settings optional array()
- Configuration settings for the helper.
_nestedListItem() protected ¶
_nestedListItem( array $items , array $options , array $itemOptions , string $tag )
Internal function to build a nested list (UL/OL) out of an associative array.
Parameters
- array $items
- Set of elements to list
- array $options
- Additional HTML attributes of the list (ol/ul) tag
- array $itemOptions
- Additional HTML attributes of the list item (LI) tag
- string $tag
- Type of list tag to use (ol/ul)
Returns
The nested list element
See
_prepareCrumbs() protected ¶
_prepareCrumbs( string $startText , boolean $escape = true )
Prepends startText to crumbs array if set
Parameters
- string $startText
- Text to prepend
- boolean $escape optional true
- If the output should be escaped or not
Returns
Crumb list including startText (if provided)
addCrumb() public ¶
addCrumb( string $name , string $link = null , string|array $options = null )
Adds a link to the breadcrumbs array.
Parameters
- string $name
- Text for link
- string $link optional null
- URL for link (if empty it won't be a link)
- string|array $options optional null
- Link attributes e.g. array('id' => 'selected')
Returns
See
Link
charset() public ¶
charset( string $charset = null )
Returns a charset META-tag.
Parameters
- string $charset optional null
The character set to be used in the meta tag. If empty, The App.encoding value will be used. Example: "utf-8".
Returns
A meta tag containing the specified character set.
Link
css() public ¶
css( string|array $path , array $options = array() )
Creates a link element for CSS stylesheets.
Usage
Include one CSS file:
echo $this->Html->css('styles.css');
Include multiple CSS files:
echo $this->Html->css(array('one.css', 'two.css'));
Add the stylesheet to the $scripts_for_layout layout var:
$this->Html->css('styles.css', array('inline' => false));
Add the stylesheet to a custom block:
$this->Html->css('styles.css', array('block' => 'layoutCss'));
Options
inlineIf set to false, the generated tag will be appended to the 'css' block, and included in the$scripts_for_layoutlayout variable. Defaults to true.onceWhether or not the css file should be checked for uniqueness. If true css files will only be included once, use false to allow the same css to be included more than once per request.blockSet the name of the block link/style tag will be appended to. This overrides theinlineoption.pluginFalse value will prevent parsing path as a pluginrelDefaults to 'stylesheet'. If equal to 'import' the stylesheet will be imported.fullBaseIf true the URL will get a full address for the css file.
Parameters
- string|array $path
The name of a CSS style sheet or an array containing names of CSS stylesheets. If
$pathis prefixed with '/', the path will be relative to the webroot of your application. Otherwise, the path will be relative to your CSS path, usually webroot/css.- array $options optional array()
- Array of options and HTML arguments.
Returns
CSS or tag, depending on the type of link.
Link
div() public ¶
div( string $class = null , string $text = null , array $options = array() )
Returns a formatted DIV tag for HTML FORMs.
Options
escapeWhether or not the contents should be html_entity escaped.
Parameters
- string $class optional null
- CSS class name of the div element.
- string $text optional null
String content that will appear inside the div element. If null, only a start tag will be printed
- array $options optional array()
- Additional HTML attributes of the DIV tag
Returns
The formatted DIV element
Link
docType() public ¶
docType( string $type = 'html5' )
Returns a doctype string.
Possible doctypes:
- html4-strict: HTML4 Strict.
- html4-trans: HTML4 Transitional.
- html4-frame: HTML4 Frameset.
- html5: HTML5. Default value.
- xhtml-strict: XHTML1 Strict.
- xhtml-trans: XHTML1 Transitional.
- xhtml-frame: XHTML1 Frameset.
- xhtml11: XHTML1.1.
Parameters
- string $type optional 'html5'
- Doctype to use.
Returns
Doctype string
Link
getCrumbList() public ¶
getCrumbList( array $options = array() , string|array|boolean $startText = false )
Returns breadcrumbs as a (x)html list
This method uses HtmlHelper::tag() to generate list and its elements. Works similar to HtmlHelper::getCrumbs(), so it uses options which every crumb was added with.
Options
separatorSeparator content to insert in between breadcrumbs, defaults to ''firstClassClass for wrapper tag on the first breadcrumb, defaults to 'first'lastClassClass for wrapper tag on current active page, defaults to 'last'
Parameters
- array $options optional array()
- Array of html attributes to apply to the generated list elements.
- string|array|boolean $startText optional false
This will be the first crumb, if false it defaults to first crumb in array. Can also be an array, see
HtmlHelper::getCrumbsfor details.
Returns
breadcrumbs html list
Link
getCrumbs() public ¶
getCrumbs( string $separator = '»' , string|array|boolean $startText = false )
Returns the breadcrumb trail as a sequence of »-separated links.
If $startText is an array, the accepted keys are:
textDefine the text/content for the link.urlDefine the target of the created link.
All other keys will be passed to HtmlHelper::link() as the $options parameter.
Parameters
- string $separator optional '»'
- Text to separate crumbs.
- string|array|boolean $startText optional false
This will be the first crumb, if false it defaults to first crumb in array. Can also be an array, see above for details.
Returns
Composed bread crumbs
Link
image() public ¶
image( string $path , array $options = array() )
Creates a formatted IMG element.
This method will set an empty alt attribute if one is not supplied.
Usage:
Create a regular image:
echo $this->Html->image('cake_icon.png', array('alt' => 'CakePHP'));
Create an image link:
echo $this->Html->image('cake_icon.png', array('alt' => 'CakePHP', 'url' => 'http://cakephp.org'));
Options:
urlIf provided an image link will be generated and the link will point at$options['url'].fullBaseIf true the src attribute will get a full address for the image file.pluginFalse value will prevent parsing path as a plugin
Parameters
- string $path
- Path to the image file, relative to the app/webroot/img/ directory.
- array $options optional array()
- Array of HTML attributes. See above for special options.
Returns
completed img tag
Link
link() public ¶
link( string $title , string|array $url = null , array $options = array() , string $confirmMessage = false )
Creates an HTML link.
If $url starts with "http://" this is treated as an external link. Else, it is treated as a path to controller/action and parsed with the HtmlHelper::url() method.
If the $url is empty, $title is used instead.
Options
escapeSet to false to disable escaping of title and attributes.escapeTitleSet to false to disable escaping of title. (Takes precedence over value ofescape)confirmJavaScript confirmation message.
Parameters
- string $title
- The content to be wrapped by tags.
- string|array $url optional null
- Cake-relative URL or array of URL parameters, or external URL (starts with http://)
- array $options optional array()
- Array of options and HTML attributes.
- string $confirmMessage optional false
JavaScript confirmation message. This argument is deprecated as of 2.6. Use
confirmkey in $options instead.
Returns
An
<a /> element.Link
loadConfig() public ¶
loadConfig( string|array $configFile , string $path = null )
Load Html tag configuration.
Loads a file from APP/Config that contains tag data. By default the file is expected to be compatible with PhpReader:
$this->Html->loadConfig('tags.php');
tags.php could look like:
$tags = array( 'meta' => '<meta%s>' );
If you wish to store tag definitions in another format you can give an array containing the file name, and reader class name:
$this->Html->loadConfig(array('tags.ini', 'ini'));
Its expected that the tags index will exist from any configuration file that is read.
You can also specify the path to read the configuration file from, if APP/Config is not
where the file is.
$this->Html->loadConfig('tags.php', APP . 'Lib' . DS);
Configuration files can define the following sections:
tagsThe tags to replace.minimizedAttributesThe attributes that are represented likedisabled="disabled"docTypesAdditional doctypes to use.attributeFormatFormat for long attributes e.g.'%s="%s"'minimizedAttributeFormatFormat for minimized attributes e.g.'%s="%s"'
Parameters
- string|array $configFile
- String with the config file (load using PhpReader) or an array with file and reader name
- string $path optional null
- Path with config file
Returns
False to error or loaded configs
Throws
Link
media() public ¶
media( string|array $path , array $options = array() )
Returns an audio/video element
Usage
Using an audio file:
echo $this->Html->media('audio.mp3', array('fullBase' => true));
Outputs:
<video src="http://www.somehost.com/files/audio.mp3">Fallback text</video>
Using a video file:
echo $this->Html->media('video.mp4', array('text' => 'Fallback text'));
Outputs:
<video src="/files/video.mp4">Fallback text</video>
Using multiple video files:
echo $this->Html->media( array('video.mp4', array('src' => 'video.ogv', 'type' => "video/ogg; codecs='theora, vorbis'")), array('tag' => 'video', 'autoplay') );
Outputs:
<video autoplay="autoplay"> <source src="/files/video.mp4" type="video/mp4"/> <source src="/files/video.ogv" type="video/ogv; codecs='theora, vorbis'"/> </video>
Options
tagType of media element to generate, either "audio" or "video". If tag is not provided it's guessed based on file's mime type.textText to include inside the audio/video tagpathPrefixPath prefix to use for relative URLs, defaults to 'files/'fullBaseIf provided the src attribute will get a full address including domain name
Parameters
- string|array $path
Path to the video file, relative to the webroot/{$options['pathPrefix']} directory. Or an array where each item itself can be a path string or an associate array containing keys
srcandtype- array $options optional array()
- Array of HTML attributes, and special options above.
Returns
Generated media element
meta() public ¶
meta( string $type , string|array $url = null , array $options = array() )
Creates a link to an external resource and handles basic meta tags
Create a meta tag that is output inline:
`$this->Html->meta('icon', 'favicon.ico');
Append the meta tag to $scripts_for_layout:
$this->Html->meta('description', 'A great page', array('inline' => false));
Append the meta tag to custom view block:
$this->Html->meta('description', 'A great page', array('block' => 'metaTags'));
Options
inlineWhether or not the link element should be output inline. Set to false to have the meta tag included in$scripts_for_layout, and appended to the 'meta' view block.blockChoose a custom block to append the meta tag to. Using this option will override the inline option.
Parameters
- string $type
- The title of the external resource
- string|array $url optional null
- The address of the external resource or string for content attribute
- array $options optional array()
Other attributes for the generated tag. If the type attribute is html, rss, atom, or icon, the mime-type is returned.
Returns
A completed
<link /> element.Link
nestedList() public ¶
nestedList( array $list , array $options = array() , array $itemOptions = array() , string $tag = 'ul' )
Build a nested list (UL/OL) out of an associative array.
Parameters
- array $list
- Set of elements to list
- array $options optional array()
- Additional HTML attributes of the list (ol/ul) tag or if ul/ol use that as tag
- array $itemOptions optional array()
- Additional HTML attributes of the list item (LI) tag
- string $tag optional 'ul'
- Type of list tag to use (ol/ul)
Returns
The nested list
Link
para() public ¶
para( string $class , string $text , array $options = array() )
Returns a formatted P tag.
Options
escapeWhether or not the contents should be html_entity escaped.
Parameters
- string $class
- CSS class name of the p element.
- string $text
- String content that will appear inside the p element.
- array $options optional array()
- Additional HTML attributes of the P tag
Returns
The formatted P element
Link
script() public ¶
script( string|array $url , array|boolean $options = array() )
Returns one or many <script> tags depending on the number of scripts given.
If the filename is prefixed with "/", the path will be relative to the base path of your application. Otherwise, the path will be relative to your JavaScript path, usually webroot/js.
Usage
Include one script file:
echo $this->Html->script('styles.js');
Include multiple script files:
echo $this->Html->script(array('one.js', 'two.js'));
Add the script file to the $scripts_for_layout layout var:
$this->Html->script('styles.js', array('inline' => false));
Add the script file to a custom block:
$this->Html->script('styles.js', array('block' => 'bodyScript'));
Options
inlineWhether script should be output inline or into$scripts_for_layout. When set to false, the script tag will be appended to the 'script' view block as well as$scripts_for_layout.blockThe name of the block you want the script appended to. Leave undefined to output inline. Using this option will override the inline option.onceWhether or not the script should be checked for uniqueness. If true scripts will only be included once, use false to allow the same script to be included more than once per request.pluginFalse value will prevent parsing path as a pluginfullBaseIf true the url will get a full address for the script file.
Parameters
- string|array $url
- String or array of javascript files to include
- array|boolean $options optional array()
- Array of options, and html attributes see above. If boolean sets $options['inline'] = value
Returns
String of <script /> tags or null if $inline is false or if $once is true and the file has been
included before.
Link
scriptBlock() public ¶
scriptBlock( string $script , array $options = array() )
Wrap $script in a script tag.
Options
safe(boolean) Whether or not the $script should be wrapped ininline(boolean) Whether or not the $script should be added to$scripts_for_layout/scriptblock, or output inline. (Deprecated, useblockinstead)blockWhich block you want this script block appended to. Defaults toscript.
Parameters
- string $script
- The script to wrap
- array $options optional array()
The options to use. Options not listed above will be treated as HTML attributes.
Returns
string or null depending on the value of
$options['block']Link
scriptEnd() public ¶
scriptEnd( )
End a Buffered section of JavaScript capturing.
Generates a script tag inline or in $scripts_for_layout depending on the settings
used when the scriptBlock was started
Returns
depending on the settings of scriptStart() either a script tag or null
Link
scriptStart() public ¶
scriptStart( array $options = array() )
Begin a script block that captures output until HtmlHelper::scriptEnd() is called. This capturing block will capture all output between the methods and create a scriptBlock from it.
Options
safeWhether the code block should contain a CDATAinlineShould the generated script tag be output inline or in$scripts_for_layout
Parameters
- array $options optional array()
- Options for the code block.
Link
style() public ¶
style( array $data , boolean $oneline = true )
Builds CSS style data from an array of CSS properties
Usage:
echo $this->Html->style(array('margin' => '10px', 'padding' => '10px'), true); // creates 'margin:10px;padding:10px;'
Parameters
- array $data
- Style data array, keys will be used as property names, values as property values.
- boolean $oneline optional true
- Whether or not the style block should be displayed on one line.
Returns
CSS styling data
Link
tableCells() public ¶
tableCells( array $data , array $oddTrOptions = null , array $evenTrOptions = null , boolean $useCount = false , boolean $continueOddEven = true )
Returns a formatted string of table rows (TR's with TD's in them).
Parameters
- array $data
- Array of table data
- array $oddTrOptions optional null
- HTML options for odd TR elements if true useCount is used
- array $evenTrOptions optional null
- HTML options for even TR elements
- boolean $useCount optional false
- adds class "column-$i"
- boolean $continueOddEven optional true
If false, will use a non-static $count variable, so that the odd/even count is reset to zero just for that call.
Returns
Formatted HTML
Link
tableHeaders() public ¶
tableHeaders( array $names , array $trOptions = null , array $thOptions = null )
Returns a row of formatted and named TABLE headers.
Parameters
- array $names
Array of tablenames. Each tablename also can be a key that points to an array with a set of attributes to its specific tag
- array $trOptions optional null
- HTML options for TR elements.
- array $thOptions optional null
- HTML options for TH elements.
Returns
Completed table headers
Link
tag() public ¶
tag( string $name , string $text = null , array $options = array() )
Returns a formatted block tag, i.e DIV, SPAN, P.
Options
escapeWhether or not the contents should be html_entity escaped.
Parameters
- string $name
- Tag name.
- string $text optional null
String content that will appear inside the div element. If null, only a start tag will be printed
- array $options optional array()
- Additional HTML attributes of the DIV tag, see above.
Returns
The formatted tag element
Link
Properties detail
$_docTypes ¶
Document type definitions
array( 'html4-strict' => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">', 'html4-trans' => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">', 'html4-frame' => '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">', 'html5' => '<!DOCTYPE html>', 'xhtml-strict' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">', 'xhtml-trans' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">', 'xhtml-frame' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">', 'xhtml11' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">' )
$_scriptBlockOptions ¶
Options for the currently opened script block buffer if any.
array()
$_tags ¶
html tags used by this helper.
array( 'meta' => '<meta%s/>', 'metalink' => '<link href="%s"%s/>', 'link' => '<a href="%s"%s>%s</a>', 'mailto' => '<a href="mailto:%s"%s>%s</a>', 'form' => '<form action="%s"%s>', 'formend' => '</form>', 'input' => '<input name="%s"%s/>', 'textarea' => '<textarea name="%s"%s>%s</textarea>', 'hidden' => '<input type="hidden" name="%s"%s/>', 'checkbox' => '<input type="checkbox" name="%s"%s/>', 'checkboxmultiple' => '<input type="checkbox" name="%s[]"%s />', 'radio' => '<input type="radio" name="%s" id="%s"%s />%s', 'selectstart' => '<select name="%s"%s>', 'selectmultiplestart' => '<select name="%s[]"%s>', 'selectempty' => '<option value=""%s> </option>', 'selectoption' => '<option value="%s"%s>%s</option>', 'selectend' => '</select>', 'optiongroup' => '<optgroup label="%s"%s>', 'optiongroupend' => '</optgroup>', 'checkboxmultiplestart' => '', 'checkboxmultipleend' => '', 'password' => '<input type="password" name="%s"%s/>', 'file' => '<input type="file" name="%s"%s/>', 'file_no_model' => '<input type="file" name="%s"%s/>', 'submit' => '<input%s/>', 'submitimage' => '<input type="image" src="%s"%s/>', 'button' => '<button%s>%s</button>', 'image' => '<img src="%s"%s/>', 'tableheader' => '<th%s>%s</th>', 'tableheaderrow' => '<tr%s>%s</tr>', 'tablecell' => '<td%s>%s</td>', 'tablerow' => '<tr%s>%s</tr>', 'block' => '<div%s>%s</div>', 'blockstart' => '<div%s>', 'blockend' => '</div>', 'hiddenblock' => '<div style="display:none;">%s</div>', 'tag' => '<%s%s>%s</%s>', 'tagstart' => '<%s%s>', 'tagend' => '</%s>', 'tagselfclosing' => '<%s%s/>', 'para' => '<p%s>%s</p>', 'parastart' => '<p%s>', 'label' => '<label for="%s"%s>%s</label>', 'fieldset' => '<fieldset%s>%s</fieldset>', 'fieldsetstart' => '<fieldset><legend>%s</legend>', 'fieldsetend' => '</fieldset>', 'legend' => '<legend>%s</legend>', 'css' => '<link rel="%s" type="text/css" href="%s"%s/>', 'style' => '<style type="text/css"%s>%s</style>', 'charset' => '<meta http-equiv="Content-Type" content="text/html; charset=%s" />', 'ul' => '<ul%s>%s</ul>', 'ol' => '<ol%s>%s</ol>', 'li' => '<li%s>%s</li>', 'error' => '<div%s>%s</div>', 'javascriptblock' => '<script%s>%s</script>', 'javascriptstart' => '<script>', 'javascriptlink' => '<script type="text/javascript" src="%s"%s></script>', 'javascriptend' => '</script>' )