Class HtmlHelper

__construct()source public

__construct( View $View , array $settings array() )

Constructor

Settings

• configFile A 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()source 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

string
The nested list element

See

HtmlHelper::nestedList()

_prepareCrumbs()source 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

array
Crumb list including startText (if provided)

addCrumb()source 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

HtmlHelper

See

HtmlHelper::link() for details on $options that can be used.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper

charset()source 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

string
A meta tag containing the specified character set.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::charset

css()source 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

• inline If set to false, the generated tag will be appended to the 'css' block, and included in the $scripts_for_layout layout variable. Defaults to true.
• 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.
• block Set the name of the block link/style tag will be appended to. This overrides the inline option.
• plugin False value will prevent parsing path as a plugin
• rel 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|array $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()

Array of options and HTML arguments.

Returns

string
CSS <link /> or <style /> tag, depending on the type of link.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::css

div()source public

div( string $class null , string $text null , array $options array() )

Returns a formatted DIV tag for HTML FORMs.

Options

• escape Whether 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

string
The formatted DIV element

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::div

docType()source 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

string|null
Doctype string

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::docType

getCrumbList()source 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

• 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()

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::getCrumbs for details.

Returns

string|null
breadcrumbs html list

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper

getCrumbs()source 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:

• 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|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

string|null
Composed bread crumbs

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper

image()source 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:

• 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 $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

string
completed img tag

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::image

link()source 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

• escape Set to false to disable escaping of title and attributes.
• escapeTitle Set to false to disable escaping of title. (Takes precedence over value of escape)
• confirm JavaScript confirmation message.

Parameters

string $title

The content to be wrapped by <a> 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 confirm key in $options instead.

Returns

string
An <a /> element.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::link

loadConfig()source 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:

• tags The tags to replace.
• minimizedAttributes The attributes that are represented like disabled="disabled"
• docTypes Additional doctypes to use.
• attributeFormat Format for long attributes e.g. '%s="%s"'
• minimizedAttributeFormat Format 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

mixed
False to error or loaded configs

Throws

ConfigureException

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#changing-the-tags-output-by-htmlhelper

media()source 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

• 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 tag
• pathPrefix 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 and type

array $options optional array()

Array of HTML attributes, and special options above.

Returns

string
Generated media element

meta()source 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

• inline Whether 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.
• block Choose 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

string
A completed <link /> element.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::meta

nestedList()source 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

string
The nested list

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::nestedList

para()source public

para( string $class , string $text , array $options array() )

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 array()

Additional HTML attributes of the P tag

Returns

string
The formatted P element

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::para

script()source 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

• inline Whether 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.
• block The name of the block you want the script appended to. Leave undefined to output inline. Using this option will override the inline option.
• 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 plugin
• fullBase If 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

mixed

String of <script /> tags or null if $inline is false or if $once is true and the file has been included before.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::script

scriptBlock()source public

scriptBlock( string $script , array $options array() )

Wrap $script in a script tag.

Options

• safe (boolean) Whether or not the $script should be wrapped in <![CDATA[ ]]>
• inline (boolean) Whether or not the $script should be added to $scripts_for_layout / script block, or output inline. (Deprecated, use block instead)
• block Which block you want this script block appended to. Defaults to script.

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

mixed
string or null depending on the value of $options['block']

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::scriptBlock

scriptEnd()source 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

mixed
depending on the settings of scriptStart() either a script tag or null

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::scriptEnd

scriptStart()source 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

• safe Whether the code block should contain a CDATA
• inline Should the generated script tag be output inline or in $scripts_for_layout

Parameters

array $options optional array()

Options for the code block.

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::scriptStart

style()source 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

string
CSS styling data

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::style

tableCells()source 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

string
Formatted HTML

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::tableCells

tableHeaders()source 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

string
Completed table headers

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::tableHeaders

tag()source public

tag( string $name , string $text null , array $options array() )

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 $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

string
The formatted tag element

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::tag

useTag()source public

useTag( string $tag )

Returns a formatted existent block of $tags

Parameters

string $tag

Tag name

Returns

string
Formatted block

Link

http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::useTag

array()

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">'
)

array()

array()

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>',
    'formwithoutaction' => '<form%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>&nbsp;</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>'
)