docs/guides/getting_started/README.md

   1 # Getting Started
   2
   3 ## 1. Requirements
   4
   5 ### 1.1 Web Browsers
   6
   7 Ext JS 4 supports all major web browsers, from Internet Explorer 6 to the latest version of Google Chrome. During development, however, we recommend that you choose one of the following browsers for the best debugging experience:
   8
   9 - [Google Chrome](http://www.google.com/chrome/) 10+
  10 - [Apple Safari](http://www.apple.com/safari/download/) 5+
  11 - [Mozilla Firefox](http://www.mozilla.com/en-US/firefox/fx/) 4+ with the [Firebug](http://getfirebug.com/) Web Development Plugin
  12
  13 This tutorial assumes you are using the latest version of Google Chrome.  If you don't already have Chrome take a moment to install it, and familiarize yourself with the [Chrome Developer Tools](http://code.google.com/chrome/devtools/docs/overview.html).
  14
  15 ### 1.2 Web Server
  16
  17 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 [XHR](http://en.wikipedia.org/wiki/XHR) over local [file:// protocol](http://en.wikipedia.org/wiki/File_URI_scheme) has [cross origin restriction](http://en.wikipedia.org/wiki/Same_origin_policy) on most browsers.
  18 If you don't already have a local web server it is recommended that you download and install Apache HTTP Server.
  19
  20 - [Instructions for installing Apache on Windows](http://httpd.apache.org/docs/current/platform/windows.html)
  21 - [Instructions for installing Apache on Linux](http://httpd.apache.org/docs/current/install.html)
  22 - Mac OS X comes with a build in apache installation which you can enable by navigating to "System Preferences > Sharing" and checking the box next to "Web Sharing".
  23
  24 Once you have installed or enabled Apache you can verify that it is running by navigating to [localhost](http://localhost/) in your browser.  You should see a startup page indicating that Apache HTTP Server was installed successfully and is running.
  25
  26 ### 1.3. Ext JS 4 SDK
  27
  28 Download [Ext JS 4 SDK][sdk-download]. Unzip the package to a new directory called "extjs" within your web root directory.  If you aren't sure where your web root directory is, consult the docs for your web server.
  29 Your web root directory may vary depending on your operating system, but if you are using Apache it is typically located at:
  30
  31 - Windows - "C:\Program Files\Apache Software Foundation\Apache2.2\htdocs"
  32 - Linux - "/var/www/"
  33 - Mac OS X - "/Library/WebServer/Documents/"
  34
  35 Once you have finished installing Apache navigate to [http://localhost/extjs/index.html](http://localhost/extjs/index.html) in your browser. If an Ext JS 4 welcome page appears, you are all set.
  36
  37 ## 2. Application Structure
  38
  39 ### 2.1 Basic Structure
  40
  41 Although not mandatory, all suggestions listed below should be considered as best-practice guidelines to keep your application well organized, extensible and maintainable.
  42 The following is the recommended directory structure for an Ext JS application:
  43
  44     - appname
  45         - app
  46             - namespace
  47                 - Class1.js
  48                 - Class2.js
  49                 - ...
  50         - extjs
  51         - resources
  52             - css
  53             - images
  54             - ...
  55         - app.js
  56         - index.html
  57
  58 - `appname` is a directory that contains all your application's source files
  59 - `app` contains all your classes, the naming style of which should follow the convention listed in the [Class System](#/guide/class_system) guide
  60 - `extjs` contains the Ext JS 4 SDK files
  61 - `resources` 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.)
  62 - `index.html` is the entry-point HTML document
  63 - `app.js` contains your application's logic
  64
  65 Don't worry about creating all those directories at the moment.  For now lets just focus on creating the minimum amount of code necessary to get an Ext JS application up and running.
  66 To do this we'll create a basic "hello world" Ext JS application called "Hello Ext".  First, create the following directory and files in your web root directory.
  67
  68     - helloext
  69         - app.js
  70         - index.html
  71
  72 Then unzip the Ext JS 4 SDK to a directory named `extjs` in the `helloext` directory
  73
  74 A typical Ext JS application is contained in a single HTML document - `index.html`.  Open `index.html` and insert the following html code:
  75
  76     <html>
  77     <head>
  78         <title>Hello Ext</title>
  79
  80         <link rel="stylesheet" type="text/css" href="extjs/resources/css/ext-all.css">
  81         <script type="text/javascript" src="extjs/ext-debug.js"></script>
  82         <script type="text/javascript" src="app.js"></script>
  83     </head>
  84     <body></body>
  85     </html>
  86
  87 - `extjs/resources/css/ext-all.css` contains all styling information needed for the whole framework
  88 - `extjs/ext-debug.js` contains a minimal set of Ext JS 4 Core library classes
  89 - `app.js` will contain your application code
  90
  91 Now you're ready to write your application code. Open `app.js` and insert the following JavaScript code:
  92
  93     Ext.application({
  94         name: 'HelloExt',
  95         launch: function() {
  96             Ext.create('Ext.container.Viewport', {
  97                 layout: 'fit',
  98                 items: [
  99                     {
 100                         title: 'Hello Ext',
 101                         html : 'Hello! Welcome to Ext JS.'
 102                     }
 103                 ]
 104             });
 105         }
 106     });
 107
 108 Now open your browser and navigate to [http://localhost/helloext/index.html](http://localhost/helloext/index.html). You should see a panel with a title bar containing the text "Hello Ext" and the "welcome" message in the panel's body area.
 109
 110 ### 2.2 Dynamic Loading
 111
 112 Open the Chrome Developer Tools and click on the Console option.  Now refresh the Hello Ext application.  You should see a warning in the console that looks like this:
 113
 114 {@img loader-warning-viewport.png testing}
 115
 116 Ext JS 4 comes with a system for dynamically loading only the JavaScript resources necessary to run your app.
 117 In our example `Ext.create` creates an instance of `Ext.container.Viewport`.  When `Ext.create` is called the loader will first check to see if `Ext.container.Viewport` has been defined.
 118 If it is undefined the loader will try to load the JavaScript file that contains the code for `Ext.container.Viewport` before instantiating the viewport object.  In our example the `Viewport.js` file gets loaded successfully, but the loader detects
 119 that files are being loaded in a less-than optimal manner.  Since we are loading the `Viewport.js` file only when an instance of `Ext.container.Viewport` is requested, execution of the code is stopped until that file has been loaded successfully, causing a short delay.
 120 This delay would be compounded if we had several calls to Ext.create,  because the application would wait for each file to load before requesting the next one.
 121
 122 To fix this, we can add this one line of code above the call to `Ext.application`:
 123
 124 `Ext.require('Ext.container.Viewport');`
 125
 126 This will ensure that the file containing the code for `Ext.container.Viewport` is loaded before the application runs.  You should no longer see the `Ext.Loader` warning when you refresh the page.
 127
 128 ### 2.3 Library Inclusion methods
 129
 130 When you unzip the Ext JS 4 download, you will see the following files:
 131
 132 1. `ext-debug.js` - This file is only for use during development.  It provides the minimum number of core Ext JS classes needed to get up and running.  Any additional classes should be dynamically loaded as separate files as demonstrated above.
 133
 134 2. `ext.js` - same as `ext-debug.js` but minified for use in production.  Meant to be used in combination with your application's `app-all.js` file. (see section *3*)
 135
 136 3. `ext-all-debug.js` - This file contains the entire Ext JS library.  This can be helpful for shortening your initial learning curve, however `ext-debug.js` is preferred in most cases for actual application development.
 137
 138 4. `ext-all.js` - This is a minified version of `ext-all-debug.js` that can be used in production environments, however, it is not recommended since most applications will not make use of all the classes that it contains.  Instead it is recommended that you create a custom build for your production environment as described in section *3*.
 139
 140 ## 3. Deployment
 141
 142 The newly-introduced Sencha SDK Tools ([download here][sdk-download]) makes deployment of any Ext JS 4 application easier than ever. The tools allow you to generate a manifest of all JavaScript dependencies in the form of a JSB3 (JSBuilder file format) file, and create a custom build containing only the code that your application needs.
 143
 144 Once you've installed the SDK Tools, open a terminal window and navigate into your application's directory.
 145
 146     cd path/to/web/root/helloext
 147
 148 From here you only need to run a couple of simple commands. The first one generates a JSB3 file:
 149
 150     sencha create jsb -a index.html -p app.jsb3
 151
 152 For applications built on top of a dynamic server-side language like PHP, Ruby, ASP, etc., you can simply replace `index.html` with the actual URL of your application:
 153
 154     sencha create jsb -a http://localhost/helloext/index.html -p app.jsb3
 155
 156 This scans your `index.html` file for all framework and application files that are actually used by the app, and then creates a JSB file called `app.jsb3`. Generating the JSB3 first gives us a chance to modify the generated `app.jsb3` 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:
 157
 158     sencha build -p app.jsb3 -d .
 159
 160 This creates 2 files based on the JSB3 file:
 161
 162 1. `all-classes.js` - This file contains all of your application's classes. It is not minified so is very useful for debugging problems with your built application.  In our example this file is empty because our "Hello Ext" application does not contain any classes.
 163
 164 2. `app-all.js` - This file is a minimized build of your application plus all of the Ext JS classes required to run it. It is the minified and production-ready version of `all-classes.js + app.js`.
 165
 166 An Ext JS application will need a separate `index.html` for the production version of the app.  You will typically handle this in your build process or server side logic, but for now let's just create a new file in the `helloext` directory called `index-prod.html`:
 167
 168     <html>
 169     <head>
 170         <title>Hello Ext</title>
 171
 172         <link rel="stylesheet" type="text/css" href="extjs/resources/css/ext-all.css">
 173         <script type="text/javascript" src="extjs/ext.js"></script>
 174         <script type="text/javascript" src="app-all.js"></script>
 175     </head>
 176     <body></body>
 177     </html>
 178
 179 Notice that `ext-debug.js` has been replaced with `ext.js`, and `app.js` has been replaced with `app-all.js`. If you navigate to [http://localhost/helloext/index-prod.html](http://localhost/helloext/index-prod.html) in your browser, you should see the production version of the "Hello Ext" application.
 180
 181 ## 4. Further Reading
 182
 183 1. [Class System](#/guide/class_system)
 184 2. [MVC Application Architecture](#/guide/application_architecture)
 185 3. [Layouts and Containsers](#/guide/layouts_and_containers)
 186 4. [Working with Data](#/guide/data)
 187
 188 [sdk-download]: http://www.sencha.com/products/extjs/