Docs/Types/Function.md

   1 Type: Function {#Function}
   2 ==========================
   3
   4 Function Methods.
   5
   6 ### See Also:
   7
   8 - [MDN Function][]
   9
  10
  11
  12 Function: Function.convert {#Function:Function:convert}
  13 -------------------------------------------------
  14
  15 If the passed argument is a function, it will return itself. Otherwise, it will return a function that returns the passed argument.
  16
  17 ### Syntax:
  18
  19         var foo = Function.convert(obj);
  20
  21 ### Arguments:
  22
  23 1. obj - (*mixed*) If this argument is a function, it will simply return itself. Otherwise, an object you wish to convert into a function that returns the argument.
  24
  25 ### Returns:
  26
  27 * (*function*) Either the passed function or an anonymous function that returns the passed argument.
  28
  29 ### Examples:
  30
  31         var fn = Function.convert(42);
  32         alert(fn());    // alerts '42'
  33
  34         var fn2 = Function.convert(fn);
  35         alert(fn2());   // alerts '42'
  36
  37 ### Notes:
  38
  39 This function is equivalent to the following deprecated MooTools 1.2 methods:
  40
  41         var fn1 = Function.convert();           // equivalent to var fn1 = function(){};
  42         var fn2 = Function.convert(foo);        // equivalent to var fn2 = function(){ return foo; };
  43
  44
  45 Function: Function.attempt {#Function:Function-attempt}
  46 -------------------------------------------------------
  47
  48 Tries to execute a number of functions. Returns immediately the return value of the first non-failed function without executing successive functions, or null.
  49
  50 ### Syntax:
  51
  52         Function.attempt(fn[, fn, fn, fn, ...]);
  53
  54 ### Arguments:
  55
  56 * fn   - (*function*) Any number of functions to execute.
  57
  58 ### Returns:
  59
  60 * (*mixed*) Standard return of the called function.
  61 * (*null*) `null` if all the passed functions fail.
  62
  63 ### Examples:
  64
  65         var result = Function.attempt(function(){
  66                 return some.made.up.object;
  67         }, function(){
  68                 return jibberish.that.doesnt.exists;
  69         }, function(){
  70                 return false;
  71         });
  72
  73         //result is false
  74
  75         var failure, success;
  76
  77         Function.attempt(function(){
  78                 some.made.up.object = 'something';
  79                 success = true;
  80         }, function(){
  81                 failure = true;
  82         });
  83
  84         if (success) alert('yey!');
  85
  86 ### Notes:
  87
  88 This method is an equivalent of *$try* from MooTools 1.2.
  89
  90
  91
  92 Function method: extend {#Function:extend}
  93 ------------------------------------------
  94
  95 Extends a function with a new method or property.
  96
  97 ### Syntax:
  98
  99         myFunction.extend(key, value);
 100
 101         // Or
 102
 103         myFunction.extend(object);
 104
 105 ### Arguments:
 106
 107 1. key - (*string*) The key of the method or property
 108 2. value - (*mixed*) The function or property value
 109
 110 Or
 111
 112 1. object - (*object*) An object with the key value pairs to add multiple methods or properties
 113
 114 ### Returns:
 115
 116 * (*function*) The function
 117
 118 ### Example:
 119
 120         var myFunction = function(){};
 121         myFunction.extend('alert', function(text){
 122                 alert(text);
 123         });
 124         myFunction.alert('Hello!'); // alerts Hello!
 125
 126         // Using objects
 127         myFunction.extend({
 128                 alert: function(text){
 129                         alert(text);
 130                 }
 131         });
 132
 133 Function method: implement {#Function:implement}
 134 ------------------------------------------------
 135
 136 Implements a method to the prototype of the function.
 137
 138 ### Syntax:
 139
 140         myFunction.implement(key, value);
 141
 142         // Or
 143
 144         myFunction.implement(object);
 145
 146 ### Arguments:
 147
 148 1. key - (*string*) The method of property name in the prototype
 149 2. value - (*mixed*) The function or another value in the prototype
 150
 151 Or
 152
 153 1. object - (*object*) An object with key-value pairs to add multiple methods or properties to the function it's prototype.
 154
 155 ### Returns:
 156
 157 * (*function*) The function
 158
 159 ### Example:
 160
 161         var myFunction = function(){};
 162         myFunction.implement('alert', function(text){
 163                 alert(text);
 164         });
 165         var myInstance = new myFunction();
 166         myInstance.alert('Hello!'); // alerts Hello!
 167
 168         // Using objects
 169         myInstance.implement({
 170                 alert: function(text){
 171                         alert(text);
 172                 }
 173         });
 174
 175 ### Notes:
 176
 177 The difference between *implement* and *extend*, is that implement adds the value to the prototype.
 178 So with *implement* each instance of the function will have this method or property while with *extend*
 179 the method or property is added to a single instance.
 180
 181
 182 Function method: attempt {#Function:attempt}
 183 --------------------------------------------
 184
 185 Tries to execute a single function. Returns immediately the return value of the function if it does not fail, or null.
 186
 187 ### Syntax:
 188
 189         var myFunctionResult = myFunction.attempt(args[, bind]);
 190
 191 ### Arguments:
 192
 193 1. args - (*mixed*) An argument, or array of arguments to run the function with.
 194 2. bind - (*object*, optional) The object that the "this" of the function will refer to.
 195
 196 ### Returns:
 197
 198 * (*mixed*) This Function's return value.
 199 * (*null*) `null` if the function fails.
 200
 201 ### Examples:
 202
 203         var myFunction = function(){
 204                 return some.made.up.object;
 205         };
 206         myFunction.attempt(); // returns 'null'
 207
 208
 209         var myFunction = function(val){
 210                 return val;
 211         };
 212         myFunction.attempt(false); // returns 'false'
 213
 214 ### See Also:
 215
 216 - See [Function.attempt](#Function:Function-attempt) for using more than one functions.
 217
 218
 219 Function method: pass {#Function:pass}
 220 --------------------------------------
 221
 222 Returns a closure with arguments and bind.
 223
 224 ### Syntax:
 225
 226         var newFunction = myFunction.pass([args[, bind]]);
 227
 228 ### Arguments:
 229
 230 1. args - (*mixed*, optional) The arguments to pass to the function (must be an array if passing more than one argument).
 231 2. bind - (*object*, optional) The object that the "this" of the function will refer to.
 232
 233 ### Returns:
 234
 235 * (*function*) The function whose arguments are passed when called.
 236
 237 ### Example:
 238
 239         var myFunction = function(){
 240                 var result = 'Passed: ';
 241                 for (var i = 0, l = arguments.length; i < l; i++){
 242                         result += (arguments[i] + ' ');
 243                 }
 244                 return result;
 245         }
 246         var myHello = myFunction.pass('hello');
 247         var myItems = myFunction.pass(['peach', 'apple', 'orange']);
 248
 249         // Later in the code, the functions can be executed:
 250         alert(myHello()); // passes 'hello' to myFunction.
 251         alert(myItems()); // passes the array of items to myFunction.
 252
 253
 254 ### See Also:
 255
 256 [Function:bind][]
 257
 258
 259 Function method: bind {#Function:bind}
 260 --------------------------------------
 261
 262 Changes the scope of `this` within the target function to refer to the bind parameter.
 263
 264 ### Syntax:
 265
 266         myFunction.bind([bind[, arg1, arg2, ...]]);
 267
 268 ### Arguments:
 269
 270 1. bind - (*object*, optional) The object that the "this" of the function will refer to.
 271 2. arg1, arg2, ... - (*mixed*, optional) The arguments to pass to the function. If the bound function is called with other arguments the arguments are concatenated.
 272
 273 ### Returns:
 274
 275 * (*function*) The bound function.
 276
 277 ### Example:
 278
 279         function myFunction(){
 280                 // Note that 'this' here refers to window, not an element.
 281                 // the function must be bound to the element we want to manipulate.
 282                 this.setStyle('color', 'red');
 283         };
 284         var myBoundFunction = myFunction.bind(myElement);
 285         myBoundFunction(); // makes myElement's text red
 286
 287         // To show how bind works the following example:
 288         var myBoundFunction = myFunction.bind(anyVar);
 289         // is roughly equivalent with
 290         var myBoundFunction = function(){
 291                 return myFunction.call(this);
 292         };
 293
 294 ### See Also:
 295
 296 [Function:pass][]
 297
 298 Function method: delay {#Function:delay}
 299 ----------------------------------------
 300
 301 Delays the execution of a function by a specified duration.
 302
 303 ### Syntax:
 304
 305         var timeoutID = myFunction.delay(delay[, bind[, args]]);
 306
 307 ### Arguments:
 308
 309 1. delay - (*number*) The duration to wait (in milliseconds).
 310 2. bind  - (*object*, optional) The object that the "this" of the function will refer to.
 311 3. args  - (*mixed*, optional) The arguments passed (must be an array if the arguments are greater than one).
 312
 313 ### Returns:
 314
 315 * (*number*) The JavaScript timeout id (for clearing delays).
 316
 317 ### Example:
 318
 319         var myFunction = function(){ alert('moo! Element id is: ' + this.id); };
 320
 321         //wait 50 milliseconds, then call myFunction and bind myElement to it
 322         myFunction.delay(50, myElement); // alerts: 'moo! Element id is: ... '
 323
 324         //an anonymous function which waits a second and then alerts
 325         (function(){ alert('one second later...'); }).delay(1000);
 326
 327         //to stop the delay, clearTimeout can be used like so:
 328         var timer = myFunction.delay(50);
 329         clearTimeout(timer);
 330
 331
 332 ### See Also:
 333
 334 - [MDN setTimeout][], [MDN clearTimeout][]
 335
 336
 337
 338 Function method: periodical {#Function:periodical}
 339 --------------------------------------------------
 340
 341 Executes a function in the specified intervals of time. Periodic execution can be stopped using the *clearInterval* function.
 342
 343 ### Syntax:
 344
 345         var intervalID = myFunction.periodical(period[, bind[, args]]);
 346
 347 ### Arguments:
 348
 349 1. period - (*number*) The duration of the intervals between executions.
 350 2. bind   - (*object*, optional) The object that the "this" of the function will refer to.
 351 3. args   - (*mixed*, optional) The arguments passed (must be an array if the arguments are greater than one).
 352
 353 ### Returns:
 354
 355 * (*number*) The Interval id (for clearing a periodical).
 356
 357 ### Example:
 358
 359         var Site = { counter: 0 };
 360         var addCount = function(){ this.counter++; };
 361         addCount.periodical(1000, Site); //adds the number of seconds at the Site.
 362
 363         // the interval can be stopped using the clearInterval function
 364         var timer = myFunction.periodical(1000);
 365         clearInterval(timer);
 366
 367 ### See Also:
 368
 369 - [MDN setInterval][], [MDN clearInterval][]
 370
 371
 372 Deprecated Functions {#Deprecated-Functions}
 373 ============================================
 374
 375 Function method: create {#Deprecated-Functions:create}
 376 ------------------------------------------------------
 377
 378 This function has been deprecated.
 379
 380 Function method: bindWithEvent {#Deprecated-Functions:bindWithEvent}
 381 --------------------------------------------------------------------
 382
 383 This function has been deprecated.
 384
 385 ### Example how you could replace this method:
 386
 387         myElement.addEvent('click', function(e){
 388                 myFunction.call(bind, e);
 389         });
 390
 391 Function method: run {#Deprecated-Functions:run}
 392 ------------------------------------------------
 393
 394 This function has been deprecated.
 395
 396 ### Replacement example
 397
 398         fn.apply(thisArg, arguments); // Old API: fn.run(arguments, thisArg);
 399
 400
 401 [Function:bind]: /core/Types/Function/#Function:bind
 402 [Function:pass]: /core/Types/Function/#Function:pass
 403 [Element:addEvent]: /core/Element/Element.Event/#Element:addEvent
 404 [MDN Function]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function
 405 [MDN setInterval]: https://developer.mozilla.org/en/DOM/window.setInterval
 406 [MDN setTimeout]: https://developer.mozilla.org/en/DOM/window.setTimeout
 407 [MDN clearInterval]: https://developer.mozilla.org/en/DOM/window.clearInterval
 408 [MDN clearTimeout]: https://developer.mozilla.org/en/DOM/window.clearTimeout
 409