* Copyright 2005-2008, Cake Software Foundation, Inc.
* 1785 E. Sahara Avenue, Suite 490-204
* Las Vegas, Nevada 89104
*
* Licensed under The MIT License
* Redistributions of files must retain the above copyright notice.
*
* @filesource
* @copyright Copyright 2005-2008, Cake Software Foundation, Inc.
* @link http://www.cakefoundation.org/projects/info/cakephp CakePHP(tm) Project
* @package cake
* @subpackage cake.cake.libs.view.helpers
* @since CakePHP(tm) v 0.10.0.1076
* @version $Revision$
* @modifiedby $LastChangedBy$
* @lastmodified $Date$
* @license http://www.opensource.org/licenses/mit-license.php The MIT License
*/
/**
* Javascript Helper class for easy use of JavaScript.
*
* JavascriptHelper encloses all methods needed while working with JavaScript.
*
* @package cake
* @subpackage cake.cake.libs.view.helpers
*/
class JavascriptHelper extends AppHelper {
/**
* Determines whether native JSON extension is used for encoding. Set by object constructor.
*
* @var boolean
* @access public
*/
var $useNative = false;
/**
* If true, automatically writes events to the end of a script or to an external JavaScript file
* at the end of page execution
*
* @var boolean
* @access public
*/
var $enabled = true;
/**
* Indicates whether blocks should be written 'safely,' i.e. wrapped in CDATA blocks
*
* @var boolean
* @access public
*/
var $safe = false;
/**
* HTML tags used by this helper.
*
* @var array
* @access public
*/
var $tags = array(
'javascriptblock' => '',
'javascriptstart' => '',
'javascriptend' => ''
);
/**
* Holds options passed to codeBlock(), saved for when block is dumped to output
*
* @var array
* @access protected
* @see JavascriptHelper::codeBlock()
*/
var $_blockOptions = array();
/**
* Caches events written by event() for output at the end of page execution
*
* @var array
* @access protected
* @see JavascriptHelper::event()
*/
var $_cachedEvents = array();
/**
* Indicates whether generated events should be cached for later output (can be written at the end of the page,
* in the , or to an external file).
*
* @var boolean
* @access protected
* @see JavascriptHelper::event()
* @see JavascriptHelper::writeEvents()
*/
var $_cacheEvents = false;
/**
* Indicates whether cached events should be written to an external file
*
* @var boolean
* @access protected
* @see JavascriptHelper::event()
* @see JavascriptHelper::writeEvents()
*/
var $_cacheToFile = false;
/**
* Indicates whether *all* generated JavaScript should be cached for later output
*
* @var boolean
* @access protected
* @see JavascriptHelper::codeBlock()
* @see JavascriptHelper::blockEnd()
*/
var $_cacheAll = false;
/**
* Contains event rules attached with CSS selectors. Used with the event:Selectors JavaScript library.
*
* @var array
* @access protected
* @see JavascriptHelper::event()
* @link http://alternateidea.com/event-selectors/
*/
var $_rules = array();
/**
* @var string
* @access private
*/
var $__scriptBuffer = null;
/**
* Constructor. Checks for presence of native PHP JSON extension to use for object encoding
*
* @access public
*/
function __construct($options = array()) {
if (!empty($options)) {
foreach ($options as $key => $val) {
if (is_numeric($key)) {
$key = $val;
$val = true;
}
switch ($key) {
case 'cache':
break;
case 'safe':
$this->safe = $val;
break;
}
}
}
$this->useNative = function_exists('json_encode');
return parent::__construct($options);
}
/**
* Returns a JavaScript script tag.
*
* @param string $script The JavaScript to be wrapped in SCRIPT tags.
* @param array $options Set of options: allowCache, safe
* @param boolean $safe DEPRECATED. Use $options['safe'] instead
* @return string The full SCRIPT element, with the JavaScript inside it.
*/
function codeBlock($script = null, $options = array(), $safe = true) {
if (!empty($options) && !is_array($options)) {
$options = array('allowCache' => $options);
} else if (empty($options)) {
$options = array();
}
$defaultOptions = array('allowCache' => true, 'safe' => true, 'inline' => true);
$options = array_merge($defaultOptions, compact('safe'), $options);
if ($this->_cacheEvents && $this->_cacheAll && $options['allowCache'] && $script !== null) {
$this->_cachedEvents[] = $script;
} else {
$block = ($script !== null);
$safe = ($options['safe'] || $this->safe);
if ($safe && !($this->_cacheAll && $options['allowCache'])) {
$script = "\n" . '//' . "\n";
}
}
if ($script === null) {
$this->__scriptBuffer = @ob_get_contents();
$this->_blockOptions = $options;
$this->inBlock = true;
@ob_end_clean();
ob_start();
return null;
} else if (!$block) {
$this->_blockOptions = $options;
}
if ($options['inline']) {
if ($block) {
return sprintf($this->tags['javascriptblock'], $script);
} else {
return sprintf($this->tags['javascriptstart']).ife($safe, "\n" . '//addScript(sprintf($this->tags['javascriptblock'], $script));
}
}
}
/**
* Ends a block of cached JavaScript code
*
* @return mixed
*/
function blockEnd() {
$script = @ob_get_contents();
@ob_end_clean();
ob_start();
echo $this->__scriptBuffer;
$this->__scriptBuffer = null;
$options = $this->_blockOptions;
$safe = ((isset($options['safe']) && $options['safe']) || $this->safe);
$this->_blockOptions = array();
$this->inBlock = false;
if (isset($options['inline']) && !$options['inline']) {
$view =& ClassRegistry::getObject('view');
$view->addScript(sprintf($this->tags['javascriptblock'], $script));
}
if (!empty($script) && $this->_cacheAll && $options['allowCache']) {
$this->_cachedEvents[] = $script;
return null;
}
return ife($safe, "\n" . '//]]>' . "\n", '').$this->tags['javascriptend'];
}
/**
* Returns a JavaScript include tag (SCRIPT element). 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.
*
* @param mixed $url String URL to JavaScript file, or an array of URLs.
* @param boolean $inline If true, the tag will be printed inline,
* otherwise it will be printed in the