Docs/Class/Class.Extras.md

   1 Class: Chain {#Chain}
   2 =====================
   3
   4 A Utility Class which executes functions one after another, with each function firing after completion of the previous.
   5 Its methods can be implemented with [Class:implement][] into any [Class][], and it is currently implemented in [Fx][] and [Request][].
   6 In [Fx][], for example, it is used to create custom, complex animations.
   7
   8
   9
  10 Chain Method: constructor {#Chain:constructor}
  11 ----------------------------------------------
  12
  13
  14 ### Syntax:
  15
  16 #### For new classes:
  17
  18         var MyClass = new Class({ Implements: Chain });
  19
  20 #### For existing classes:
  21
  22         MyClass.implement(Chain);
  23
  24 #### Stand alone
  25
  26         var myChain = new Chain;
  27
  28 ### Example:
  29
  30                 var Todo = new Class({
  31                         Implements: Chain,
  32                         initialize: function(){
  33                                 this.chain.apply(this, arguments);
  34                         }
  35                 });
  36
  37                 var myTodoList = new Todo(
  38                         function(){ alert('get groceries');     },
  39                         function(){ alert('go workout'); },
  40                         function(){ alert('code mootools documentation until eyes close involuntarily'); },
  41                         function(){ alert('sleep');     }
  42                 );
  43
  44 ### See Also:
  45
  46 - [Class][]
  47
  48
  49
  50 Chain Method: chain {#Chain:chain}
  51 ----------------------------------
  52
  53 Adds functions to the end of the call stack of the Chain instance.
  54
  55 ### Syntax:
  56
  57         myClass.chain(fn[, fn2[, fn3[, ...]]]);
  58
  59 ### Arguments:
  60
  61 1. fn - (*function* or *array*) The function (or array of functions) to add to the chain call stack. Will accept and number of functions or arrays of functions.
  62
  63 ### Returns:
  64
  65 * (*object*) The current Class instance. Calls to chain can also be chained.
  66
  67 ### Example:
  68         //Fx.Tween has already implemented the Chain class because of inheritance of the Fx class.
  69         var myFx = new Fx.Tween('myElement', {property: 'opacity'});
  70         myFx.start(1,0).chain(
  71                 //Notice that "this" refers to the calling object (in this case, the myFx object).
  72                 function(){ this.start(0,1); },
  73                 function(){ this.start(1,0); },
  74                 function(){ this.start(0,1); }
  75         ); //Will fade the Element out and in twice.
  76
  77
  78 ### See Also:
  79
  80 - [Fx][], [Fx.Tween][]
  81
  82
  83
  84 Chain Method: callChain {#Chain:callChain}
  85 ------------------------------------------
  86
  87 Removes the first function of the Chain instance stack and executes it. The next function will then become first in the array.
  88
  89 ### Syntax:
  90
  91         myClass.callChain([any arguments]);
  92
  93 ### Arguments:
  94
  95 1. Any arguments passed in will be passed to the "next" function.
  96
  97 ### Returns:
  98
  99 * (*mixed*) The return value of the "next" function or false when the chain was empty.
 100
 101 ### Example:
 102
 103         var myChain = new Chain();
 104         myChain.chain(
 105                 function(){ alert('do dishes'); },
 106                 function(){ alert('put away clean dishes'); }
 107         );
 108         myChain.callChain(); // alerts 'do dishes'.
 109         myChain.callChain(); // alerts 'put away clean dishes'.
 110
 111
 112
 113 Chain Method: clearChain {#Chain:clearChain}
 114 --------------------------------------------
 115
 116 Clears the stack of a Chain instance.
 117
 118 ### Syntax:
 119
 120         myClass.clearChain();
 121
 122 ### Returns:
 123
 124 * (*object*) The current Class instance.
 125
 126 ### Example:
 127
 128         var myFx = Fx.Tween('myElement', 'color'); // Fx.Tween inherited Fx's implementation of Chain.
 129         myFx.chain(function(){ while(true) alert("D'oh!"); }); // chains an infinite loop of alerts.
 130         myFx.clearChain(); // cancels the infinite loop of alerts before allowing it to begin.
 131
 132 ### See Also:
 133
 134 - [Fx][], [Fx.Tween][]
 135
 136
 137
 138 Class: Events {#Events}
 139 =======================
 140
 141 A Utility Class. Its methods can be implemented with [Class:implement][] into any [Class][].
 142 In [Fx][], for example, this Class is used to allow any number of functions to be added to the Fx events, like 'complete', 'start', and 'cancel'.
 143 Events in a Class that implements [Events][] must be either added as an option or with addEvent, not directly through .options.onEventName.
 144
 145 ### Syntax:
 146
 147 #### For new classes:
 148
 149         var MyClass = new Class({ Implements: Events });
 150
 151 #### For existing classes:
 152
 153         MyClass.implement(Events);
 154
 155 ### Implementing:
 156
 157 - This class can be implemented into other classes to add its functionality to them.
 158 - Events has been designed to work well with the [Options][] class. When the option property begins with 'on' and is followed by a capital letter it will be added as an event (e.g. 'onComplete' will add as 'complete' event).
 159
 160 ### Example:
 161
 162         var Widget = new Class({
 163                 Implements: Events,
 164                 initialize: function(element){
 165                         // ...
 166                 },
 167                 complete: function(){
 168                         this.fireEvent('complete');
 169                 }
 170         });
 171
 172         var myWidget = new Widget();
 173         myWidget.addEvent('complete', myFunction);
 174
 175 ### Notes:
 176
 177 - Events starting with 'on' are still supported in all methods and are converted to their representation without 'on' (e.g. 'onComplete' becomes 'complete').
 178
 179
 180 ### See Also:
 181
 182 - [Class][], [Options][]
 183
 184
 185
 186 Events Method: addEvent {#Events:addEvent}
 187 ------------------------------------------
 188
 189 Adds an event to the Class instance's event stack.
 190
 191 ### Syntax:
 192
 193         myClass.addEvent(type, fn[, internal]);
 194
 195 ### Arguments:
 196
 197 1. type     - (*string*) The type of event (e.g. 'complete').
 198 2. fn       - (*function*) The function to execute.
 199 3. internal - (*boolean*, optional) Sets the function property: internal to true. Internal property is used to prevent removal.
 200
 201 ### Returns:
 202
 203 * (*object*) This Class instance.
 204
 205 ### Example:
 206
 207         var myFx = new Fx.Tween('element', 'opacity');
 208         myFx.addEvent('start', myStartFunction);
 209
 210
 211 Events Method: addEvents {#Events:addEvents}
 212 ------------------------------------------
 213
 214 The same as [addEvent][], but accepts an object to add multiple events at once.
 215
 216 ### Syntax:
 217
 218         myClass.addEvents(events);
 219
 220 ### Arguments:
 221
 222 1. events - (*object*) An object with key/value representing: key the event name (e.g. 'start'), and value the function that is called when the Event occurs.
 223
 224 ### Returns:
 225
 226 * (*object*) This Class instance.
 227
 228 ### Example:
 229
 230         var myFx = new Fx.Tween('element', 'opacity');
 231         myFx.addEvents({
 232                 start: myStartFunction,
 233                 complete: function() {
 234                         alert('Done.');
 235                 }
 236         });
 237
 238
 239
 240 Events Method: fireEvent {#Events:fireEvent}
 241 --------------------------------------------
 242
 243 Fires all events of the specified type in the Class instance.
 244
 245 ### Syntax:
 246
 247         myClass.fireEvent(type[, args[, delay]]);
 248
 249 ### Arguments:
 250
 251 1. type  - (*string*) The type of event (e.g. 'complete').
 252 2. args  - (*mixed*, optional) The argument(s) to pass to the function. To pass more than one argument, the arguments must be in an array.
 253 3. delay - (*number*, optional) Delay in milliseconds to wait before executing the event (defaults to 0).
 254
 255 ### Returns:
 256
 257 * (*object*) This Class instance.
 258
 259 ### Example:
 260
 261         var Widget = new Class({
 262                 Implements: Events,
 263                 initialize: function(arg1, arg2){
 264                         //...
 265                         this.fireEvent('initialize', [arg1, arg2], 50);
 266                 }
 267         });
 268
 269
 270
 271 Events Method: removeEvent {#Events:removeEvent}
 272 ------------------------------------------------
 273
 274 Removes an event from the stack of events of the Class instance.
 275
 276 ### Syntax:
 277
 278         myClass.removeEvent(type, fn);
 279
 280 ### Arguments:
 281
 282 1. type - (*string*) The type of event (e.g. 'complete').
 283 2. fn   - (*function*) The function to remove.
 284
 285 ### Returns:
 286
 287 * (*object*) This Class instance.
 288
 289 ### Notes:
 290
 291 - If the function has the property internal and is set to true, then the event will not be removed.
 292
 293
 294 Events Method: removeEvents {#Events:removeEvents}
 295 --------------------------------------------------
 296
 297 Removes all events of the given type from the stack of events of a Class instance. If no type is specified, removes all events of all types.
 298
 299 ### Syntax:
 300
 301         myClass.removeEvents([events]);
 302
 303 ### Arguments:
 304
 305 1. events - (optional) If not passed removes all events of all types.
 306         - (*string*) The event name (e.g. 'success'). Removes all events of that type.
 307         - (*object*) An object of type function pairs. Like the one passed to [addEvents][].
 308
 309 ### Returns:
 310
 311 * (*object*) The current Class instance.
 312
 313 ### Example:
 314
 315         var myFx = new Fx.Tween('myElement', 'opacity');
 316         myFx.removeEvents('complete');
 317
 318
 319 ### Notes:
 320
 321 - removeEvents will not remove internal events. See [Events:removeEvent][].
 322
 323
 324
 325 Class: Options {#Options}
 326 =========================
 327
 328 A Utility Class. Its methods can be implemented with [Class:implement][] into any [Class][].
 329 Used to automate the setting of a Class instance's options.
 330 Will also add Class [Events][] when the option property begins with 'on' and is followed by a capital letter (e.g. 'onComplete' adds a 'complete' event). You will need to call this.setOptions() for this to have an effect, however.
 331
 332 ### Syntax:
 333
 334 #### For new classes:
 335
 336         var MyClass = new Class({Implements: Options});
 337
 338 #### For existing classes:
 339
 340         MyClass.implement(Options);
 341
 342
 343
 344 Options Method: setOptions {#Options:setOptions}
 345 ------------------------------------------------
 346
 347 Merges the default options of the Class with the options passed in. Every value passed in to this method will be deep copied. Therefore other class instances or objects that are not intended for copying must be passed to a class in other ways.
 348
 349 ### Syntax:
 350
 351         myClass.setOptions([options]);
 352
 353 ### Arguments:
 354
 355 1. options - (*object*, optional) The user defined options to merge with the defaults.
 356
 357 ### Returns:
 358
 359 * (*object*) The current Class instance.
 360
 361 ### Example:
 362
 363         var Widget = new Class({
 364                 Implements: Options,
 365                 options: {
 366                         color: '#fff',
 367                         size: {
 368                                 width: 100,
 369                                 height: 100
 370                         }
 371                 },
 372                 initialize: function(options){
 373                         this.setOptions(options);
 374                 }
 375         });
 376
 377         var myWidget = new Widget({
 378                 color: '#f00',
 379                 size: {
 380                         width: 200
 381                 }
 382         });
 383
 384         //myWidget.options is now: {color: #f00, size: {width: 200, height: 100}}
 385
 386         // Deep copy example
 387         var mySize = {
 388                 width: 50,
 389                 height: 50
 390         };
 391
 392         var myWidget = new Widget({
 393                 size: mySize
 394         });
 395
 396         (mySize == myWidget.options.size) // false! mySize was copied in the setOptions call.
 397
 398 ### Notes:
 399
 400 - Relies on the default options of a Class defined in its options property.
 401
 402
 403 Options in combination with Events
 404 -----------------------------------
 405
 406 If a Class has [Events][] as well as [Options][] implemented, every option beginning with 'on' and followed by a capital letter (e.g. 'onComplete') becomes a Class instance event, assuming the value of the option is a function.
 407
 408 ### Example:
 409
 410         var Widget = new Class({
 411                 Implements: [Options, Events],
 412                 options: {
 413                         color: '#fff',
 414                         size: {
 415                                 width: 100,
 416                                 height: 100
 417                         }
 418                 },
 419                 initialize: function(options){
 420                         this.setOptions(options);
 421                 },
 422                 show: function(){
 423                         // Do some cool stuff
 424
 425                         this.fireEvent('show');
 426                 }
 427
 428         });
 429
 430         var myWidget = new Widget({
 431                 color: '#f00',
 432                 size: {
 433                         width: 200
 434                 },
 435                 onShow: function(){
 436                         alert('Lets show it!');
 437                 }
 438         });
 439
 440         myWidget.show(); // fires the event and alerts 'Lets show it!'
 441
 442
 443 [Class]: /core/Class/Class
 444 [Class:implement]: /core/Class/Class/#Class:implement
 445 [Fx]: /core/Fx/Fx
 446 [Fx.Tween]: /core/Fx/Fx.Tween
 447 [Request]: /core/Request/Request
 448 [Request.HTML]: /core/Request/Request.HTML
 449 [Events:removeEvent]: /core/Element/Element.Event/#Element:removeEvent
 450 [Events]: #Events
 451 [Options]: #Options
 452 [addEvent]: #Events:addEvent
 453 [addEvents]: #Events:addEvents