Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / guide / getting_started.html
1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><script type="text/javascript" src="../ext-all.js"></script><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../scrollbars.css" type="text/css"><link rel="stylesheet" href="../docs.css" type="text/css"><link id="styleCss" rel="stylesheet" href="../style.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script><link rel="stylesheet" href="../prettify.css" type="text/css"><!-- link(rel: 'stylesheet', href: req.baseURL + '/css/ext4.css', type: 'text/css')--><link rel="shortcut icon" type="image/ico" href="../favicon.ico"><!--[if IE]>
2 <style type="text/css">.head-band { display: none; }
3 .header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
4 .doc-tab .members .member a.more { background-color: #efefef; }
5 </style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
6 </head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit 
7 <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a></div><div class="wrapper"><div class="head-band"></div><div class="header"><h2><a href="../index.html">Sencha Documentation</a></h2></div><div id="search"><form><input type="text" placeholder="Search" id="search-field" autocomplete="off" name="q"></form><div id="search-box"></div></div><div id="treePanel"></div><div id="container"><script type="text/javascript">
8
9     req = {
10         liveURL: '.',
11         standAloneMode: true,
12         origDocClass: 'undefined',
13         docClass: 'undefined',
14         docReq: 'undefined',
15         version: '4.0',
16         baseURL: '.',
17         baseDocURL: '.',
18         baseProdURL: '.'
19     };
20
21     clsInfo = {};
22
23
24
25 </script>
26
27 <script type="text/javascript" src="../search.js"></script>
28 <!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
29 <script type="text/javascript" src="../class_tree.js"></script>
30 <script type="text/javascript" src="../class_doc.js"></script>
31 <div id="top-block" class="top-block"></div><div id="docContent"><div class="guide"><h1>I. Introduction</h1>
32
33 <hr></hr>
34
35 <p>Ext JS 4 is by far the biggest overhaul we’ve ever made to Ext JS, and constitutes the most advanced JavaScript framework ever created. Almost every area of the framework has been upgraded, from the generated HTML to the class system. We’ve unified APIs, added incredible new capabilities, and improved the performance of the entire framework.</p>
36
37 <p>With Ext JS 4 we’ve been driven by three key goals: speed, robustness and ease of use. We wanted the framework to be as fast and as robust as possible on every browser, and to be easy to learn and use. To achieve this we took the whole framework back to the drawing board, and what we’ve come back with is the fastest, most bullet-proof version of Ext JS we’ve ever created. Best of all, we’ve managed to do it while staying true to the core experience of writing apps “the Ext JS way.”</p>
38
39 <p><iframe src="http://player.vimeo.com/video/17666102?byline=0&amp;portrait=0" width="500" height="281" frameborder="0"></iframe></p>
40
41 <p><iframe src="http://player.vimeo.com/video/17733892?byline=0&amp;portrait=0" width="500" height="281" frameborder="0"></iframe></p>
42
43 <h1>II. Getting Started</h1>
44
45 <hr></hr>
46
47 <h2>1. Requirements</h2>
48
49 <h3>1.1 Web Browsers</h3>
50
51 <p>Ext JS 4 supports almost any known web browsers, from Internet Explorer 6 to Chrome 11. During development, we recommend that you choose one of the following as the primary browsers for the best debugging experience:</p>
52
53 <ul><li><a href="http://www.google.com/chrome/intl/en/landing_chrome_mac.html?hl=en">Google Chrome</a> 10+</li><li><a href="http://www.apple.com/safari/download/">Apple Safari</a> 5+</li><li><a href="http://www.mozilla.com/en-US/firefox/new/?from=getfirefox">Mozilla Firefox</a> 4+</li></ul>
54
55 <h3>1.2 Debugging Tools</h3>
56
57 <p>Please refer to the dedicated <a href="getting_started.html#">Debugging Handbook</a> guide on the recommended tools for each and every browser, as well as how to make use of them to aid development.</p>
58
59 <h3>1.3 Web Server</h3>
60
61 <p>Even though a local web server is not a requirement to use Ext JS 4, it is still highly recommended that you develop with one, since <a href="http://en.wikipedia.org/wiki/XHR">XHR</a> over local <a href="http://en.wikipedia.org/wiki/File_URI_scheme">file:// protocol</a> has <a href="http://en.wikipedia.org/wiki/Same_origin_policy">cross origin restriction</a> on most browsers.</p>
62
63 <h3>1.4. Ext JS 4 SDK</h3>
64
65 <p>Download <a href="http://www.sencha.com/products/extjs/">Ext JS 4 SDK</a> if you haven't done so. Unzip the package within your web root directory tree. This guide assumes that <code>http://localhost/ext-4.0</code> points to the top level directory of the downloaded SDK.</p>
66
67 <p>Open <code>http://localhost/ext-4.0/index.html</code> on your web browser. If a welcome page appears, you are all set.</p>
68
69 <h2>2. Application Structure</h2>
70
71 <p>Although not being mandatory, all suggestions listed below should be considered as best-practice guidelines to keep your application well organized, extensible and maintainable.</p>
72
73 <h3>2.1 Basic Structure</h3>
74
75 <pre class="prettyprint"><code>- appname
76     - app
77         - namespace
78             - Class1.js
79             - Class2.js
80             - ...
81     - resources
82         - css
83         - images
84         - ...
85     - app.js
86     - index.html</code></pre>
87
88 <p>in which:</p>
89
90 <ul><li><code>appname</code> is a directory containing all your application's source files</li><li><code>app</code> contains all your classes, the naming style of which should follow the convention listed in the <a href="class_system.html">Class System</a> guide</li><li><code>resources</code> contains additional CSS and image files which are responsible for the look and feel of the application, as well as other static resources (XML, JSON, etc.)</li><li><code>index.html</code> is the entry-point HTML document</li><li><code>app.js</code> contains your own application's logics</li></ul>
91
92 <p>An Ext JS application is self-contained in a single HTML document, the content of which has this format:</p>
93
94 <pre class="prettyprint"><code>&lt;html&gt;
95 &lt;head&gt;
96     &lt;title&gt;Application Name&lt;/title&gt;
97
98     &lt;link rel="stylesheet" type="text/css" href="path/to/sdk/resources/css/ext-all.css"&gt;
99     &lt;script type="text/javascript" src="path/to/sdk/ext-debug.js"&gt;&lt;/script&gt;
100     &lt;script type="text/javascript" src="app.js"&gt;&lt;/script&gt;
101 &lt;/head&gt;
102 &lt;body&gt;&lt;/body&gt;
103 &lt;/html&gt;</code></pre>
104
105 <p>whereby:</p>
106
107 <ul><li><code>path/to/sdk</code> points to Ext JS 4 SDK directory in section <em>1.4</em></li><li><code>path/to/sdk/resources/css/ext-all.css</code> contains all styling information needed for the whole framework</li><li><code>path/to/sdk/ext(-debug).js</code> contains Ext JS 4 Core library (or <code>path/to/sdk/ext-all(-debug).js</code>, as explained below)</li></ul>
108
109 <p>From this point you need to choose between 2 different library inclusion methods. Each has its own pros and cons listed below:</p>
110
111 <ol><li><p>Include <code>path/to/sdk/ext-all.js</code> (<code>path/to/sdk/ext-all-debug.js</code> during development), which contains the whole framework.</p><ul><li>Pros:<ul><li>There is no need to worry about dependencies when using default Ext JS components (but not your own custom classes)</li></ul></li><li><p>Cons:</p><ul><li>Deployment file size could be unnecessarily large if your application doesn't make use of everything the library has to offer. That, as a consequence, would lead to slower application initialization due to unnecessary script execution as well as network data transfer overheads.</li><li><p>Debugging is difficult due to the fact that all source code is confined into one big file.</p></li></ul></li></ul></li><li><p>Include <code>path/to/sdk/ext.js</code> (<code>path/to/sdk/ext-debug.js</code> during development) which contains just the minimum core library, and make use of <a href="../api/Ext.Loader.html">Ext.Loader</a> for automatic dependencies resolution.</p><ul><li>Pros:<ul><li>Your application only loads exactly what it needs as you develop. Deployed file size will be minimal.</li><li>Debugging is simple and straight-forward since all source files are loaded separated. Errors messages come with the exact line numbers and file names from which they occur.</li></ul></li><li>Cons:<ul><li>Attention to dependencies when using default components shipped with the SDK is needed</li></ul></li></ul></li></ol>
112
113 <p>In summary, it is recommended that you should only use <code>ext-all(-debug).js</code> if you need to shorten the initial learning curve. Otherwise, <code>ext(-debug).js</code> is preferred in most cases for actual application development.</p>
114
115 <p>Last but not least, <code>app.js</code> is the entry-point of your own application's logic. For a basic application, the typical format of which may look like this:</p>
116
117 <pre class="prettyprint"><code>// Register namespaces and their corresponding paths to Ext.Loader
118 Ext.Loader.setPath({
119     'AppName': 'app',
120     ... // Other namespaces
121 });
122
123 // Specify a list of classes your application your application needs
124 Ext.require([
125     ...
126 ]);
127
128 // Application's initialization
129 Ext.onReady(function() {
130
131     ...
132
133 });</code></pre>
134
135 <h3>2.2 MVC (Model-View-Controller) Structure</h3>
136
137 <p>Ext JS 4 shipped with a robust MVC architecture which maximize extensibility and maintainability for medium to large scale applications. Please refer to the <a href="application_architecture.html">MVC Application Architecture guide</a> for detailed instructions.</p>
138
139 <h1>3. Deployment</h1>
140
141 <p>The newly introduced Sencha SDK Tools (<a href="http://www.sencha.com/products/extjs/download/)">download here</a> makes deployment of any Ext JS 4 application easier than ever. The tools allows you to generate a manifest of all dependencies in the form of a JSB3 (JSBuilder file format) file, and create a minimal custom build of just what your application needs within minutes.</p>
142
143 <p>Once you've installed the SDK Tools, open a terminal window and navigate into your application's directory.</p>
144
145 <pre class="prettyprint"><code>cd path/to/application</code></pre>
146
147 <p>From here you only need to run a couple of simple commands. The first one generates a JSB3 file:</p>
148
149 <pre class="prettyprint"><code>sencha create jsb -a index.html -p app.jsb3</code></pre>
150
151 <p>This scans your <code>index.html</code> file for all framework and application files that are actually used by the app, and then creates a JSB file called <code>app.jsb3</code>. Generating the JSB3 first gives us a chance to modify the generated <code>app.jsb3</code> before building - this can be helpful if you have custom resources to copy, but in most cases we can immediately proceed to build the application with the second command:</p>
152
153 <pre class="prettyprint"><code>sencha build -p app.jsb3 -d .</code></pre>
154
155 <p>This takes the JSB3 file and creates an <code>app-all.js</code>, which is a minimized build of your application plus all of the Ext JS classes required to run it. It also creates an <code>all-classes.js</code> file, which has the same classes as <code>app-all.js</code>, but is not minified so is very useful for debugging problems with your built application. In short, <code>app-all.js</code> is the minified and production-ready version of <code>all-classes.js + app.js</code>.</p>
156
157 <p>Most applications will need a separate <code>index.html</code> for the deployed version of the app, for example to add Analytics includes or other production-only logic into that file. Typically you would end up with a production <code>index.html</code> file that looks like this:</p>
158
159 <pre class="prettyprint"><code>&lt;html&gt;
160 &lt;head&gt;
161     &lt;title&gt;Application Name&lt;/title&gt;
162
163     &lt;link rel="stylesheet" type="text/css" href="path/to/sdk/resources/css/ext-all.css"&gt;
164     &lt;script type="text/javascript" src="path/to/sdk/ext.js"&gt;&lt;/script&gt;
165     &lt;script type="text/javascript" src="app-all.js"&gt;&lt;/script&gt;
166 &lt;/head&gt;
167 &lt;body&gt;&lt;/body&gt;
168 &lt;/html&gt;</code></pre>
169
170 <p>Notice that <code>path/to/sdk/ext-debug.js</code> has been replaced with <code>path/to/sdk/ext.js</code>, and <code>app.js</code> has been replaced with <code>app-all.js</code> in this production version, comparing with the development one described in section <em>2.1</em></p>
171
172 <p>For applications built on top of a dynamic server-side language like PHP, Ruby, ASP, etc., you can simply replace <code>index.html</code> in the first command to the actual URL of your application. This URL should be the same with what is viewable on the browsers during development. For example:</p>
173
174 <pre class="prettyprint"><code>sencha create jsb -a http://localhost/path/to/application/index.php -p app.jsb3</code></pre>
175
176 <h2>This guide is a work in progress.</h2>
177
178 <p>Please check back soon</p></div></div></div></div></body></html>