Javascript¶

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.