CakePHP: the rapid development php framework: Api : HtmlHelper

HtmlHelper Class Info:

Class Declaration:

class HtmlHelper extends AppHelper

File name:

cake/libs/view/helpers/html.php

Description:

Html Helper class for easy use of HTML widgets.

HtmlHelper encloses all methods needed while working with HTML pages.

Class Inheritance

AppHelper Helper Overloadable Object

Package: cake
Subpackage: cake.cake.libs.view.helpers
Link: http://book.cakephp.org/view/1434/HTML

Properties:

Show/Hide parent properties

action string

Current action.
argSeparator string

URL argument separator character
base string

Base URL
_crumbs array

Breadcrumbs.
data array

POST data for models
helpers array

List of helpers used by this helper
here string

URL to current action.
namedArgs array

List of named arguments
params array

Parameter array.
plugin string

Plugin path
_scriptBlockOptions array

Options for the currently opened script block buffer if any.
tags array

html tags used by this helper.
theme string

The current theme name if any.
validationErrors array

Contains model validation errors of form post-backs
webroot string

Webroot path

Method Summary:

Show/Hide parent methods

addClass( $options = array ( ), $class = NULL, $key = 'class' )
addCrumb( $name, $link = NULL, $options = NULL )
afterLayout( )
afterRender( )
assetTimestamp( $path )
beforeLayout( )
beforeRender( )
cakeError( $method, $messages = array ( ) )
call__( $method, $params )
charset( $charset = NULL )
clean( $output )
__construct( )
css( $path, $rel = NULL, $options = array ( ) )
dispatchMethod( $method, $params = array ( ) )
div( $class = NULL, $text = NULL, $options = array ( ) )
docType( $type = 'xhtml-strict' )
domId( $options = NULL, $id = 'id' )
field( )
get__( $name )
getCrumbs( $separator = '»', $startText = false )
image( $path, $options = array ( ) )
_initInputField( $field, $options = array ( ) )
link( $title, $url = NULL, $options = array ( ), $confirmMessage = false )
loadConfig( $name = 'tags' )
log( $msg, $type = 2 )
meta( $type, $url = NULL, $options = array ( ) )
model( )
modelID( )
_name( $options = array ( ), $field = NULL, $key = 'name' )
nestedList( $list, $options = array ( ), $itemOptions = array ( ), $tag = 'ul' )
Object( )
output( $str )
overload( )
para( $class, $text, $options = array ( ) )
_parseAttributes( $options, $exclude = NULL, $insertBefore = ' ', $insertAfter = NULL )
_persist( $name, $return, $object, $type = NULL )
requestAction( $url, $extra = array ( ) )
_savePersistent( $name, $object )
script( $url, $options = array ( ) )
scriptBlock( $script, $options = array ( ) )
scriptEnd( )
scriptStart( $options = array ( ) )
_set( $properties = array ( ) )
set__( $name, $value )
setEntity( $entity, $setScope = false )
_stop( $status = 0 )
style( $data, $oneline = true )
tableCells( $data, $oddTrOptions = NULL, $evenTrOptions = NULL, $useCount = false, $continueOddEven = true )
tableHeaders( $names, $trOptions = NULL, $thOptions = NULL )
tag( $name, $text = NULL, $options = array ( ) )
tagIsInvalid( $model = NULL, $field = NULL, $modelID = NULL )
toString( )
url( $url = NULL, $full = false )
value( $options = array ( ), $field = NULL, $key = 'value' )
webroot( $file )

addClass

top

Adds the given class to the element options

Parameters:

array $options optional array ( )

Array options/attributes to add a class to
string $class optional NULL

The classname being added.
string $key optional 'class'

the key to use for class.

Method defined in:

cake/libs/view/helper.php on line 754

Return: array Array of options with $key set.
Access: public

addCrumb

top

Adds a link to the breadcrumbs array.

Parameters:

string $name required

Text for link
string $link optional NULL

URL for link (if empty it won't be a link)
mixed $options optional NULL

Link attributes e.g. array('id'=>'selected')

Method defined in:

cake/libs/view/helpers/html.php on line 143

Return: void
See: HtmlHelper::link() for details on $options that can be used.
Access: public

afterLayout

top

After layout callback. afterLayout is called after the layout has rendered.

Overridden in subclasses.

Method defined in:: cake/libs/view/helper.php on line 818

Return: void
Access: public

afterRender

top

After render callback. afterRender is called after the view file is rendered but before the layout has been rendered.

Overridden in subclasses.

Method defined in:: cake/libs/view/helper.php on line 796

Return: void
Access: public

assetTimestamp

top

Adds a timestamp to a file based resource based on the value of Asset.timestamp in Configure. If Asset.timestamp is true and debug > 0, or Asset.timestamp == 'force' a timestamp will be added.

Parameters:

string $path required

The file path to timestamp, the path must be inside WWW_ROOT

Method defined in:

cake/libs/view/helper.php on line 242

Return: string Path with a timestamp added, or not.
Access: public

beforeLayout

top

Before layout callback. beforeLayout is called before the layout is rendered.

Overridden in subclasses.

Method defined in:: cake/libs/view/helper.php on line 807

Return: void
Access: public

beforeRender

top

Before render callback. beforeRender is called before the view file is rendered.

Overridden in subclasses.

Method defined in:: cake/libs/view/helper.php on line 784

Return: void
Access: public

cakeError

top

Used to report user friendly errors. If there is a file app/error.php or app/app_error.php this file will be loaded error.php is the AppError class it should extend ErrorHandler class.

Parameters:

string $method required

Method to be called in the error class (AppError or ErrorHandler classes)
array $messages optional array ( )

Message that is to be displayed by the error class

Method defined in:

cake/libs/object.php on line 187

Return: error message
Access: public

call__

top

Parameters:

$method required
$params required

Method defined in:

cake/libs/view/helper.php on line 153

charset

top

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".

Method defined in:

cake/libs/view/helpers/html.php on line 253

Return: string A meta tag containing the specified character set.
Access: public
Link: http://book.cakephp.org/view/1436/charset

clean

top

Used to remove harmful tags from content. Removes a number of well known XSS attacks from content. However, is not guaranteed to remove all possiblities. Escaping content is the best way to prevent all possible attacks.

Parameters:

mixed $output required

Either an array of strings to clean or a single string to clean.

Method defined in:

cake/libs/view/helper.php on line 263

Return: cleaned content for output
Access: public

__construct

top

Class constructor, overridden in descendant classes.

Method defined in:: cake/libs/object.php on line 54

css

top

Creates a link element for CSS stylesheets.

Options

inline If set to false, the generated tag appears in the head tag of the layout. Defaults to true

Parameters:

mixed $path required

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.
string $rel optional NULL

Rel attribute. Defaults to "stylesheet". If equal to 'import' the stylesheet will be imported.
array $options optional array ( )

Array of HTML attributes.

Method defined in:

cake/libs/view/helpers/html.php on line 336

Return: string CSS <link /> or <style /> tag, depending on the type of link.
Access: public
Link: http://book.cakephp.org/view/1437/css

dispatchMethod

top

Calls a method on this object with the given parameters. Provides an OO wrapper for call_user_func_array

Parameters:

string $method required

Name of the method to call
array $params optional array ( )

Parameter list to use when calling $method

Method defined in:

cake/libs/object.php on line 107

Return: mixed Returns the result of the method call
Access: public

div

top

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

Method defined in:

cake/libs/view/helpers/html.php on line 751

Return: string The formatted DIV element
Access: public
Link: http://book.cakephp.org/view/1444/div

docType

top

Returns a doctype string.

Possible doctypes:

html4-strict: HTML4 Strict.
html4-trans: HTML4 Transitional.
html4-frame: HTML4 Frameset.
xhtml-strict: XHTML1 Strict.
xhtml-trans: XHTML1 Transitional.
xhtml-frame: XHTML1 Frameset.
xhtml11: XHTML1.1.

Parameters:

string $type optional 'xhtml-strict'

Doctype to use.

Method defined in:

cake/libs/view/helpers/html.php on line 165

Return: string Doctype string
Access: public
Link: http://book.cakephp.org/view/1439/docType

domId

top

Generates a DOM ID for the selected element, if one is not set. Uses the current View::entity() settings to generate a CamelCased id attribute.

Parameters:

mixed $options optional NULL

Either an array of html attributes to add $id into, or a string with a view entity path to get a domId for.
string $id optional 'id'

The name of the 'id' attribute.

Method defined in:

cake/libs/view/helper.php on line 584

Return: mixed If $options was an array, an array will be returned with $id set. If a string was supplied, a string will be returned.
Todo: Refactor this method to not have as many input/output options.

field

top

Gets the currently-used model field of the rendering context.

Method defined in:: cake/libs/view/helper.php on line 550

Return: string
Access: public

get__

top

Default overload methods

Parameters:

$name required

Method defined in:

cake/libs/view/helper.php on line 151

Access: protected

getCrumbs

top

Returns the breadcrumb trail as a sequence of »-separated links.

Parameters:

string $separator optional '»'

Text to separate crumbs.
string $startText optional false

This will be the first crumb, if false it defaults to first crumb in array

Method defined in:

cake/libs/view/helpers/html.php on line 563

Return: string Composed bread crumbs
Access: public

image

top

Creates a formatted IMG element. If $options['url'] is provided, an image link will be generated with the link pointed at $options['url']. This method will set an empty alt attribute if one is not supplied.

Usage

Create a regular image:

echo $html->image('cake_icon.png', array('alt' => 'CakePHP'));

Create an image link:

echo $html->image('cake_icon.png', array('alt' => 'CakePHP', 'url' => 'http://cakephp.org'));

Parameters:

string $path required

Path to the image file, relative to the app/webroot/img/ directory.
array $options optional array ( )

Array of HTML attributes.

Method defined in:

cake/libs/view/helpers/html.php on line 604

Return: string completed img tag
Access: public
Link: http://book.cakephp.org/view/1441/image

_initInputField

top

Sets the defaults for an input tag. Will set the name, value, and id attributes for an array of html attributes. Will also add a 'form-error' class if the field contains validation errors.

Parameters:

string $field required

The field name to initialize.
array $options optional array ( )

Array of options to use while initializing an input field.

Method defined in:

cake/libs/view/helper.php on line 731

Return: array Array options for the form input.
Access: protected

link

top

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.

Parameters:

string $title required

The content to be wrapped by <a> tags.
mixed $url optional NULL

Cake-relative URL or array of URL parameters, or external URL (starts with http://)
array $options optional array ( )

Array of HTML attributes.
string $confirmMessage optional false

JavaScript confirmation message.

Method defined in:

cake/libs/view/helpers/html.php on line 281

Return: string An <a /> element.
Access: public
Link: http://book.cakephp.org/view/1442/link

loadConfig

top

Parses tag templates into $this->tags.

Parameters:

$name optional 'tags'

Method defined in:

cake/libs/view/helper.php on line 164

Return: array merged tags from config/$name.php
Access: public

log

top

Convience method to write a message to CakeLog. See CakeLog::write() for more information on writing to logs.

Parameters:

string $msg required

Log message
integer $type optional 2

Error type constant. Defined in app/config/core.php.

Method defined in:

cake/libs/object.php on line 148

Return: boolean Success of log write
Access: public

model

top

Gets the currently-used model of the rendering context.

Method defined in:: cake/libs/view/helper.php on line 524

Return: string
Access: public

modelID

top

Gets the ID of the currently-used model of the rendering context.

Method defined in:: cake/libs/view/helper.php on line 539

Return: mixed
Access: public

_name

top

Gets the input field name for the current tag. Creates input name attributes using CakePHP's data[Model][field] formatting.

Parameters:

mixed $options optional array ( )

If an array, should be an array of attributes that $key needs to be added to. If a string or null, will be used as the View entity.
string $field optional NULL

If an array, should be an array of attributes that $key needs to be added to. If a string or null, will be used as the View entity.
string $key optional 'name'

The name of the attribute to be set, defaults to 'name'

Method defined in:

cake/libs/view/helper.php on line 620

Return: mixed If an array was given for $options, an array with $key set will be returned. If a string was supplied a string will be returned.
Access: protected
Todo: Refactor this method to not have as many input/output options.

nestedList

top

Build a nested list (UL/OL) out of an associative array.

Parameters:

array $list required

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)

Method defined in:

cake/libs/view/helpers/html.php on line 797

Return: string The nested list
Access: public

Object

top

A hack to support __construct() on PHP 4 Hint: descendant classes have no PHP4 class_name() constructors, so this constructor gets called first and calls the top-layer __construct() which (if present) should call parent::__construct()

Method defined in:: cake/libs/object.php on line 43

Return: Object

output

top

Returns a string generated by a helper method

This method can be overridden in subclasses to do generalized output post-processing

Parameters:

string $str required

String to be output.

Method defined in:

cake/libs/view/helper.php on line 772

Return: string
Deprecated: This method will be removed in future versions.

overload

top

Overload implementation. No need for implementation in PHP5.

Method defined in:: cake/libs/overloadable_php5.php on line 36

Access: public

para

top

Returns a formatted P tag.

Options

escape Whether or not the contents should be html_entity escaped.

Parameters:

string $class required

CSS class name of the p element.
string $text required

String content that will appear inside the p element.
array $options optional array ( )

Additional HTML attributes of the P tag

Method defined in:

cake/libs/view/helpers/html.php on line 772

Return: string The formatted P element
Access: public
Link: http://book.cakephp.org/view/1445/para

_parseAttributes

top

Returns a space-delimited string with items of the $options array. If a key of $options array happens to be one of:

'compact'
'checked'
'declare'
'readonly'
'disabled'
'selected'
'defer'
'ismap'
'nohref'
'noshade'
'nowrap'
'multiple'
'noresize'

And its value is one of:

1
true
'true'

Then the value will be reset to be identical with key's name. If the value is not one of these 3, the parameter is not output.

'escape' is a special option in that it controls the conversion of attributes to their html-entity encoded equivalents. Set to false to disable html-encoding.

If value for any option key is set to null or false, that option will be excluded from output.

Parameters:

array $options required

Array of options.
array $exclude optional NULL

Array of options to be excluded, the options here will not be part of the return.
string $insertBefore optional ' '

String to be inserted before options.
string $insertAfter optional NULL

String to be inserted after options.

Method defined in:

cake/libs/view/helper.php on line 318

Return: string Composed attributes.
Access: public

_persist

top

Checks for a persistent class file, if found file is opened and true returned If file is not found a file is created and false returned If used in other locations of the model you should choose a unique name for the persistent file There are many uses for this method, see manual for examples

Parameters:

string $name required

name of the class to persist
$return required
string $object required

the object to persist
$type optional NULL

Method defined in:

cake/libs/object.php on line 218

Return: boolean Success
Access: protected
Todo: add examples to manual

requestAction

top

Calls a controller's method from any location. Can be used to connect controllers together or tie plugins into a main application. requestAction can be used to return rendered views or fetch the return value from controller actions.

Parameters:

mixed $url required

String or array-based url.
array $extra optional array ( )

if array includes the key "return" it sets the AutoRender to true.

Method defined in:

cake/libs/object.php on line 80

Return: mixed Boolean true or false on success/failure, or contents of rendered action if 'return' is set in $extra.
Access: public

_savePersistent

top

You should choose a unique name for the persistent file

There are many uses for this method, see manual for examples

Parameters:

string $name required

name used for object to cache
object $object required

the object to persist

Method defined in:

cake/libs/object.php on line 247

Return: boolean true on save, throws error if file can not be created
Access: protected

script

top

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.

Can include one or many Javascript files.

Options

inline - Whether script should be output inline or into scripts_for_layout.
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.

Parameters:

mixed $url required

String or array of javascript files to include
mixed $options optional array ( )

Array of options, and html attributes see above. If boolean sets $options['inline'] = value

Method defined in:

cake/libs/view/helpers/html.php on line 409

Return: mixed String of <script /> tags or null if $inline is false or if $once is true and the file has been included before.
Access: public
Link: http://book.cakephp.org/view/1589/script

scriptBlock

top

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 or output inline

Parameters:

string $script required

The script to wrap
array $options optional array ( )

The options to use.

Method defined in:

cake/libs/view/helpers/html.php on line 468

Return: mixed string or null depending on the value of $options['inline']
Access: public
Link: http://book.cakephp.org/view/1604/scriptBlock

scriptEnd

top

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

Method defined in:: cake/libs/view/helpers/html.php on line 516

Return: mixed depending on the settings of scriptStart() either a script tag or null
Access: public
Link: http://book.cakephp.org/view/1606/scriptEnd

scriptStart

top

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.

Method defined in:

cake/libs/view/helpers/html.php on line 500

Return: void
Access: public
Link: http://book.cakephp.org/view/1605/scriptStart

_set

top

Allows setting of multiple properties of the object in a single line of code. Will only set properties that are part of a class declaration.

Parameters:

array $properties optional array ( )

An associative array containing properties and corresponding values.

Method defined in:

cake/libs/object.php on line 166

Return: void
Access: protected

set__

top

Parameters:

$name required
$value required

Method defined in:

cake/libs/view/helper.php on line 152

setEntity

top

Sets this helper's model and field properties to the dot-separated value-pair in $entity.

Parameters:

mixed $entity required

A field name, like "ModelName.fieldName" or "ModelName.ID.fieldName"
boolean $setScope optional false

Sets the view scope to the model specified in $tagValue

Method defined in:

cake/libs/view/helper.php on line 378

Return: void
Access: public

_stop

top

Stop execution of the current script. Wraps exit() making testing easier.

Parameters:

$status optional 0

Method defined in:

cake/libs/object.php on line 135

Return: void
Access: public

style

top

Builds CSS style data from an array of CSS properties

Usage:

echo $html->style(array('margin' => '10px', 'padding' => '10px'), true);

// creates
'margin:10px;padding:10px;'

Parameters:

array $data required

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.

Method defined in:

cake/libs/view/helpers/html.php on line 541

Return: string CSS styling data
Access: public
Link: http://book.cakephp.org/view/1440/style

tableCells

top

Returns a formatted string of table rows (TR's with TD's in them).

Parameters:

array $data required

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
bool $useCount optional false

adds class "column-$i"
bool $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.

Method defined in:

cake/libs/view/helpers/html.php on line 663

Return: string Formatted HTML
Access: public
Link: http://book.cakephp.org/view/1447/tableCells

tableHeaders

top

Returns a row of formatted and named TABLE headers.

Parameters:

array $names required

Array of tablenames.
array $trOptions optional NULL

HTML options for TR elements.
array $thOptions optional NULL

HTML options for TH elements.

Method defined in:

cake/libs/view/helpers/html.php on line 642

Return: string Completed table headers
Access: public
Link: http://book.cakephp.org/view/1446/tableHeaders

tagIsInvalid

top

Returns false if given FORM field has no errors. Otherwise it returns the constant set in the array Model->validationErrors.

Parameters:

string $model optional NULL

Model name as a string
string $field optional NULL

Fieldname as a string
integer $modelID optional NULL

Unique index identifying this record within the form

Method defined in:

cake/libs/view/helper.php on line 564

Return: boolean True on errors.

toString

top

Object-to-string conversion. Each class can override this method as necessary.

Method defined in:: cake/libs/object.php on line 64

Return: string The name of this class
Access: public

url

top

Finds URL for specified action.

Returns a URL pointing at the provided parameters.

Parameters:

mixed $url optional NULL

Either a relative string url like /products/view/23 or an array of url parameters. Using an array for urls will allow you to leverage the reverse routing features of CakePHP.
boolean $full optional false

If true, the full base URL will be prepended to the result

Method defined in:

cake/libs/view/helper.php on line 187

Return: string Full translated URL with base path.
Access: public
Link: http://book.cakephp.org/view/1448/url

value

top

Gets the data for the current tag

Parameters:

mixed $options optional array ( )

If an array, should be an array of attributes that $key needs to be added to. If a string or null, will be used as the View entity.
string $field optional NULL

If an array, should be an array of attributes that $key needs to be added to. If a string or null, will be used as the View entity.
string $key optional 'value'

The name of the attribute to be set, defaults to 'value'

Method defined in:

cake/libs/view/helper.php on line 666

Return: mixed If an array was given for $options, an array with $key set will be returned. If a string was supplied a string will be returned.
Access: public
Todo: Refactor this method to not have as many input/output options.

webroot

top

Checks if a file exists when theme is used, if no file is found default location is returned

Parameters:

string $file required

The file to create a webroot path to.

Method defined in:

cake/libs/view/helper.php on line 198

Return: string Web accessible path to file.
Access: public

The API

HtmlHelper Class Info:

Properties:

action string

argSeparator string

base string

_crumbs array

data array

helpers array

here string

namedArgs array

params array

plugin string

_scriptBlockOptions array

tags array

theme string

validationErrors array

webroot string

Method Summary:

addClass

addCrumb

afterLayout

afterRender

assetTimestamp

beforeLayout

beforeRender

cakeError

call__

charset

clean

__construct

css

Options

dispatchMethod

div

Options

docType

domId

field

get__

getCrumbs

image

Usage

_initInputField

link

Options

loadConfig

log

meta

Options

model

modelID

_name

nestedList

Object

output

overload

para

Options

_parseAttributes

_persist

requestAction

_savePersistent

script

Options

scriptBlock

Options

scriptEnd

scriptStart

Options

_set

set__

setEntity

_stop

style

Usage:

tableCells

tableHeaders

tag

Options