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