diff --git a/README.md b/README.md index a507c0b..6b14819 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Name ==== -JooseX.Bridge.Ext - metaclass, bridging the class system of the ExtJS framework to Joose (or vice-versa, as you prefere). +JooseX.Bridge.Ext - metaclass, allowing you subclass ExtJS classes using Joose notation (or modify standard ExtJS classes) SYNOPSIS @@ -25,28 +25,199 @@ SYNOPSIS + Class('Test.Run.Harness.Browser.UI.TestGrid', { + + xtype : 'testgrid', + + isa : Ext.grid.GridPanel, + + does : ExtX.Some.Role.For.Grid, + + .... + }) + + DESCRIPTION =========== -`JooseX.Bridge.Ext` is a custom metaclass, which allows to bridge the class system of ExtJS framework to Joose. -It transparently turns all ExtJS classes into Joose classes. , and a +`JooseX.Bridge.Ext` is a custom metaclass, which bridges the class system of ExtJS framework to Joose (or vice-versa, as you prefere). +It transparently turns all ExtJS classes into Joose classes, and allows you to use any of Joose features for them. +Pleas refer to Joose [documentation](http://openjsan.org/go/?l=Joose), to know why you might want to do that :) -CAVEATS -======== -Initializers +EXAMPLES +======== + ExtClass('My.Panel', { + isa : Ext.Panel + }) + + // equivalent of: + + Class('My.Panel', { + meta : JooseX.Bridge.Ext, + + isa : Ext.Panel + }) + + + // automatically register the class with default xtype: + + var panel = Ext.ComponentMgr.create({ + xtype : 'My.Panel' + }) + + + // "meta : JooseX.Bridge.Ext" - can be omitted: + Class('Test.Run.Harness.Browser.UI.TestGrid', { + + xtype : 'testgrid', //custom xtype + + isa : Ext.grid.GridPanel, + + does : ExtX.Some.Role.For.Grid, + + trait : JooseX.CPS, + + + has : { + harness : { + is : 'rw', + required : true + } + }, + + + before : { + initComponent : function () { + var sm = new Ext.grid.CheckboxSelectionModel({ singleSelect : false }) + + this.addEvents('rowselect') + + Ext.apply(this, { + .... + }) + } + }, + + + after : { + initComponent : function () { + .... + } + }, + + + methods : { + + onRowSelect : function (selModel, indx, record) { + this.fireEvent('rowselect', this, record) + } + } + + }) USAGE ===== -First, include the Joose on your page. Then, between ExtJS adapter and main sources, insert this package and one of the convertors. +First, include Joose on your page. Then, between ExtJS adapter and main sources, insert this package and one of the convertors. + This package comes with two convertors : `JooseX.Bridge.Ext.Convertor` and `JooseX.Bridge.Ext.LazyConvertor`. -The 2nd convertor requires the `JooseX.Meta.Lazy` installed, and makes all classes lazy. Please refer to `JooseX.Meta.Lazy` -[documentation](http://openjsan.org/go?l=JooseX.Meta.Lazy) for details. + +The 2nd convertor requires `JooseX.Meta.Lazy` installed, and makes all classes lazy. Please refer to `JooseX.Meta.Lazy` +[documentation](http://openjsan.org/go?l=JooseX.Meta.Lazy) for details. + +See the above for examples how you can use new metaclass. + + +`xtype` builder +--------------- + +You can use new builder `xtype` in your class declaration. It will register your class with `Ext.reg` call. +If you will not specify `xtype`, your class will be registered using its name. + + +Metaclass inheritance +--------------------- + +By default, when Joose class inherit from superclass, it will be created using the metaclass of the parent. +So generally, when subclassing ExtJS classes you can omit the metaclass (the 3rd example). Sometimes though, +the metaclass needs to be explicitly specified (see [Explicit metaclass specification]) + + + +CAVEATS +======== + +Make sure you've read this section if you have any problems using the bridge. + + +Initial attribute values and setters +------------------------------------ + +This metaclass unifies two class systems, which uses different approaches to class construction. Thus appears some caveats. + +Joose provides system constructor for classes and classes should use `BUILD` and `initialize` for initialization. +[Details](http://openjsan.org/go?l=Joose.Manual.Construction) Joose also uses getters and setters concepts. + +Lightweight class system of ExtJS, simply calls the constructor of superclass. ExtJS applies provided configuration +values directly to instance. + +This metaclass first calls default Joose constructor, then the constructor from ExtJS. + +This means, that your class will be initialized "in Joose way" first, using any custom setter methods. +Then, it will be initialized "in ExtJS way", effectively overriding the initial values from previous step. +Also, the native setter method may be called too early - before the ExtJS constructor. + +For example this declaration will throw an exception: + + Class('My.Panel', { + isa : Ext.Panel, + + has : { + title : { + is : 'rw', + init : 'Joosified' + } + } + }) + +`Ext.Panel` have `setTitle` method, which Joose treats like setter, and tries to initialize the attribute with it. +However the call to `setTitle` relies on already initialized instance (it will fire the 'titlechange' event), so +the exception raise. + +The solution for such situations will be to use basic attributes, which do not have getters and setters: + + Class('My.Panel', { + isa : Ext.Panel, + + have : { + title : 'Joosified' + } + }) + +[Details](http://openjsan.org/go?l=Joose.Manual.Attributes) + + +Explicit metaclass specification +-------------------------------- + +Some of the classes in ExtJS framework are defined outside of its class system, using "raw JavaScript". +Such classes will have the low-level metaclass `Joose.Proto.Class`. If you will inherit from such class, +you will need to explicitly specify the metaclass, to use any advanced Joose feature. This should be a rare case +for Ext >3.0, but still. + +An example will be inheritance from Ext.Template: + + Class('My.Template', { + //explicit metaclass + meta : JooseX.Bridge.Ext, + + isa : Ext.Template + }) GETTING HELP @@ -62,7 +233,7 @@ SEE ALSO [http://github.com/SamuraiJack/joosex-bridge-ext/](http://github.com/SamuraiJack/joosex-bridge-ext/) -Web page of this extensions +Web page of this package [http://openjsan.org/go/?l=Joose](http://openjsan.org/go/?l=Joose) diff --git a/lib/JooseX/Bridge/Ext.js b/lib/JooseX/Bridge/Ext.js index a58b3d3..cfdb9ca 100644 --- a/lib/JooseX/Bridge/Ext.js +++ b/lib/JooseX/Bridge/Ext.js @@ -114,7 +114,7 @@ Name ==== -JooseX.Bridge.Ext - metaclass, bridging the class system of the ExtJS framework to Joose (or vice-versa, as you prefere). +JooseX.Bridge.Ext - metaclass, allowing you subclass ExtJS classes using Joose notation (or modify standard ExtJS classes) SYNOPSIS @@ -137,28 +137,199 @@ SYNOPSIS + Class('Test.Run.Harness.Browser.UI.TestGrid', { + + xtype : 'testgrid', + + isa : Ext.grid.GridPanel, + + does : ExtX.Some.Role.For.Grid, + + .... + }) + + DESCRIPTION =========== -`JooseX.Bridge.Ext` is a custom metaclass, which allows to bridge the class system of ExtJS framework to Joose. -It transparently turns all ExtJS classes into Joose classes. , and a +`JooseX.Bridge.Ext` is a custom metaclass, which bridges the class system of ExtJS framework to Joose (or vice-versa, as you prefere). +It transparently turns all ExtJS classes into Joose classes, and allows you to use any of Joose features for them. +Pleas refer to Joose [documentation](http://openjsan.org/go/?l=Joose), to know why you might want to do that :) -CAVEATS -======== -Initializers +EXAMPLES +======== + ExtClass('My.Panel', { + isa : Ext.Panel + }) + + // equivalent of: + + Class('My.Panel', { + meta : JooseX.Bridge.Ext, + + isa : Ext.Panel + }) + + + // automatically register the class with default xtype: + + var panel = Ext.ComponentMgr.create({ + xtype : 'My.Panel' + }) + + + // "meta : JooseX.Bridge.Ext" - can be omitted: + Class('Test.Run.Harness.Browser.UI.TestGrid', { + + xtype : 'testgrid', //custom xtype + + isa : Ext.grid.GridPanel, + + does : ExtX.Some.Role.For.Grid, + + trait : JooseX.CPS, + + + has : { + harness : { + is : 'rw', + required : true + } + }, + + + before : { + initComponent : function () { + var sm = new Ext.grid.CheckboxSelectionModel({ singleSelect : false }) + + this.addEvents('rowselect') + + Ext.apply(this, { + .... + }) + } + }, + + + after : { + initComponent : function () { + .... + } + }, + + + methods : { + + onRowSelect : function (selModel, indx, record) { + this.fireEvent('rowselect', this, record) + } + } + + }) USAGE ===== -First, include the Joose on your page. Then, between ExtJS adapter and main sources, insert this package and one of the convertors. +First, include Joose on your page. Then, between ExtJS adapter and main sources, insert this package and one of the convertors. + This package comes with two convertors : `JooseX.Bridge.Ext.Convertor` and `JooseX.Bridge.Ext.LazyConvertor`. -The 2nd convertor requires the `JooseX.Meta.Lazy` installed, and makes all classes lazy. Please refer to `JooseX.Meta.Lazy` -[documentation](http://openjsan.org/go?l=JooseX.Meta.Lazy) for details. + +The 2nd convertor requires `JooseX.Meta.Lazy` installed, and makes all classes lazy. Please refer to `JooseX.Meta.Lazy` +[documentation](http://openjsan.org/go?l=JooseX.Meta.Lazy) for details. + +See the above for examples how you can use new metaclass. + + +`xtype` builder +--------------- + +You can use new builder `xtype` in your class declaration. It will register your class with `Ext.reg` call. +If you will not specify `xtype`, your class will be registered using its name. + + +Metaclass inheritance +--------------------- + +By default, when Joose class inherit from superclass, it will be created using the metaclass of the parent. +So generally, when subclassing ExtJS classes you can omit the metaclass (the 3rd example). Sometimes though, +the metaclass needs to be explicitly specified (see [Explicit metaclass specification]) + + + +CAVEATS +======== + +Make sure you've read this section if you have any problems using the bridge. + + +Initial attribute values and setters +------------------------------------ + +This metaclass unifies two class systems, which uses different approaches to class construction. Thus appears some caveats. + +Joose provides system constructor for classes and classes should use `BUILD` and `initialize` for initialization. +[Details](http://openjsan.org/go?l=Joose.Manual.Construction) Joose also uses getters and setters concepts. + +Lightweight class system of ExtJS, simply calls the constructor of superclass. ExtJS applies provided configuration +values directly to instance. + +This metaclass first calls default Joose constructor, then the constructor from ExtJS. + +This means, that your class will be initialized "in Joose way" first, using any custom setter methods. +Then, it will be initialized "in ExtJS way", effectively overriding the initial values from previous step. +Also, the native setter method may be called too early - before the ExtJS constructor. + +For example this declaration will throw an exception: + + Class('My.Panel', { + isa : Ext.Panel, + + has : { + title : { + is : 'rw', + init : 'Joosified' + } + } + }) + +`Ext.Panel` have `setTitle` method, which Joose treats like setter, and tries to initialize the attribute with it. +However the call to `setTitle` relies on already initialized instance (it will fire the 'titlechange' event), so +the exception raise. + +The solution for such situations will be to use basic attributes, which do not have getters and setters: + + Class('My.Panel', { + isa : Ext.Panel, + + have : { + title : 'Joosified' + } + }) + +[Details](http://openjsan.org/go?l=Joose.Manual.Attributes) + + +Explicit metaclass specification +-------------------------------- + +Some of the classes in ExtJS framework are defined outside of its class system, using "raw JavaScript". +Such classes will have the low-level metaclass `Joose.Proto.Class`. If you will inherit from such class, +you will need to explicitly specify the metaclass, to use any advanced Joose feature. This should be a rare case +for Ext >3.0, but still. + +An example will be inheritance from Ext.Template: + + Class('My.Template', { + //explicit metaclass + meta : JooseX.Bridge.Ext, + + isa : Ext.Template + }) GETTING HELP @@ -174,7 +345,7 @@ SEE ALSO [http://github.com/SamuraiJack/joosex-bridge-ext/](http://github.com/SamuraiJack/joosex-bridge-ext/) -Web page of this extensions +Web page of this package [http://openjsan.org/go/?l=Joose](http://openjsan.org/go/?l=Joose) @@ -213,88 +384,4 @@ Redistribution and use in source and binary forms, with or without modification, THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -*/ - - - - - -/** - * Improved Ext.ux.extend. Provides exactly the same interface as standard Ext.ux.extend plus it converts both classes into Joose Classes..
- * @name Joose.Bridge.Ext#extend - * @methodOf Joose.Bridge.Ext - * @param {Class} subClass The class inheriting the functionality - * @param {Class} superClass The class being extended - * @param {Object} [overrides] A literal with members which are copied into the subclass's prototype, and are therefore shared between all instances of the new class. - * @return {Class} The subclass constructor. - */ - - -/** - * Class builder for meta-class Joose.ExtClass, which provide compatibility with Joose. This is the exact analog of standard Class function in Joose, - * see this page for examples. This function is copied into global scope and is using for creation of new classes. - * @name Joose.Bridge.Ext#ExtClass - * @methodOf Joose.Bridge.Ext - * @param {String} name The name of the class, being created - * @param {Object} [overrides] A literal with members, from which the new Class is constructed. See Joose manual. - * @return {Class} The class constructor. - */ - - -/** - * @class - * @name Joose.Bridge.Ext - * @desc This package provides fully backward-compatible drop-in replacement for Ext.extend, which turns standard Ext classes into Joose Classes. - * After including this package you can derive new classes in standard way -
-Ext.myWindow = Joose.Bridge.Ext.my.extend(Ext.Window, {
-    
-    initComponent : function (){
-        Ext.myWindow.superclass.initComponent.call(this)
-        this.width = 800
-    }
-    
-})
-
-or in the native Joose way: -
-ExtClass('Ext.myWindow', {
-    isa : Ext.Window,
-    
-    after : {
-        initComponent : function (){
-            this.width = 800
-        }
-    }
-    
-})
-
-in both cases you can use any of Joose features with your classes, for example - apply Roles, either statically, during creation: -
-Role('Joosificator', {
-    before : {
-        render : function(){
-            this.title = "Joosified: " + this.title
-        }
-    }
-})
-
-ExtClass('Ext.myWindow', {
-    isa : Ext.Window,
-    
-    does : [Joosificator],
-    
-    ...
-})
-
-or dynamically, at run-time: -
-Ext.myWindow.meta.extend({
-    does : [Joosificator]
-})
-
- *
See the forum thread for additional details and Joose home page for complete manual on Joose. - * @version 0.1 - * @author SamuraiJack - * @license LGPL 3.0 - */ +*/ \ No newline at end of file