1: <?php
2: /**
3: * Javascript Generator class file.
4: *
5: * PHP 5
6: *
7: * CakePHP : Rapid Development Framework (http://cakephp.org)
8: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
9: *
10: * Licensed under The MIT License
11: * For full copyright and license information, please see the LICENSE.txt
12: * Redistributions of files must retain the above copyright notice.
13: *
14: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
15: * @link http://cakephp.org CakePHP(tm) Project
16: * @package Cake.View.Helper
17: * @since CakePHP(tm) v 1.2
18: * @license http://www.opensource.org/licenses/mit-license.php MIT License
19: */
20:
21: App::uses('AppHelper', 'View/Helper');
22: App::uses('JsBaseEngineHelper', 'View/Helper');
23: App::uses('Multibyte', 'I18n');
24:
25: /**
26: * Javascript Generator helper class for easy use of JavaScript.
27: *
28: * JsHelper provides an abstract interface for authoring JavaScript with a
29: * given client-side library.
30: *
31: * @package Cake.View.Helper
32: * @property HtmlHelper $Html
33: * @property FormHelper $Form
34: */
35: class JsHelper extends AppHelper {
36:
37: /**
38: * Whether or not you want scripts to be buffered or output.
39: *
40: * @var boolean
41: */
42: public $bufferScripts = true;
43:
44: /**
45: * Helper dependencies
46: *
47: * @var array
48: */
49: public $helpers = array('Html', 'Form');
50:
51: /**
52: * Variables to pass to Javascript.
53: *
54: * @var array
55: * @see JsHelper::set()
56: */
57: protected $_jsVars = array();
58:
59: /**
60: * Scripts that are queued for output
61: *
62: * @var array
63: * @see JsHelper::buffer()
64: */
65: protected $_bufferedScripts = array();
66:
67: /**
68: * Current Javascript Engine that is being used
69: *
70: * @var string
71: */
72: protected $_engineName;
73:
74: /**
75: * The javascript variable created by set() variables.
76: *
77: * @var string
78: */
79: public $setVariable = 'app';
80:
81: /**
82: * Constructor - determines engine helper
83: *
84: * @param View $View the view object the helper is attached to.
85: * @param array $settings Settings array contains name of engine helper.
86: */
87: public function __construct(View $View, $settings = array()) {
88: $className = 'Jquery';
89: if (is_array($settings) && isset($settings[0])) {
90: $className = $settings[0];
91: } elseif (is_string($settings)) {
92: $className = $settings;
93: }
94: $engineName = $className;
95: list(, $className) = pluginSplit($className);
96:
97: $this->_engineName = $className . 'Engine';
98: $engineClass = $engineName . 'Engine';
99: $this->helpers[] = $engineClass;
100: parent::__construct($View, $settings);
101: }
102:
103: /**
104: * call__ Allows for dispatching of methods to the Engine Helper.
105: * methods in the Engines bufferedMethods list will be automatically buffered.
106: * You can control buffering with the buffer param as well. By setting the last parameter to
107: * any engine method to a boolean you can force or disable buffering.
108: *
109: * e.g. `$js->get('#foo')->effect('fadeIn', array('speed' => 'slow'), true);`
110: *
111: * Will force buffering for the effect method. If the method takes an options array you may also add
112: * a 'buffer' param to the options array and control buffering there as well.
113: *
114: * e.g. `$js->get('#foo')->event('click', $functionContents, array('buffer' => true));`
115: *
116: * The buffer parameter will not be passed onto the EngineHelper.
117: *
118: * @param string $method Method to be called
119: * @param array $params Parameters for the method being called.
120: * @return mixed Depends on the return of the dispatched method, or it could be an instance of the EngineHelper
121: */
122: public function __call($method, $params) {
123: if ($this->{$this->_engineName} && method_exists($this->{$this->_engineName}, $method)) {
124: $buffer = false;
125: $engineHelper = $this->{$this->_engineName};
126: if (in_array(strtolower($method), $engineHelper->bufferedMethods)) {
127: $buffer = true;
128: }
129: if (count($params) > 0) {
130: $lastParam = $params[count($params) - 1];
131: $hasBufferParam = (is_bool($lastParam) || is_array($lastParam) && isset($lastParam['buffer']));
132: if ($hasBufferParam && is_bool($lastParam)) {
133: $buffer = $lastParam;
134: unset($params[count($params) - 1]);
135: } elseif ($hasBufferParam && is_array($lastParam)) {
136: $buffer = $lastParam['buffer'];
137: unset($params['buffer']);
138: }
139: }
140:
141: $out = call_user_func_array(array(&$engineHelper, $method), $params);
142: if ($this->bufferScripts && $buffer && is_string($out)) {
143: $this->buffer($out);
144: return null;
145: }
146: if (is_object($out) && $out instanceof JsBaseEngineHelper) {
147: return $this;
148: }
149: return $out;
150: }
151: if (method_exists($this, $method . '_')) {
152: return call_user_func(array(&$this, $method . '_'), $params);
153: }
154: trigger_error(__d('cake_dev', 'JsHelper:: Missing Method %s is undefined', $method), E_USER_WARNING);
155: }
156:
157: /**
158: * Overwrite inherited Helper::value()
159: * See JsBaseEngineHelper::value() for more information on this method.
160: *
161: * @param mixed $val A PHP variable to be converted to JSON
162: * @param boolean $quoteString If false, leaves string values unquoted
163: * @return string a JavaScript-safe/JSON representation of $val
164: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::value
165: */
166: public function value($val = array(), $quoteString = null, $key = 'value') {
167: if ($quoteString === null) {
168: $quoteString = true;
169: }
170: return $this->{$this->_engineName}->value($val, $quoteString);
171: }
172:
173: /**
174: * Writes all Javascript generated so far to a code block or
175: * caches them to a file and returns a linked script. If no scripts have been
176: * buffered this method will return null. If the request is an XHR(ajax) request
177: * onDomReady will be set to false. As the dom is already 'ready'.
178: *
179: * ### Options
180: *
181: * - `inline` - Set to true to have scripts output as a script block inline
182: * if `cache` is also true, a script link tag will be generated. (default true)
183: * - `cache` - Set to true to have scripts cached to a file and linked in (default false)
184: * - `clear` - Set to false to prevent script cache from being cleared (default true)
185: * - `onDomReady` - wrap cached scripts in domready event (default true)
186: * - `safe` - if an inline block is generated should it be wrapped in <![CDATA[ ... ]]> (default true)
187: *
188: * @param array $options options for the code block
189: * @return mixed Completed javascript tag if there are scripts, if there are no buffered
190: * scripts null will be returned.
191: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::writeBuffer
192: */
193: public function writeBuffer($options = array()) {
194: $domReady = !$this->request->is('ajax');
195: $defaults = array(
196: 'onDomReady' => $domReady, 'inline' => true,
197: 'cache' => false, 'clear' => true, 'safe' => true
198: );
199: $options = array_merge($defaults, $options);
200: $script = implode("\n", $this->getBuffer($options['clear']));
201:
202: if (empty($script)) {
203: return null;
204: }
205:
206: if ($options['onDomReady']) {
207: $script = $this->{$this->_engineName}->domReady($script);
208: }
209: $opts = $options;
210: unset($opts['onDomReady'], $opts['cache'], $opts['clear']);
211:
212: if ($options['cache'] && $options['inline']) {
213: $filename = md5($script);
214: if (file_exists(JS . $filename . '.js')
215: || cache(str_replace(WWW_ROOT, '', JS) . $filename . '.js', $script, '+999 days', 'public')
216: ) {
217: return $this->Html->script($filename);
218: }
219: }
220:
221: $return = $this->Html->scriptBlock($script, $opts);
222: if ($options['inline']) {
223: return $return;
224: }
225: return null;
226: }
227:
228: /**
229: * Write a script to the buffered scripts.
230: *
231: * @param string $script Script string to add to the buffer.
232: * @param boolean $top If true the script will be added to the top of the
233: * buffered scripts array. If false the bottom.
234: * @return void
235: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::buffer
236: */
237: public function buffer($script, $top = false) {
238: if ($top) {
239: array_unshift($this->_bufferedScripts, $script);
240: } else {
241: $this->_bufferedScripts[] = $script;
242: }
243: }
244:
245: /**
246: * Get all the buffered scripts
247: *
248: * @param boolean $clear Whether or not to clear the script caches (default true)
249: * @return array Array of scripts added to the request.
250: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::getBuffer
251: */
252: public function getBuffer($clear = true) {
253: $this->_createVars();
254: $scripts = $this->_bufferedScripts;
255: if ($clear) {
256: $this->_bufferedScripts = array();
257: $this->_jsVars = array();
258: }
259: return $scripts;
260: }
261:
262: /**
263: * Generates the object string for variables passed to javascript and adds to buffer
264: *
265: * @return void
266: */
267: protected function _createVars() {
268: if (!empty($this->_jsVars)) {
269: $setVar = (strpos($this->setVariable, '.')) ? $this->setVariable : 'window.' . $this->setVariable;
270: $this->buffer($setVar . ' = ' . $this->object($this->_jsVars) . ';', true);
271: }
272: }
273:
274: /**
275: * Generate an 'Ajax' link. Uses the selected JS engine to create a link
276: * element that is enhanced with Javascript. Options can include
277: * both those for HtmlHelper::link() and JsBaseEngine::request(), JsBaseEngine::event();
278: *
279: * ### Options
280: *
281: * - `confirm` - Generate a confirm() dialog before sending the event.
282: * - `id` - use a custom id.
283: * - `htmlAttributes` - additional non-standard htmlAttributes. Standard attributes are class, id,
284: * rel, title, escape, onblur and onfocus.
285: * - `buffer` - Disable the buffering and return a script tag in addition to the link.
286: *
287: * @param string $title Title for the link.
288: * @param string|array $url Mixed either a string URL or a CakePHP URL array.
289: * @param array $options Options for both the HTML element and Js::request()
290: * @return string Completed link. If buffering is disabled a script tag will be returned as well.
291: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::link
292: */
293: public function link($title, $url = null, $options = array()) {
294: if (!isset($options['id'])) {
295: $options['id'] = 'link-' . intval(mt_rand());
296: }
297: list($options, $htmlOptions) = $this->_getHtmlOptions($options);
298: $out = $this->Html->link($title, $url, $htmlOptions);
299: $this->get('#' . $htmlOptions['id']);
300: $requestString = $event = '';
301: if (isset($options['confirm'])) {
302: $requestString = $this->confirmReturn($options['confirm']);
303: unset($options['confirm']);
304: }
305: $buffer = isset($options['buffer']) ? $options['buffer'] : null;
306: $safe = isset($options['safe']) ? $options['safe'] : true;
307: unset($options['buffer'], $options['safe']);
308:
309: $requestString .= $this->request($url, $options);
310:
311: if (!empty($requestString)) {
312: $event = $this->event('click', $requestString, $options + array('buffer' => $buffer));
313: }
314: if (isset($buffer) && !$buffer) {
315: $opts = array('safe' => $safe);
316: $out .= $this->Html->scriptBlock($event, $opts);
317: }
318: return $out;
319: }
320:
321: /**
322: * Pass variables into Javascript. Allows you to set variables that will be
323: * output when the buffer is fetched with `JsHelper::getBuffer()` or `JsHelper::writeBuffer()`
324: * The Javascript variable used to output set variables can be controlled with `JsHelper::$setVariable`
325: *
326: * @param string|array $one Either an array of variables to set, or the name of the variable to set.
327: * @param string|array $two If $one is a string, $two is the value for that key.
328: * @return void
329: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::set
330: */
331: public function set($one, $two = null) {
332: $data = null;
333: if (is_array($one)) {
334: if (is_array($two)) {
335: $data = array_combine($one, $two);
336: } else {
337: $data = $one;
338: }
339: } else {
340: $data = array($one => $two);
341: }
342: if (!$data) {
343: return false;
344: }
345: $this->_jsVars = array_merge($this->_jsVars, $data);
346: }
347:
348: /**
349: * Uses the selected JS engine to create a submit input
350: * element that is enhanced with Javascript. Options can include
351: * both those for FormHelper::submit() and JsBaseEngine::request(), JsBaseEngine::event();
352: *
353: * Forms submitting with this method, cannot send files. Files do not transfer over XmlHttpRequest
354: * and require an iframe or flash.
355: *
356: * ### Options
357: *
358: * - `url` The url you wish the XHR request to submit to.
359: * - `confirm` A string to use for a confirm() message prior to submitting the request.
360: * - `method` The method you wish the form to send by, defaults to POST
361: * - `buffer` Whether or not you wish the script code to be buffered, defaults to true.
362: * - Also see options for JsHelper::request() and JsHelper::event()
363: *
364: * @param string $caption The display text of the submit button.
365: * @param array $options Array of options to use. See the options for the above mentioned methods.
366: * @return string Completed submit button.
367: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/js.html#JsHelper::submit
368: */
369: public function submit($caption = null, $options = array()) {
370: if (!isset($options['id'])) {
371: $options['id'] = 'submit-' . intval(mt_rand());
372: }
373: $formOptions = array('div');
374: list($options, $htmlOptions) = $this->_getHtmlOptions($options, $formOptions);
375: $out = $this->Form->submit($caption, $htmlOptions);
376:
377: $this->get('#' . $htmlOptions['id']);
378:
379: $options['data'] = $this->serializeForm(array('isForm' => false, 'inline' => true));
380: $requestString = $url = '';
381: if (isset($options['confirm'])) {
382: $requestString = $this->confirmReturn($options['confirm']);
383: unset($options['confirm']);
384: }
385: if (isset($options['url'])) {
386: $url = $options['url'];
387: unset($options['url']);
388: }
389: if (!isset($options['method'])) {
390: $options['method'] = 'post';
391: }
392: $options['dataExpression'] = true;
393:
394: $buffer = isset($options['buffer']) ? $options['buffer'] : null;
395: $safe = isset($options['safe']) ? $options['safe'] : true;
396: unset($options['buffer'], $options['safe']);
397:
398: $requestString .= $this->request($url, $options);
399: if (!empty($requestString)) {
400: $event = $this->event('click', $requestString, $options + array('buffer' => $buffer));
401: }
402: if (isset($buffer) && !$buffer) {
403: $opts = array('safe' => $safe);
404: $out .= $this->Html->scriptBlock($event, $opts);
405: }
406: return $out;
407: }
408:
409: /**
410: * Parse a set of Options and extract the Html options.
411: * Extracted Html Options are removed from the $options param.
412: *
413: * @param array $options Options to filter.
414: * @param array $additional Array of additional keys to extract and include in the return options array.
415: * @return array Array of js options and Htmloptions
416: */
417: protected function _getHtmlOptions($options, $additional = array()) {
418: $htmlKeys = array_merge(
419: array('class', 'id', 'escape', 'onblur', 'onfocus', 'rel', 'title', 'style'),
420: $additional
421: );
422: $htmlOptions = array();
423: foreach ($htmlKeys as $key) {
424: if (isset($options[$key])) {
425: $htmlOptions[$key] = $options[$key];
426: }
427: unset($options[$key]);
428: }
429: if (isset($options['htmlAttributes'])) {
430: $htmlOptions = array_merge($htmlOptions, $options['htmlAttributes']);
431: unset($options['htmlAttributes']);
432: }
433: return array($options, $htmlOptions);
434: }
435:
436: }
437: