Class/Class.Extras.js

   1 /*
   2 Script: Class.Extras.js
   3         Contains common implementations for custom classes. In Mootools is implemented in <Ajax>, <XHR> and <Fx.Base> and many more.
   4
   5 License:
   6         MIT-style license.
   7 */
   8
   9 /*
  10 Class: Chain
  11         An "Utility" Class. Its methods can be implemented with <Class.implement> into any <Class>.
  12         Currently implemented in <Fx.Base>, <XHR> and <Ajax>. In <Fx.Base> for example, is used to execute a list of function, one after another, once the effect is completed.
  13         The functions will not be fired all togheter, but one every completion, to create custom complex animations.
  14
  15 Example:
  16         (start code)
  17         var myFx = new Fx.Style('element', 'opacity');
  18
  19         myFx.start(1,0).chain(function(){
  20                 myFx.start(0,1);
  21         }).chain(function(){
  22                 myFx.start(1,0);
  23         }).chain(function(){
  24                 myFx.start(0,1);
  25         });
  26         //the element will appear and disappear three times
  27         (end)
  28 */
  29
  30 var Chain = new Class({
  31
  32         /*
  33         Property: chain
  34                 adds a function to the Chain instance stack.
  35
  36         Arguments:
  37                 fn - the function to append.
  38         */
  39
  40         chain: function(fn){
  41                 this.chains = this.chains || [];
  42                 this.chains.push(fn);
  43                 return this;
  44         },
  45
  46         /*
  47         Property: callChain
  48                 Executes the first function of the Chain instance stack, then removes it. The first function will then become the second.
  49         */
  50
  51         callChain: function(){
  52                 if (this.chains && this.chains.length) this.chains.shift().delay(10, this);
  53         },
  54
  55         /*
  56         Property: clearChain
  57                 Clears the stack of a Chain instance.
  58         */
  59
  60         clearChain: function(){
  61                 this.chains = [];
  62         }
  63
  64 });
  65
  66 /*
  67 Class: Events
  68         An "Utility" Class. Its methods can be implemented with <Class.implement> into any <Class>.
  69
  70         In <Fx.Base> Class, for example, is used to give the possibility add any number of functions to the Effects events, like onComplete, onStart, onCancel.
  71
  72 Example:
  73         (start code)
  74         var myFx = new Fx.Style('element', 'opacity').addEvent('onComplete', function(){
  75                 alert('the effect is completed');
  76         }).addEvent('onComplete', function(){
  77                 alert('I told you the effect is completed');
  78         });
  79
  80         myFx.start(0,1);
  81         //upon completion it will display the 2 alerts, in order.
  82         (end)
  83
  84 Implementing:
  85         This class can be implemented into other classes to add the functionality to them.
  86         Goes well with the <Options> class.
  87
  88 Example:
  89         (start code)
  90         var Widget = new Class({
  91                 initialize: function(){},
  92                 finish: function(){
  93                         this.fireEvent('onComplete');
  94                 }
  95         });
  96         Widget.implement(new Events);
  97         //later...
  98         var myWidget = new Widget();
  99         myWidget.addEvent('onComplete', myfunction);
 100         (end)
 101 */
 102
 103 var Events = new Class({
 104
 105         /*
 106         Property: addEvent
 107                 adds an event to the stack of events of the Class instance.
 108
 109         Arguments:
 110                 type - string; the event name (e.g. 'onComplete')
 111                 fn - function to execute
 112         */
 113
 114         addEvent: function(type, fn){
 115                 if (fn != Class.empty){
 116                         this.$events = this.$events || {};
 117                         this.$events[type] = this.$events[type] || [];
 118                         this.$events[type].include(fn);
 119                 }
 120                 return this;
 121         },
 122
 123         /*
 124         Property: fireEvent
 125                 fires all events of the specified type in the Class instance.
 126
 127         Arguments:
 128                 type - string; the event name (e.g. 'onComplete')
 129                 args - array or single object; arguments to pass to the function; if more than one argument, must be an array
 130                 delay - (integer) delay (in ms) to wait to execute the event
 131
 132         Example:
 133         (start code)
 134         var Widget = new Class({
 135                 initialize: function(arg1, arg2){
 136                         ...
 137                         this.fireEvent("onInitialize", [arg1, arg2], 50);
 138                 }
 139         });
 140         Widget.implement(new Events);
 141         (end)
 142         */
 143
 144         fireEvent: function(type, args, delay){
 145                 if (this.$events && this.$events[type]){
 146                         this.$events[type].each(function(fn){
 147                                 fn.create({'bind': this, 'delay': delay, 'arguments': args})();
 148                         }, this);
 149                 }
 150                 return this;
 151         },
 152
 153         /*
 154         Property: removeEvent
 155                 removes an event from the stack of events of the Class instance.
 156
 157         Arguments:
 158                 type - string; the event name (e.g. 'onComplete')
 159                 fn - function that was added
 160         */
 161
 162         removeEvent: function(type, fn){
 163                 if (this.$events && this.$events[type]) this.$events[type].remove(fn);
 164                 return this;
 165         }
 166
 167 });
 168
 169 /*
 170 Class: Options
 171         An "Utility" Class. Its methods can be implemented with <Class.implement> into any <Class>.
 172         Used to automate the options settings, also adding Class <Events> when the option begins with on.
 173
 174         Example:
 175                 (start code)
 176                 var Widget = new Class({
 177                         options: {
 178                                 color: '#fff',
 179                                 size: {
 180                                         width: 100
 181                                         height: 100
 182                                 }
 183                         },
 184                         initialize: function(options){
 185                                 this.setOptions(options);
 186                         }
 187                 });
 188                 Widget.implement(new Options);
 189                 //later...
 190                 var myWidget = new Widget({
 191                         color: '#f00',
 192                         size: {
 193                                 width: 200
 194                         }
 195                 });
 196                 //myWidget.options = {color: #f00, size: {width: 200, height: 100}}
 197                 (end)
 198 */
 199
 200 var Options = new Class({
 201
 202         /*
 203         Property: setOptions
 204                 sets this.options
 205
 206         Arguments:
 207                 defaults - object; the default set of options
 208                 options - object; the user entered options. can be empty too.
 209
 210         Note:
 211                 if your Class has <Events> implemented, every option beginning with on, followed by a capital letter (onComplete) becomes an Class instance event.
 212         */
 213
 214         setOptions: function(){
 215                 this.options = $merge.apply(null, [this.options].extend(arguments));
 216                 if (!this.addEvent) return this;
 217                 for (var option in this.options){
 218                         if ($type(this.options[option] == 'function') && option.test(/^on[A-Z]/)) this.addEvent(option, this.options[option]);
 219                 }
 220                 return this;
 221         }
 222
 223 });