Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / Base3.html
1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-Base'>/**
2 </span> * @author Jacky Nguyen &lt;jacky@sencha.com&gt;
3  * @docauthor Jacky Nguyen &lt;jacky@sencha.com&gt;
4  * @class Ext.Base
5  *
6  * The root of all classes created with {@link Ext#define}
7  * All prototype and static members of this class are inherited by any other class
8  *
9  */
10 (function(flexSetter) {
11
12 var Base = Ext.Base = function() {};
13     Base.prototype = {
14         $className: 'Ext.Base',
15
16         $class: Base,
17
18 <span id='Ext-Base-property-self'>        /**
19 </span>         * Get the reference to the current class from which this object was instantiated. Unlike {@link Ext.Base#statics},
20          * `this.self` is scope-dependent and it's meant to be used for dynamic inheritance. See {@link Ext.Base#statics}
21          * for a detailed comparison
22
23     Ext.define('My.Cat', {
24         statics: {
25             speciesName: 'Cat' // My.Cat.speciesName = 'Cat'
26         },
27
28         constructor: function() {
29             alert(this.self.speciesName); / dependent on 'this'
30
31             return this;
32         },
33
34         clone: function() {
35             return new this.self();
36         }
37     });
38
39
40     Ext.define('My.SnowLeopard', {
41         extend: 'My.Cat',
42         statics: {
43             speciesName: 'Snow Leopard'         // My.SnowLeopard.speciesName = 'Snow Leopard'
44         }
45     });
46
47     var cat = new My.Cat();                     // alerts 'Cat'
48     var snowLeopard = new My.SnowLeopard();     // alerts 'Snow Leopard'
49
50     var clone = snowLeopard.clone();
51     alert(Ext.getClassName(clone));             // alerts 'My.SnowLeopard'
52
53          * @type Class
54          * @protected
55          * @markdown
56          */
57         self: Base,
58
59 <span id='Ext-Base-method-constructor'>        /**
60 </span>         * Default constructor, simply returns `this`
61          *
62          * @constructor
63          * @protected
64          * @return {Object} this
65          */
66         constructor: function() {
67             return this;
68         },
69
70 <span id='Ext-Base-method-initConfig'>        /**
71 </span>         * Initialize configuration for this class. a typical example:
72
73     Ext.define('My.awesome.Class', {
74         // The default config
75         config: {
76             name: 'Awesome',
77             isAwesome: true
78         },
79
80         constructor: function(config) {
81             this.initConfig(config);
82
83             return this;
84         }
85     });
86
87     var awesome = new My.awesome.Class({
88         name: 'Super Awesome'
89     });
90
91     alert(awesome.getName()); // 'Super Awesome'
92
93          * @protected
94          * @param {Object} config
95          * @return {Object} mixins The mixin prototypes as key - value pairs
96          * @markdown
97          */
98         initConfig: function(config) {
99             if (!this.$configInited) {
100                 this.config = Ext.Object.merge({}, this.config || {}, config || {});
101
102                 this.applyConfig(this.config);
103
104                 this.$configInited = true;
105             }
106
107             return this;
108         },
109
110 <span id='Ext-Base-method-setConfig'>        /**
111 </span>         * @private
112          */
113         setConfig: function(config) {
114             this.applyConfig(config || {});
115
116             return this;
117         },
118
119 <span id='Ext-Base-property-applyConfig'>        /**
120 </span>         * @private
121          */
122         applyConfig: flexSetter(function(name, value) {
123             var setter = 'set' + Ext.String.capitalize(name);
124
125             if (typeof this[setter] === 'function') {
126                 this[setter].call(this, value);
127             }
128
129             return this;
130         }),
131
132 <span id='Ext-Base-method-callParent'>        /**
133 </span>         * Call the parent's overridden method. For example:
134
135     Ext.define('My.own.A', {
136         constructor: function(test) {
137             alert(test);
138         }
139     });
140
141     Ext.define('My.own.B', {
142         extend: 'My.own.A',
143
144         constructor: function(test) {
145             alert(test);
146
147             this.callParent([test + 1]);
148         }
149     });
150
151     Ext.define('My.own.C', {
152         extend: 'My.own.B',
153
154         constructor: function() {
155             alert(&quot;Going to call parent's overriden constructor...&quot;);
156
157             this.callParent(arguments);
158         }
159     });
160
161     var a = new My.own.A(1); // alerts '1'
162     var b = new My.own.B(1); // alerts '1', then alerts '2'
163     var c = new My.own.C(2); // alerts &quot;Going to call parent's overriden constructor...&quot;
164                              // alerts '2', then alerts '3'
165
166          * @protected
167          * @param {Array/Arguments} args The arguments, either an array or the `arguments` object
168          * from the current method, for example: `this.callParent(arguments)`
169          * @return {Mixed} Returns the result from the superclass' method
170          * @markdown
171          */
172         callParent: function(args) {
173             var method = this.callParent.caller,
174                 parentClass, methodName;
175
176             if (!method.$owner) {
177                 //&lt;debug error&gt;
178                 if (!method.caller) {
179                     Ext.Error.raise({
180                         sourceClass: Ext.getClassName(this),
181                         sourceMethod: &quot;callParent&quot;,
182                         msg: &quot;Attempting to call a protected method from the public scope, which is not allowed&quot;
183                     });
184                 }
185                 //&lt;/debug&gt;
186
187                 method = method.caller;
188             }
189
190             parentClass = method.$owner.superclass;
191             methodName = method.$name;
192
193             //&lt;debug error&gt;
194             if (!(methodName in parentClass)) {
195                 Ext.Error.raise({
196                     sourceClass: Ext.getClassName(this),
197                     sourceMethod: methodName,
198                     msg: &quot;this.callParent() was called but there's no such method (&quot; + methodName +
199                          &quot;) found in the parent class (&quot; + (Ext.getClassName(parentClass) || 'Object') + &quot;)&quot;
200                  });
201             }
202             //&lt;/debug&gt;
203
204             return parentClass[methodName].apply(this, args || []);
205         },
206
207
208 <span id='Ext-Base-method-statics'>        /**
209 </span>         * Get the reference to the class from which this object was instantiated. Note that unlike {@link Ext.Base#self},
210          * `this.statics()` is scope-independent and it always returns the class from which it was called, regardless of what
211          * `this` points to during run-time
212
213     Ext.define('My.Cat', {
214         statics: {
215             totalCreated: 0,
216             speciesName: 'Cat' // My.Cat.speciesName = 'Cat'
217         },
218
219         constructor: function() {
220             var statics = this.statics();
221
222             alert(statics.speciesName);     // always equals to 'Cat' no matter what 'this' refers to
223                                             // equivalent to: My.Cat.speciesName
224
225             alert(this.self.speciesName);   // dependent on 'this'
226
227             statics.totalCreated++;
228
229             return this;
230         },
231
232         clone: function() {
233             var cloned = new this.self;                      // dependent on 'this'
234
235             cloned.groupName = this.statics().speciesName;   // equivalent to: My.Cat.speciesName
236
237             return cloned;
238         }
239     });
240
241
242     Ext.define('My.SnowLeopard', {
243         extend: 'My.Cat',
244
245         statics: {
246             speciesName: 'Snow Leopard'     // My.SnowLeopard.speciesName = 'Snow Leopard'
247         },
248
249         constructor: function() {
250             this.callParent();
251         }
252     });
253
254     var cat = new My.Cat();                 // alerts 'Cat', then alerts 'Cat'
255
256     var snowLeopard = new My.SnowLeopard(); // alerts 'Cat', then alerts 'Snow Leopard'
257
258     var clone = snowLeopard.clone();
259     alert(Ext.getClassName(clone));         // alerts 'My.SnowLeopard'
260     alert(clone.groupName);                 // alerts 'Cat'
261
262     alert(My.Cat.totalCreated);             // alerts 3
263
264          * @protected
265          * @return {Class}
266          * @markdown
267          */
268         statics: function() {
269             var method = this.statics.caller,
270                 self = this.self;
271
272             if (!method) {
273                 return self;
274             }
275
276             return method.$owner;
277         },
278
279 <span id='Ext-Base-method-callOverridden'>        /**
280 </span>         * Call the original method that was previously overridden with {@link Ext.Base#override}
281
282     Ext.define('My.Cat', {
283         constructor: function() {
284             alert(&quot;I'm a cat!&quot;);
285
286             return this;
287         }
288     });
289
290     My.Cat.override({
291         constructor: function() {
292             alert(&quot;I'm going to be a cat!&quot;);
293
294             var instance = this.callOverridden();
295
296             alert(&quot;Meeeeoooowwww&quot;);
297
298             return instance;
299         }
300     });
301
302     var kitty = new My.Cat(); // alerts &quot;I'm going to be a cat!&quot;
303                               // alerts &quot;I'm a cat!&quot;
304                               // alerts &quot;Meeeeoooowwww&quot;
305
306          * @param {Array/Arguments} args The arguments, either an array or the `arguments` object
307          * @return {Mixed} Returns the result after calling the overridden method
308          * @markdown
309          */
310         callOverridden: function(args) {
311             var method = this.callOverridden.caller;
312
313             //&lt;debug error&gt;
314             if (!method.$owner) {
315                 Ext.Error.raise({
316                     sourceClass: Ext.getClassName(this),
317                     sourceMethod: &quot;callOverridden&quot;,
318                     msg: &quot;Attempting to call a protected method from the public scope, which is not allowed&quot;
319                 });
320             }
321
322             if (!method.$previous) {
323                 Ext.Error.raise({
324                     sourceClass: Ext.getClassName(this),
325                     sourceMethod: &quot;callOverridden&quot;,
326                     msg: &quot;this.callOverridden was called in '&quot; + method.$name +
327                          &quot;' but this method has never been overridden&quot;
328                  });
329             }
330             //&lt;/debug&gt;
331
332             return method.$previous.apply(this, args || []);
333         },
334
335         destroy: function() {}
336     };
337
338     // These static properties will be copied to every newly created class with {@link Ext#define}
339     Ext.apply(Ext.Base, {
340 <span id='Ext-Base-property-create'>        /**
341 </span>         * Create a new instance of this Class.
342 Ext.define('My.cool.Class', {
343     ...
344 });
345
346 My.cool.Class.create({
347     someConfig: true
348 });
349          * @property create
350          * @static
351          * @type Function
352          * @markdown
353          */
354         create: function() {
355             return Ext.create.apply(Ext, [this].concat(Array.prototype.slice.call(arguments, 0)));
356         },
357
358 <span id='Ext-Base-property-own'>        /**
359 </span>         * @private
360          */
361         own: flexSetter(function(name, value) {
362             if (typeof value === 'function') {
363                 this.ownMethod(name, value);
364             }
365             else {
366                 this.prototype[name] = value;
367             }
368         }),
369
370 <span id='Ext-Base-method-ownMethod'>        /**
371 </span>         * @private
372          */
373         ownMethod: function(name, fn) {
374             var originalFn;
375
376             if (fn.$owner !== undefined &amp;&amp; fn !== Ext.emptyFn) {
377                 originalFn = fn;
378
379                 fn = function() {
380                     return originalFn.apply(this, arguments);
381                 };
382             }
383
384             //&lt;debug&gt;
385             var className;
386             className = Ext.getClassName(this);
387             if (className) {
388                 fn.displayName = className + '#' + name;
389             }
390             //&lt;/debug&gt;
391             fn.$owner = this;
392             fn.$name = name;
393
394             this.prototype[name] = fn;
395         },
396
397 <span id='Ext-Base-property-addStatics'>        /**
398 </span>         * Add / override static properties of this class.
399
400     Ext.define('My.cool.Class', {
401         ...
402     });
403
404     My.cool.Class.addStatics({
405         someProperty: 'someValue',      // My.cool.Class.someProperty = 'someValue'
406         method1: function() { ... },    // My.cool.Class.method1 = function() { ... };
407         method2: function() { ... }     // My.cool.Class.method2 = function() { ... };
408     });
409
410          * @property addStatics
411          * @static
412          * @type Function
413          * @param {Object} members
414          * @markdown
415          */
416         addStatics: function(members) {
417             for (var name in members) {
418                 if (members.hasOwnProperty(name)) {
419                     this[name] = members[name];
420                 }
421             }
422
423             return this;
424         },
425
426 <span id='Ext-Base-property-implement'>        /**
427 </span>         * Add methods / properties to the prototype of this class.
428
429     Ext.define('My.awesome.Cat', {
430         constructor: function() {
431             ...
432         }
433     });
434
435      My.awesome.Cat.implement({
436          meow: function() {
437             alert('Meowww...');
438          }
439      });
440
441      var kitty = new My.awesome.Cat;
442      kitty.meow();
443
444          * @property implement
445          * @static
446          * @type Function
447          * @param {Object} members
448          * @markdown
449          */
450         implement: function(members) {
451             var prototype = this.prototype,
452                 name, i, member, previous;
453             //&lt;debug&gt;
454             var className = Ext.getClassName(this);
455             //&lt;/debug&gt;
456             for (name in members) {
457                 if (members.hasOwnProperty(name)) {
458                     member = members[name];
459
460                     if (typeof member === 'function') {
461                         member.$owner = this;
462                         member.$name = name;
463                         //&lt;debug&gt;
464                         if (className) {
465                             member.displayName = className + '#' + name;
466                         }
467                         //&lt;/debug&gt;
468                     }
469
470                     prototype[name] = member;
471                 }
472             }
473
474             if (Ext.enumerables) {
475                 var enumerables = Ext.enumerables;
476
477                 for (i = enumerables.length; i--;) {
478                     name = enumerables[i];
479
480                     if (members.hasOwnProperty(name)) {
481                         member = members[name];
482                         member.$owner = this;
483                         member.$name = name;
484                         prototype[name] = member;
485                     }
486                 }
487             }
488         },
489
490 <span id='Ext-Base-property-borrow'>        /**
491 </span>         * Borrow another class' members to the prototype of this class.
492
493 Ext.define('Bank', {
494     money: '$$$',
495     printMoney: function() {
496         alert('$$$$$$$');
497     }
498 });
499
500 Ext.define('Thief', {
501     ...
502 });
503
504 Thief.borrow(Bank, ['money', 'printMoney']);
505
506 var steve = new Thief();
507
508 alert(steve.money); // alerts '$$$'
509 steve.printMoney(); // alerts '$$$$$$$'
510
511          * @property borrow
512          * @static
513          * @type Function
514          * @param {Ext.Base} fromClass The class to borrow members from
515          * @param {Array/String} members The names of the members to borrow
516          * @return {Ext.Base} this
517          * @markdown
518          */
519         borrow: function(fromClass, members) {
520             var fromPrototype = fromClass.prototype,
521                 i, ln, member;
522
523             members = Ext.Array.from(members);
524
525             for (i = 0, ln = members.length; i &lt; ln; i++) {
526                 member = members[i];
527
528                 this.own(member, fromPrototype[member]);
529             }
530
531             return this;
532         },
533
534 <span id='Ext-Base-property-override'>        /**
535 </span>         * Override prototype members of this class. Overridden methods can be invoked via
536          * {@link Ext.Base#callOverridden}
537
538     Ext.define('My.Cat', {
539         constructor: function() {
540             alert(&quot;I'm a cat!&quot;);
541
542             return this;
543         }
544     });
545
546     My.Cat.override({
547         constructor: function() {
548             alert(&quot;I'm going to be a cat!&quot;);
549
550             var instance = this.callOverridden();
551
552             alert(&quot;Meeeeoooowwww&quot;);
553
554             return instance;
555         }
556     });
557
558     var kitty = new My.Cat(); // alerts &quot;I'm going to be a cat!&quot;
559                               // alerts &quot;I'm a cat!&quot;
560                               // alerts &quot;Meeeeoooowwww&quot;
561
562          * @property override
563          * @static
564          * @type Function
565          * @param {Object} members
566          * @return {Ext.Base} this
567          * @markdown
568          */
569         override: function(members) {
570             var prototype = this.prototype,
571                 name, i, member, previous;
572
573             for (name in members) {
574                 if (members.hasOwnProperty(name)) {
575                     member = members[name];
576
577                     if (typeof member === 'function') {
578                         if (typeof prototype[name] === 'function') {
579                             previous = prototype[name];
580                             member.$previous = previous;
581                         }
582
583                         this.ownMethod(name, member);
584                     }
585                     else {
586                         prototype[name] = member;
587                     }
588                 }
589             }
590
591             if (Ext.enumerables) {
592                 var enumerables = Ext.enumerables;
593
594                 for (i = enumerables.length; i--;) {
595                     name = enumerables[i];
596
597                     if (members.hasOwnProperty(name)) {
598                         if (prototype[name] !== undefined) {
599                             previous = prototype[name];
600                             members[name].$previous = previous;
601                         }
602
603                         this.ownMethod(name, members[name]);
604                     }
605                 }
606             }
607
608             return this;
609         },
610
611 <span id='Ext-Base-property-mixin'>        /**
612 </span>         * Used internally by the mixins pre-processor
613          * @private
614          */
615         mixin: flexSetter(function(name, cls) {
616             var mixin = cls.prototype,
617                 my = this.prototype,
618                 i, fn;
619
620             for (i in mixin) {
621                 if (mixin.hasOwnProperty(i)) {
622                     if (my[i] === undefined) {
623                         if (typeof mixin[i] === 'function') {
624                             fn = mixin[i];
625
626                             if (fn.$owner === undefined) {
627                                 this.ownMethod(i, fn);
628                             }
629                             else {
630                                 my[i] = fn;
631                             }
632                         }
633                         else {
634                             my[i] = mixin[i];
635                         }
636                     }
637                     else if (i === 'config' &amp;&amp; my.config &amp;&amp; mixin.config) {
638                         Ext.Object.merge(my.config, mixin.config);
639                     }
640                 }
641             }
642
643             if (my.mixins === undefined) {
644                 my.mixins = {};
645             }
646
647             my.mixins[name] = mixin;
648         }),
649
650 <span id='Ext-Base-method-getName'>        /**
651 </span>         * Get the current class' name in string format.
652
653     Ext.define('My.cool.Class', {
654         constructor: function() {
655             alert(this.self.getName()); // alerts 'My.cool.Class'
656         }
657     });
658
659     My.cool.Class.getName(); // 'My.cool.Class'
660
661          * @return {String} className
662          * @markdown
663          */
664         getName: function() {
665             return Ext.getClassName(this);
666         },
667
668 <span id='Ext-Base-property-createAlias'>        /**
669 </span>         * Create aliases for existing prototype methods. Example:
670
671     Ext.define('My.cool.Class', {
672         method1: function() { ... },
673         method2: function() { ... }
674     });
675
676     var test = new My.cool.Class();
677
678     My.cool.Class.createAlias({
679         method3: 'method1',
680         method4: 'method2'
681     });
682
683     test.method3(); // test.method1()
684
685     My.cool.Class.createAlias('method5', 'method3');
686
687     test.method5(); // test.method3() -&gt; test.method1()
688
689          * @property createAlias
690          * @static
691          * @type Function
692          * @param {String/Object} alias The new method name, or an object to set multiple aliases. See
693          * {@link Ext.Function#flexSetter flexSetter}
694          * @param {String/Object} origin The original method name
695          * @markdown
696          */
697         createAlias: flexSetter(function(alias, origin) {
698             this.prototype[alias] = this.prototype[origin];
699         })
700     });
701
702 })(Ext.Function.flexSetter);
703 </pre></pre></body></html>