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