1: <?php
  2: /**
  3:  * jQuery Engine Helper for JsHelper
  4:  *
  5:  * Provides jQuery specific Javascript for JsHelper.
  6:  *
  7:  * Implements the JsHelper interface for jQuery. All $options arrays
  8:  * support all options found in the JsHelper, as well as those in the jQuery
  9:  * documentation.
 10:  *
 11:  * PHP 5
 12:  *
 13:  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
 14:  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
 15:  *
 16:  * Licensed under The MIT License
 17:  * For full copyright and license information, please see the LICENSE.txt
 18:  * Redistributions of files must retain the above copyright notice.
 19:  *
 20:  * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
 21:  * @link          http://cakephp.org CakePHP(tm) Project
 22:  * @package       Cake.View.Helper
 23:  * @since         CakePHP(tm) v 1.3
 24:  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
 25:  */
 26: 
 27: App::uses('AppHelper', 'View/Helper');
 28: App::uses('JsBaseEngineHelper', 'View/Helper');
 29: 
 30: /**
 31:  * jQuery Engine Helper for JsHelper
 32:  *
 33:  * Provides jQuery specific Javascript for JsHelper.
 34:  *
 35:  * Implements the JsHelper interface for jQuery. All $options arrays
 36:  * support all options found in the JsHelper, as well as those in the jQuery
 37:  * documentation.
 38:  *
 39:  * @package       Cake.View.Helper
 40:  */
 41: class JqueryEngineHelper extends JsBaseEngineHelper {
 42: 
 43: /**
 44:  * Option mappings for jQuery
 45:  *
 46:  * @var array
 47:  */
 48:     protected $_optionMap = array(
 49:         'request' => array(
 50:             'type' => 'dataType',
 51:             'before' => 'beforeSend',
 52:             'method' => 'type',
 53:         ),
 54:         'sortable' => array(
 55:             'complete' => 'stop',
 56:         ),
 57:         'drag' => array(
 58:             'snapGrid' => 'grid',
 59:             'container' => 'containment',
 60:         ),
 61:         'drop' => array(
 62:             'leave' => 'out',
 63:             'hover' => 'over'
 64:         ),
 65:         'slider' => array(
 66:             'complete' => 'stop',
 67:             'direction' => 'orientation'
 68:         )
 69:     );
 70: 
 71: /**
 72:  * Callback arguments lists
 73:  *
 74:  * @var string
 75:  */
 76:     protected $_callbackArguments = array(
 77:         'slider' => array(
 78:             'start' => 'event, ui',
 79:             'slide' => 'event, ui',
 80:             'change' => 'event, ui',
 81:             'stop' => 'event, ui'
 82:         ),
 83:         'sortable' => array(
 84:             'start' => 'event, ui',
 85:             'sort' => 'event, ui',
 86:             'change' => 'event, ui',
 87:             'beforeStop' => 'event, ui',
 88:             'stop' => 'event, ui',
 89:             'update' => 'event, ui',
 90:             'receive' => 'event, ui',
 91:             'remove' => 'event, ui',
 92:             'over' => 'event, ui',
 93:             'out' => 'event, ui',
 94:             'activate' => 'event, ui',
 95:             'deactivate' => 'event, ui'
 96:         ),
 97:         'drag' => array(
 98:             'start' => 'event, ui',
 99:             'drag' => 'event, ui',
100:             'stop' => 'event, ui',
101:         ),
102:         'drop' => array(
103:             'activate' => 'event, ui',
104:             'deactivate' => 'event, ui',
105:             'over' => 'event, ui',
106:             'out' => 'event, ui',
107:             'drop' => 'event, ui'
108:         ),
109:         'request' => array(
110:             'beforeSend' => 'XMLHttpRequest',
111:             'error' => 'XMLHttpRequest, textStatus, errorThrown',
112:             'success' => 'data, textStatus',
113:             'complete' => 'XMLHttpRequest, textStatus',
114:             'xhr' => ''
115:         )
116:     );
117: 
118: /**
119:  * The variable name of the jQuery Object, useful
120:  * when jQuery is put into noConflict() mode.
121:  *
122:  * @var string
123:  */
124:     public $jQueryObject = '$';
125: 
126: /**
127:  * Helper function to wrap repetitive simple method templating.
128:  *
129:  * @param string $method The method name being generated.
130:  * @param string $template The method template
131:  * @param array $options Array of options for method
132:  * @param array $extraSafeKeys Extra safe keys
133:  * @return string Composed method string
134:  */
135:     protected function _methodTemplate($method, $template, $options, $extraSafeKeys = array()) {
136:         $options = $this->_mapOptions($method, $options);
137:         $options = $this->_prepareCallbacks($method, $options);
138:         $callbacks = array_keys($this->_callbackArguments[$method]);
139:         if (!empty($extraSafeKeys)) {
140:             $callbacks = array_merge($callbacks, $extraSafeKeys);
141:         }
142:         $options = $this->_parseOptions($options, $callbacks);
143:         return sprintf($template, $this->selection, $options);
144:     }
145: 
146: /**
147:  * Create javascript selector for a CSS rule
148:  *
149:  * @param string $selector The selector that is targeted
150:  * @return JqueryEngineHelper instance of $this. Allows chained methods.
151:  */
152:     public function get($selector) {
153:         if ($selector === 'window' || $selector === 'document') {
154:             $this->selection = $this->jQueryObject . '(' . $selector . ')';
155:         } else {
156:             $this->selection = $this->jQueryObject . '("' . $selector . '")';
157:         }
158:         return $this;
159:     }
160: 
161: /**
162:  * Add an event to the script cache. Operates on the currently selected elements.
163:  *
164:  * ### Options
165:  *
166:  * - 'wrap' - Whether you want the callback wrapped in an anonymous function. (defaults true)
167:  * - 'stop' - Whether you want the event to stopped. (defaults true)
168:  *
169:  * @param string $type Type of event to bind to the current dom id
170:  * @param string $callback The Javascript function you wish to trigger or the function literal
171:  * @param array $options Options for the event.
172:  * @return string completed event handler
173:  */
174:     public function event($type, $callback, $options = array()) {
175:         $defaults = array('wrap' => true, 'stop' => true);
176:         $options = array_merge($defaults, $options);
177: 
178:         $function = 'function (event) {%s}';
179:         if ($options['wrap'] && $options['stop']) {
180:             $callback .= "\nreturn false;";
181:         }
182:         if ($options['wrap']) {
183:             $callback = sprintf($function, $callback);
184:         }
185:         return sprintf('%s.bind("%s", %s);', $this->selection, $type, $callback);
186:     }
187: 
188: /**
189:  * Create a domReady event. For jQuery. This method does not
190:  * bind a 'traditional event' as `$(document).bind('ready', fn)`
191:  * Works in an entirely different fashion than  `$(document).ready()`
192:  * The first will not run the function when eval()'d as part of a response
193:  * The second will. Because of the way that ajax pagination is done
194:  * `$().ready()` is used.
195:  *
196:  * @param string $functionBody The code to run on domReady
197:  * @return string completed domReady method
198:  */
199:     public function domReady($functionBody) {
200:         return $this->jQueryObject . '(document).ready(function () {' . $functionBody . '});';
201:     }
202: 
203: /**
204:  * Create an iteration over the current selection result.
205:  *
206:  * @param string $callback The function body you wish to apply during the iteration.
207:  * @return string completed iteration
208:  */
209:     public function each($callback) {
210:         return $this->selection . '.each(function () {' . $callback . '});';
211:     }
212: 
213: /**
214:  * Trigger an Effect.
215:  *
216:  * @param string $name The name of the effect to trigger.
217:  * @param array $options Array of options for the effect.
218:  * @return string completed string with effect.
219:  * @see JsBaseEngineHelper::effect()
220:  */
221:     public function effect($name, $options = array()) {
222:         $speed = null;
223:         if (isset($options['speed']) && in_array($options['speed'], array('fast', 'slow'))) {
224:             $speed = $this->value($options['speed']);
225:         }
226:         $effect = '';
227:         switch ($name) {
228:             case 'slideIn':
229:             case 'slideOut':
230:                 $name = ($name === 'slideIn') ? 'slideDown' : 'slideUp';
231:             case 'hide':
232:             case 'show':
233:             case 'fadeIn':
234:             case 'fadeOut':
235:             case 'slideDown':
236:             case 'slideUp':
237:                 $effect = ".$name($speed);";
238:                 break;
239:         }
240:         return $this->selection . $effect;
241:     }
242: 
243: /**
244:  * Create an $.ajax() call.
245:  *
246:  * If the 'update' key is set, success callback will be overridden.
247:  *
248:  * @param string|array $url
249:  * @param array $options See JsHelper::request() for options.
250:  * @return string The completed ajax call.
251:  * @see JsBaseEngineHelper::request() for options list.
252:  */
253:     public function request($url, $options = array()) {
254:         $url = html_entity_decode($this->url($url), ENT_COMPAT, Configure::read('App.encoding'));
255:         $options = $this->_mapOptions('request', $options);
256:         if (isset($options['data']) && is_array($options['data'])) {
257:             $options['data'] = $this->_toQuerystring($options['data']);
258:         }
259:         $options['url'] = $url;
260:         if (isset($options['update'])) {
261:             $wrapCallbacks = isset($options['wrapCallbacks']) ? $options['wrapCallbacks'] : true;
262:             $success = '';
263:             if (isset($options['success']) && !empty($options['success'])) {
264:                 $success .= $options['success'];
265:             }
266:             $success .= $this->jQueryObject . '("' . $options['update'] . '").html(data);';
267:             if (!$wrapCallbacks) {
268:                 $success = 'function (data, textStatus) {' . $success . '}';
269:             }
270:             $options['dataType'] = 'html';
271:             $options['success'] = $success;
272:             unset($options['update']);
273:         }
274:         $callbacks = array('success', 'error', 'beforeSend', 'complete');
275:         if (!empty($options['dataExpression'])) {
276:             $callbacks[] = 'data';
277:             unset($options['dataExpression']);
278:         }
279:         $options = $this->_prepareCallbacks('request', $options);
280:         $options = $this->_parseOptions($options, $callbacks);
281:         return $this->jQueryObject . '.ajax({' . $options . '});';
282:     }
283: 
284: /**
285:  * Create a sortable element.
286:  *
287:  * Requires both Ui.Core and Ui.Sortables to be loaded.
288:  *
289:  * @param array $options Array of options for the sortable.
290:  * @return string Completed sortable script.
291:  * @see JsBaseEngineHelper::sortable() for options list.
292:  */
293:     public function sortable($options = array()) {
294:         $template = '%s.sortable({%s});';
295:         return $this->_methodTemplate('sortable', $template, $options);
296:     }
297: 
298: /**
299:  * Create a Draggable element
300:  *
301:  * Requires both Ui.Core and Ui.Draggable to be loaded.
302:  *
303:  * @param array $options Array of options for the draggable element.
304:  * @return string Completed Draggable script.
305:  * @see JsBaseEngineHelper::drag() for options list.
306:  */
307:     public function drag($options = array()) {
308:         $template = '%s.draggable({%s});';
309:         return $this->_methodTemplate('drag', $template, $options);
310:     }
311: 
312: /**
313:  * Create a Droppable element
314:  *
315:  * Requires both Ui.Core and Ui.Droppable to be loaded.
316:  *
317:  * @param array $options Array of options for the droppable element.
318:  * @return string Completed Droppable script.
319:  * @see JsBaseEngineHelper::drop() for options list.
320:  */
321:     public function drop($options = array()) {
322:         $template = '%s.droppable({%s});';
323:         return $this->_methodTemplate('drop', $template, $options);
324:     }
325: 
326: /**
327:  * Create a Slider element
328:  *
329:  * Requires both Ui.Core and Ui.Slider to be loaded.
330:  *
331:  * @param array $options Array of options for the droppable element.
332:  * @return string Completed Slider script.
333:  * @see JsBaseEngineHelper::slider() for options list.
334:  */
335:     public function slider($options = array()) {
336:         $callbacks = array('start', 'change', 'slide', 'stop');
337:         $template = '%s.slider({%s});';
338:         return $this->_methodTemplate('slider', $template, $options, $callbacks);
339:     }
340: 
341: /**
342:  * Serialize a form attached to $selector. If the current selection is not an input or
343:  * form, errors will be created in the Javascript.
344:  *
345:  * @param array $options Options for the serialization
346:  * @return string completed form serialization script.
347:  * @see JsBaseEngineHelper::serializeForm() for option list.
348:  */
349:     public function serializeForm($options = array()) {
350:         $options = array_merge(array('isForm' => false, 'inline' => false), $options);
351:         $selector = $this->selection;
352:         if (!$options['isForm']) {
353:             $selector = $this->selection . '.closest("form")';
354:         }
355:         $method = '.serialize()';
356:         if (!$options['inline']) {
357:             $method .= ';';
358:         }
359:         return $selector . $method;
360:     }
361: 
362: }
363: