On this page
Class HtmlHelper
Html Helper class for easy use of HTML widgets.
HtmlHelper encloses all methods needed while working with HTML pages.
Properties summary
-
$Url public
\Cake\View\Helper\UrlHelper
-
$_View protected
\Cake\View\View
The View instance this helper is attached to
-
$_config protected
array
Runtime config
-
$_configInitialized protected
bool
Whether the config property has already been configured with defaults
-
$_crumbs protected
array
Breadcrumbs.
-
$_defaultConfig protected
array
Default config for this class
-
$_docTypes protected
string[]
Document type definitions
-
$_helperMap protected
array
A helper lookup table used to lazy load helper objects.
-
$_includedAssets protected
array
Names of script & css files that have been included once
-
$_scriptBlockOptions protected
array
Options for the currently opened script block buffer if any.
-
$_templater protected
\Cake\View\StringTemplate
StringTemplate instance.
-
$fieldset public
array
Unused.
-
$helpers public
array
List of helpers used by this helper
-
$response public
\Cake\Http\Response
Reference to the Response object
-
$tags public
array
Unused.
Method Summary
-
__debugInfo() public
Returns an array that can be used to describe the internal state of this object.
-
_nestedListItem() protected
Internal function to build a nested list (UL/OL) out of an associative array.
-
configShallow() public
Merge provided config with existing config. Unlike
config()
which does a recursive merge for nested keys, this method does a simple merge. -
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.
Method Detail
__call() public
__call(mixed $method, mixed $params)
Provide non fatal errors on missing method calls.
Parameters
string
$method-
Method to invoke
array
$params-
Array of params for the method.
Returns
mixed|void
__construct() public
__construct(\Cake\View\View $View, array $config)
Constructor
Settings
templates
Either a filename to a config containing templates. Or an array of templates to load. See Cake\View\StringTemplate for template formatting.
Customizing tag sets
Using the templates
option you can redefine the tag HtmlHelper will use.
Parameters
\Cake\View\View
$View-
The View this helper is being attached to.
array
$config optional-
Configuration settings for the helper.
__debugInfo() public
__debugInfo()
Returns an array that can be used to describe the internal state of this object.
Returns
array
__get() public
__get(mixed $name)
Lazy loads helpers.
Parameters
string
$name-
Name of the property being accessed.
Returns
\Cake\View\Helper|null
Helper instance if helper with provided name exists
__set() public
__set(mixed $name, mixed $value)
Magic setter for removed properties.
Parameters
string
$name-
Property name.
mixed
$value-
Value to set.
_cleanConfirmMessage() protected
_cleanConfirmMessage(mixed $message)
Returns a string read to be used in confirm()
Parameters
string
$message-
The message to clean
Returns
mixed
_configDelete() protected
_configDelete(mixed $key)
Deletes a single config key.
Parameters
string
$key-
Key to delete.
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config
_configRead() protected
_configRead(mixed $key)
Reads a config key.
Parameters
string|null
$key-
Key to read.
Returns
mixed
_configWrite() protected
_configWrite(mixed $key, mixed $value, mixed $merge)
Writes a config key.
Parameters
string|array
$key-
Key to write to.
mixed
$value-
Value to write.
bool|string
$merge optional-
True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config
_confirm() protected
_confirm(mixed $message, mixed $okCode, mixed $cancelCode, mixed $options)
Returns a string to be used as onclick handler for confirm dialogs.
Parameters
string
$message-
Message to be displayed
string
$okCode-
Code to be executed after user chose 'OK'
string
$cancelCode optional-
Code to be executed after user chose 'Cancel'
array
$options optional-
Array of options
Returns
string
onclick JS code
_nestedListItem() protected
_nestedListItem(mixed $items, mixed $options, mixed $itemOptions)
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-
Options and additional HTML attributes of the list item (LI) tag.
Returns
string
The nested list element
See Also
_prepareCrumbs() protected
_prepareCrumbs(mixed $startText, mixed $escape)
Prepends startText to crumbs array if set
Parameters
string|array|bool
$startText-
Text to prepend
bool
$escape optional-
If the output should be escaped or not
Returns
array
Crumb list including startText (if provided)
_renderCells() protected
_renderCells(mixed $line, mixed $useCount)
Renders cells for a row of a table.
This is a helper method for tableCells(). Overload this method as you need to change the behavior of the cell rendering.
Parameters
array
$line-
Line data to render.
bool
$useCount optional-
Renders the count into the row. Default is false.
Returns
string[]
addClass() public
addClass(array $options, mixed $class, mixed $key)
Adds the given class to the element options
Parameters
array
$options optional-
Array options/attributes to add a class to
string|null
$class optional-
The class name being added.
string
$key optional-
the key to use for class. Defaults to
'class'
.
Returns
array
Array of options with $key set.
addCrumb() public
addCrumb(mixed $name, mixed $link, array $options)
Adds a link to the breadcrumbs array.
Parameters
string
$name-
Text for link
string|array|null
$link optional-
URL for link (if empty it won't be a link)
array
$options optional-
Link attributes e.g. ['id' => 'selected']
Returns
$this
See Also
for details on $options that can be used.
Links
charset() public
charset(mixed $charset)
Returns a charset META-tag.
Parameters
string|null
$charset optional-
The character set to be used in the meta tag. If empty, The App.encoding value will be used. Example: "utf-8".
Returns
string
A meta tag containing the specified character set.
Links
config() public
config(mixed $key, mixed $value, mixed $merge)
Gets/Sets the config.
Usage
Reading the whole config:
$this->config();
Reading a specific value:
$this->config('key');
Reading a nested value:
$this->config('some.nested.key');
Setting a specific value:
$this->config('key', $value);
Setting a nested value:
$this->config('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->config(['one' => 'value', 'another' => 'value']);
Parameters
string|array|null
$key optional-
The key to get/set, or a complete array of configs.
mixed|null
$value optional-
The value to set.
bool
$merge optional-
Whether to recursively merge or overwrite existing config, defaults to true.
Returns
mixed
Config value being read, or the object itself on write operations.
Throws
Cake\Core\Exception\Exception
When trying to set a key that is invalid.
configShallow() public
configShallow(mixed $key, mixed $value)
Merge provided config with existing config. Unlike config()
which does a recursive merge for nested keys, this method does a simple merge.
Setting a specific value:
$this->configShallow('key', $value);
Setting a nested value:
$this->configShallow('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->configShallow(['one' => 'value', 'another' => 'value']);
Parameters
string|array
$key-
The key to set, or a complete array of configs.
mixed|null
$value optional-
The value to set.
Returns
$this
css() public
css(mixed $path, array $options)
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(['one.css', 'two.css']);
Add the stylesheet to view block "css":
$this->Html->css('styles.css', ['block' => true]);
Add the stylesheet to a custom block:
$this->Html->css('styles.css', ['block' => 'layoutCss']);
Options
block
Set to true to append output to view block "css" or provide custom block name.once
Whether 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.plugin
False value will prevent parsing path as a pluginrel
Defaults to 'stylesheet'. If equal to 'import' the stylesheet will be imported.fullBase
If true the URL will get a full address for the css file.
Parameters
string|string[]
$path-
The name of a CSS style sheet or an array containing names of CSS stylesheets. If
$path
is 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 of options and HTML arguments.
Returns
string|null
CSS <link />
or <style />
tag, depending on the type of link.
Links
div() public
div(mixed $class, mixed $text, array $options)
Returns a formatted DIV tag for HTML FORMs.
Options
escape
Whether or not the contents should be html_entity escaped.
Parameters
string|null
$class optional-
CSS class name of the div element.
string|null
$text optional-
String content that will appear inside the div element. If null, only a start tag will be printed
array
$options optional-
Additional HTML attributes of the DIV tag
Returns
string
The formatted DIV element
docType() public
docType(mixed $type)
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-
Doctype to use.
Returns
string|null
Doctype string
Links
formatTemplate() public
formatTemplate(mixed $name, mixed $data)
Formats a template string with $data
Parameters
string
$name-
The template name.
array
$data-
The data to insert.
Returns
string
getConfig() public
getConfig(mixed $key, mixed $default)
Returns the config.
Usage
Reading the whole config:
$this->getConfig();
Reading a specific value:
$this->getConfig('key');
Reading a nested value:
$this->getConfig('some.nested.key');
Reading with default value:
$this->getConfig('some-key', 'default-value');
Parameters
string|null
$key optional-
The key to get or null for the whole config.
mixed|null
$default optional-
The return value when the key does not exist.
Returns
mixed|null
Configuration data at the named key or null if the key does not exist.
getConfigOrFail() public
getConfigOrFail(mixed $key)
Returns the config for this specific key.
The config value for this key must exist, it can never be null.
Parameters
string|null
$key-
The key to get.
Returns
mixed
Configuration data at the named key
Throws
InvalidArgumentException
getCrumbList() public
getCrumbList(array $options, mixed $startText)
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
separator
Separator content to insert in between breadcrumbs, defaults to ''firstClass
Class for wrapper tag on the first breadcrumb, defaults to 'first'lastClass
Class for wrapper tag on current active page, defaults to 'last'
Parameters
array
$options optional-
Array of HTML attributes to apply to the generated list elements.
string|array|bool
$startText optional-
This will be the first crumb, if false it defaults to first crumb in array. Can also be an array, see
HtmlHelper::getCrumbs
for details.
Returns
string|null
Breadcrumbs HTML list.
Links
getCrumbs() public
getCrumbs(mixed $separator, mixed $startText)
Returns the breadcrumb trail as a sequence of »-separated links.
If $startText
is an array, the accepted keys are:
text
Define the text/content for the link.url
Define 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|bool
$startText optional-
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
string|null
Composed bread crumbs
Links
getTemplates() public
getTemplates(mixed $template)
Gets templates to use or a specific template.
Parameters
string|null
$template optional-
String for reading a specific template, null for all.
Returns
string|array
getView() public
getView()
Get the view instance this helper is bound to.
Returns
\Cake\View\View
The bound view instance.
image() public
image(mixed $path, array $options)
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', ['alt' => 'CakePHP']);
Create an image link:
echo $this->Html->image('cake_icon.png', ['alt' => 'CakePHP', 'url' => 'https://cakephp.org']);
Options:
url
If provided an image link will be generated and the link will point at$options['url']
.fullBase
If true the src attribute will get a full address for the image file.plugin
False value will prevent parsing path as a plugin
Parameters
string|array
$path-
Path to the image file, relative to the webroot/img/ directory.
array
$options optional-
Array of HTML attributes. See above for special options.
Returns
string
completed img tag
Links
implementedEvents() public
implementedEvents()
Event listeners.
Returns
array
initialize() public
initialize(array $config)
Constructor hook method.
Implement this method to avoid having to overwrite the constructor and call parent.
Parameters
array
$config-
The configuration settings provided to this helper.
link() public
link(mixed $title, mixed $url, array $options)
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 UrlHelper::build() method.
If the $url is empty, $title is used instead.
Options
escape
Set to false to disable escaping of title and attributes.escapeTitle
Set to false to disable escaping of title. Takes precedence over value ofescape
)confirm
JavaScript confirmation message.
Parameters
string|array
$title-
The content to be wrapped by
<a>
tags. Can be an array if $url is null. If $url is null, $title will be used as both the URL and title. string|array|null
$url optional-
Cake-relative URL or array of URL parameters, or external URL (starts with http://)
array
$options optional-
Array of options and HTML attributes.
Returns
string
An <a />
element.
Links
media() public
media(mixed $path, array $options)
Returns an audio/video element
Usage
Using an audio file:
echo $this->Html->media('audio.mp3', ['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', ['text' => 'Fallback text']);
Outputs:
<video src="/files/video.mp4">Fallback text</video>
Using multiple video files:
echo $this->Html->media(
['video.mp4', ['src' => 'video.ogv', 'type' => "video/ogg; codecs='theora, vorbis'"]],
['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
tag
Type of media element to generate, either "audio" or "video". If tag is not provided it's guessed based on file's mime type.text
Text to include inside the audio/video tagpathPrefix
Path prefix to use for relative URLs, defaults to 'files/'fullBase
If 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
src
andtype
array
$options optional-
Array of HTML attributes, and special options above.
Returns
string
Generated media element
meta() public
meta(mixed $type, mixed $content, array $options)
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 custom view block "meta":
$this->Html->meta('description', 'A great page', ['block' => true]);
Append the meta tag to custom view block:
$this->Html->meta('description', 'A great page', ['block' => 'metaTags']);
Create a custom meta tag:
$this->Html->meta(['property' => 'og:site_name', 'content' => 'CakePHP']);
Options
block
- Set to true to append output to view block "meta" or provide custom block name.
Parameters
string|array
$type-
The title of the external resource, Or an array of attributes for a custom meta tag.
string|array|null
$content optional-
The address of the external resource or string for content attribute
array
$options optional-
Other attributes for the generated tag. If the type attribute is html, rss, atom, or icon, the mime-type is returned.
Returns
string|null
A completed <link />
element, or null if the element was sent to a block.
Links
nestedList() public
nestedList(array $list, array $options, array $itemOptions)
Build a nested list (UL/OL) out of an associative array.
Options for $options:
tag
- Type of list tag to use (ol/ul)
Options for $itemOptions:
even
- Class to use for even rows.odd
- Class to use for odd rows.
Parameters
array
$list-
Set of elements to list
array
$options optional-
Options and additional HTML attributes of the list (ol/ul) tag.
array
$itemOptions optional-
Options and additional HTML attributes of the list item (LI) tag.
Returns
string
The nested list
Links
para() public
para(mixed $class, mixed $text, array $options)
Returns a formatted P tag.
Options
escape
Whether 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-
Additional HTML attributes of the P tag
Returns
string
The formatted P element
script() public
script(mixed $url, array $options)
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(['one.js', 'two.js']);
Add the script file to a custom block:
$this->Html->script('styles.js', ['block' => 'bodyScript']);
Options
block
Set to true to append output to view block "script" or provide custom block name.once
Whether 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.plugin
False value will prevent parsing path as a pluginfullBase
If true the url will get a full address for the script file.
Parameters
string|string[]
$url-
String or array of javascript files to include
array
$options optional-
Array of options, and html attributes see above.
Returns
string|null
String of <script />
tags or null if block is specified in options or if $once is true and the file has been included before.
Links
scriptBlock() public
scriptBlock(mixed $script, array $options)
Wrap $script in a script tag.
Options
safe
(boolean) Whether or not the $script should be wrapped in<![CDATA[ ]]>
. Defaults tofalse
.block
Set to true to append output to view block "script" or provide custom block name.
Parameters
string
$script-
The script to wrap
array
$options optional-
The options to use. Options not listed above will be treated as HTML attributes.
Returns
string|null
String or null depending on the value of $options['block']
Links
scriptEnd() public
scriptEnd()
End a Buffered section of JavaScript capturing.
Generates a script tag inline or appends to specified view block depending on the settings used when the scriptBlock was started
Returns
string|null
Depending on the settings of scriptStart() either a script tag or null
Links
scriptStart() public
scriptStart(array $options)
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
safe
(boolean) Whether or not the $script should be wrapped in<![CDATA[ ]]>
. See scriptBlock().block
Set to true to append output to view block "script" or provide custom block name.
Parameters
array
$options optional-
Options for the code block.
Links
setConfig() public
setConfig(mixed $key, mixed $value, mixed $merge)
Sets the config.
Usage
Setting a specific value:
$this->setConfig('key', $value);
Setting a nested value:
$this->setConfig('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->setConfig(['one' => 'value', 'another' => 'value']);
Parameters
string|array
$key-
The key to set, or a complete array of configs.
mixed|null
$value optional-
The value to set.
bool
$merge optional-
Whether to recursively merge or overwrite existing config, defaults to true.
Returns
$this
Throws
Cake\Core\Exception\Exception
When trying to set a key that is invalid.
setTemplates() public
setTemplates(array $templates)
Sets templates to use.
Parameters
string[]
$templates-
Templates to be added.
Returns
$this
style() public
style(array $data, mixed $oneLine)
Builds CSS style data from an array of CSS properties
Usage:
echo $this->Html->style(['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.
bool
$oneLine optional-
Whether or not the style block should be displayed on one line.
Returns
string
CSS styling data
Links
tableCell() public
tableCell(mixed $content, array $options)
Renders a single table cell (A TD with attributes).
Parameters
string
$content-
The content of the cell.
array
$options optional-
HTML attributes.
Returns
string
tableCells() public
tableCells(mixed $data, mixed $oddTrOptions, mixed $evenTrOptions, mixed $useCount, mixed $continueOddEven)
Returns a formatted string of table rows (TR's with TD's in them).
Parameters
array|string
$data-
Array of table data
array|bool|null
$oddTrOptions optional-
HTML options for odd TR elements if true useCount is used
array|bool|null
$evenTrOptions optional-
HTML options for even TR elements
bool
$useCount optional-
adds class "column-$i"
bool
$continueOddEven optional-
If false, will use a non-static $count variable, so that the odd/even count is reset to zero just for that call.
Returns
string
Formatted HTML
Links
tableHeaders() public
tableHeaders(array $names, array $trOptions, array $thOptions)
Returns a row of formatted and named TABLE headers.
Parameters
array
$names-
Array of tablenames. Each tablename can be string, or array with name and an array with a set of attributes to its specific tag
array|null
$trOptions optional-
HTML options for TR elements.
array|null
$thOptions optional-
HTML options for TH elements.
Returns
string
Completed table headers
Links
tableRow() public
tableRow(mixed $content, array $options)
Renders a single table row (A TR with attributes).
Parameters
string
$content-
The content of the row.
array
$options optional-
HTML attributes.
Returns
string
tag() public
tag(mixed $name, mixed $text, array $options)
Returns a formatted block tag, i.e DIV, SPAN, P.
Options
escape
Whether or not the contents should be html_entity escaped.
Parameters
string
$name-
Tag name.
string|null
$text optional-
String content that will appear inside the div element. If null, only a start tag will be printed
array
$options optional-
Additional HTML attributes of the DIV tag, see above.
Returns
string
The formatted tag element
templater() public
templater()
Returns the templater instance.
Returns
\Cake\View\StringTemplate
templates() public
templates(mixed $templates)
Gets/sets templates to use.
Parameters
string|array|null
$templates optional-
null or string allow reading templates. An array allows templates to be added.
Returns
$this|string|array
Property Detail
$Url public
Type
\Cake\View\Helper\UrlHelper
$_View protected
The View instance this helper is attached to
Type
\Cake\View\View
$_config protected
Runtime config
Type
array
$_configInitialized protected
Whether the config property has already been configured with defaults
Type
bool
$_crumbs protected
Breadcrumbs.
Type
array
$_defaultConfig protected
Default config for this class
Type
array
$_docTypes protected
Document type definitions
Type
string[]
$_helperMap protected
A helper lookup table used to lazy load helper objects.
Type
array
$_includedAssets protected
Names of script & css files that have been included once
Type
array
$_scriptBlockOptions protected
Options for the currently opened script block buffer if any.
Type
array
$_templater protected
StringTemplate instance.
Type
\Cake\View\StringTemplate
$fieldset public
Unused.
Type
array
$helpers public
List of helpers used by this helper
Type
array
$response public
Reference to the Response object
Type
\Cake\Http\Response
$tags public
Unused.
Type
array
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.9/class-Cake.View.Helper.HtmlHelper.html