Page Contents

Javascript

The Javascript helper is used to aid in creating well formatted related javascript tags and codeblocks. There are several methods some of which are designed to work with the Prototype Javascript library.

The Javascript Helper is deprecated in 1.3 and will be removed in future versions of CakePHP. See the new JsHelper and HtmlHelper, as well as the migration guide for where JavascriptHelper’s methods have moved to.

Methods

codeBlock($script, $options = array('allowCache'=>true,'safe'=>true,'inline'=>true), $safe)

  • string $script - The JavaScript to be wrapped in SCRIPT tags

  • array $options - Set of options:

    • allowCache: boolean, designates whether this block is cacheable using the current cache settings.

    • safe: boolean, whether this block should be wrapped in CDATA tags. Defaults to helper’s object configuration.

    • inline: whether the block should be printed inline, or written to cached for later output (i.e. $scripts_for_layout).

  • boolean $safe - DEPRECATED. Use $options[‚safe‘] instead

codeBlock returns a formatted script element containing $script. But can also return null if Javascript helper is set to cache events. See JavascriptHelper::cacheEvents(). And can write in $scripts_for_layout if you set $options[‚inline‘] to false.

blockEnd()

Ends a block of cached Javascript. Can return either a end script tag, or empties the buffer, adding the contents to the cachedEvents array. Its return value depends on the cache settings. See JavascriptHelper::cacheEvents()

link($url, $inline = true)

  • mixed $url - String URL to JavaScript file, or an array of URLs.

  • boolean $inline If true, the <script> tag will be printed inline, otherwise it will be printed in $scripts_for_layout

Creates a javascript link to a single or many javascript files. Can output inline or in $scripts_for_layout.

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.

escapeString($string)

  • string $script - String that needs to get escaped.

Escape a string to be JavaScript friendly. Allowing it to safely be used in javascript blocks.

The characters that are escaped are:

  • „\r\n“ => ‚\n‘

  • „\r“ => ‚\n‘

  • „\n“ => ‚\n‘

  • ‚“‘ => ‚\“‘

  • „‘“ => „\\‘“

event($object, $event, $observer, $useCapture)

  • string $object - DOM Object to be observed.

  • string $event - type of event to observe ie ‚click‘, ‚over‘.

  • string $observer - Javascript function to call when event occurs.

  • array $options - Set options: useCapture, allowCache, safe

    • boolean $options[‚useCapture‘] - Whether to fire the event in the capture or bubble phase of event handling. Defaults false

    • boolean $options[‚allowCache‘] - See JavascriptHelper::cacheEvents()

    • boolean $options[‚safe‘] - Indicates whether <script /> blocks should be written ‚safely,‘ i.e. wrapped in CDATA blocks

Attach a javascript event handler specified by $event to an element DOM element specified by $object. Object does not have to be an ID reference it can refer to any valid javascript object or CSS selectors. If a CSS selector is used the event handler is cached and should be retrieved with JavascriptHelper::getCache(). This method requires the Prototype library.

cacheEvents($file, $all)

  • boolean $file - If true, code will be written to a file

  • boolean $all - If true, all code written with JavascriptHelper will be sent to a file

Allows you to control how the JavaScript Helper caches event code generated by event(). If $all is set to true, all code generated by the helper is cached and can be retrieved with getCache() or written to file or page output with writeCache().

getCache($clear)

  • boolean $clear - If set to true the cached javascript is cleared. Defaults to true.

Gets (and clears) the current JavaScript event cache

writeEvents($inline)

  • boolean $inline - If true, returns JavaScript event code. Otherwise it is added to the output of $scripts_for_layout in the layout.

Returns cached javascript code. If $file was set to true with cacheEvents(), code is cached to a file and a script link to the cached events file is returned. If inline is true, the event code is returned inline. Else it is added to the $scripts_for_layout for the page.

includeScript($script)

  • string $script - File name of script to include.

Includes the named $script. If $script is left blank the helper will include every script in your app/webroot/js directory. Includes the contents of each file inline. To create a script tag with an src attribute use link().

object($data, $options)

  • array $data - Data to be converted

  • array $options - Set of options: block, prefix, postfix, stringKeys, quoteKeys, q

    • boolean $options[‚block‘] - Wraps return value in a <script /> block if true. Defaults to false.

    • string $options[‚prefix‘] - Prepends the string to the returned data.

    • string $options[‚postfix‘] - Appends the string to the returned data.

    • array $options[‚stringKeys‘] - A list of array keys to be treated as a string.

    • boolean $options[‚quoteKeys‘] - If false, treats $stringKey as a list of keys *not* to be quoted. Defaults to true.

    • string $options[‚q‘] - The type of quote to use.

Generates a JavaScript object in JavaScript Object Notation (JSON) from $data array.