/ext-4.0.7/jsbuilder/README.md

  1#What's new
  2
  3##Loader
  4To init the Loader, assuming PATH points to the root folder
  5
  6	load(PATH + 'src/Loader.js');
  7	Loader.setBasePath(PATH + 'src');
  8	
  9After that, simply include other classes at will. The behaviour should be similar to require_once in PHP. It is specially useful when you need to include dynamic components during run-time without having to specify all of them at the beginning. For example:
 10
 11	// Single class
 12	Loader.require('Filesystem');
 13	Fiesystem.readFile('some/file/here.js');
 14	
 15	// Multiple
 16	Loader.require(['Filesystem', 'Logger', 'Parser']);
 17	
 18	// Class name syntax
 19	Loader.require('Some.Thing.Here'); // Will load Some/Thing/Here.js within the basePath set above
 20
 21This is beautifully utilized by the Parser below to dynamically load Statement classes on demand.
 22
 23##Parser
 24
 25###Introduction
 26The new Parser allows fully customizable build, to be consumed by all of our products. It combines the syntax of inline JavaScript comments & HTML for high readablity. As a quick example, let say we have this chunk of code:
 27
 28	alert('Some code here');
 29	
 30	//<if browser="ie" browserVersion="6">
 31	
 32	alert("Some ugly hacks just to target IE 6 only");
 33	
 34	//<else>
 35	
 36	alert("Others");
 37	
 38	//</if>
 39	
 40During build time, if we supply the following params:
 41
 42	browser: 'ie'
 43	browserVersion: 7
 44	
 45The result will be:
 46
 47	alert('Some code here');
 48	
 49	alert("Others");
 50	
 51###Nested conditions
 52Nested conditions / tags are fully supported without sacrificing much build performance. We can mix and match complex conditions when necessary:
 53	//<if condition="here">
 54		//<debug>
 55			//<if blah>
 56				...
 57			//</if>
 58			...
 59		//</debug>
 60		...
 61		//<if other="cond">
 62			...
 63		//<else>
 64			//<deprecated since="1.0">
 65				...
 66			//</deprecated>
 67			...
 68		//</if>
 69	//</if>
 70		
 71	
 72###Attribute Syntax
 73Currently all these are supported:
 74	browser="ie"
 75	browser='ie'
 76	browser=ie
 77
 78Comparisons:	
 79	browser="6"
 80	browser="!6"
 81	browser=">6"
 82	browser="<6"
 83	browser=">=6"
 84	browser="<=6"
 85	
 86Auto casting during evaluation
 87	Boolean: "true" => true, "false" => false
 88	Numeric: "3.2" => 3.2
 89	
 90###Tag Name:
 91Parser package is designed to be highly extensible. All custom tag names have their own corresponding class, extending from Parser.Statement (Parser/Statement.js). Currently we have the following:
 92
 93	If
 94	Elseif
 95	Else
 96	Debug
 97	Deprecated
 98	
 99Debug and Deprecated extends from If, and they make typing more convenient:
100	
101	//<debug>
102	alert("Stuff in here are strictly for debugging, shouldn't appear during production");
103	//</debug>
104	
105Which is equivalent to:
106
107	//<if debug="true">
108	...
109	//</if>
110	
111	// OR
112	
113	//<if debug>
114	...
115	//</if>
116	
117Deprecated has a required "since" attribute:
118
119	//<deprecated since="2.0">
120	alert("Old stuff for backwards compatibility");
121	//</deprecated>
122	
123If the param name "minVersion" (minimum supported version) is set to 3.0 (>2.0) during build, the above will disappear for good.
124
125Unknown tags (no equivalent classes that the Loader can find) will be ignored
126	//<notSupportedYet>
127	alert("Nothing special")
128	//</notSupportedYet>
129
130Furture tags can be added with ease based on our needs. This is how Parser.Statement.Debug looks like:
131	Loader.require('Parser.Statement.If');
132
133	Parser.Statement.Debug = Ext.extend(Parser.Statement.If, {
134	    constructor: function() {
135	        Parser.Statement.Debug.superclass.constructor.apply(this, arguments);
136
137	        this.setProperty('debug', true);
138	    }
139	});
140
141###Inversion
142For convenience, conditional inversion can be done like this:
143	//<!if browser="ie">
144	
145	//</!if>
146	
147	//<!debug>
148	
149	//<else>
150	
151	//</!debug>
152
153###Standalone
154Parser is a singleton and does not depend on anything else other than Loader.js and Ext.js. It's unittest-able too. Usage is straight-forward:
155
156	Parser.setParams({
157		debug: false,
158		minVersion: 2.2,
159		ie6Compatible: false
160		// More params...
161	});
162	
163	// Returns the parsed content of the given file, based on the params supplied above
164	var parsed = Parser.parse("path/to/file.js");
165	
166###Integration with building process
167Parser will automatically process final target files right before compression. It takes the "options" property inside jsb3 file as the params, merged with the old "debug" property. For example, currently in ext-touch.jsb3:
168	...
169	"builds": [
170    {
171        "name": "Sencha Touch",
172        "target": "ext-touch.js",
173        "debug": true,
174        "packages": [
175        	...
176        ]
177    }
178
179To supply more params for Parser:
180	...
181	"builds": [
182    {
183        "name": "Sencha Touch",
184        "target": "ext-touch.js",
185        "debug": true,
186		"options": {
187			"minVersion": 2.0,
188			"experimental": true
189		}
190        "packages": [
191        	...
192        ]
193    }
194
195From which the Parser will process with the following params:
196	{
197		debug: true,
198		minVersion: 2.0,
199		experimental: true
200	}
201	
202###Unit testing
203	/path/to/jsdb tests/run.js --name parser