# Using Sencha Cmd with Ext JS 4.2+ {@img ../command/sencha-command-128.png} This guide walks through the process of using Sencha Cmd with Ext JS 4.2 applications starting with the `sencha generate app` command and ending with a running application. This guide applies mostly to *new* single-page Ext JS applications. If you have an *existing* single-page application you might consider using Sencha Cmd to build an application skeleton based on this guide and then migrate your application code to this preferred structure. This will provide you with the maximum leverage from Sencha Cmd. If this option is not right for your app, you can still use Sencha Cmd to help with many aspects of your development. For developing single-page applications with a custom folder structure, see [Single-Page Ext JS Apps](#/guide/command_app_single). If you work with applications that have multiple pages, it will be helpful to start by learning about the simple uses of Sencha Cmd described in this and the [Single-Page Ext JS Apps](#/guide/command_app_single) guide. For details on developing more complex, multipage Ext JS applications, refer to [Multi-Page and Mixed Apps](#/guide/command_app_multi). ## Generating Your Application Our starting point is to generate an application skeleton. This is done using the following command: sencha generate app MyApp /path/to/MyApp **Important.** The above command must be able to determine the appropriate SDK. This can be satisfied by either executing this command from a folder containing an extracted SDK distribution or by using the `-sdk` switch like so: sencha -sdk /path/to/SDK generate app MyApp /path/to/MyApp The application files generated by this command should have the following structure: .sencha/ # Sencha-specific files (e.g. configuration) app/ # Application-specific content sencha.cfg # Application configuration file for Sencha Cmd build-impl.xml # Standard application build script plugin.xml # Application-level plugin for Sencha Cmd workspace/ # Workspace-specific content (see below) sencha.cfg # Workspace configuration file for Sencha Cmd plugin.xml # Workspace-level plugin for Sencha Cmd ext/ # A copy of the Ext JS SDK cmd/ # Framework-specific content for Sencha Cmd sencha.cfg # Framework configuration file for Sencha Cmd packages/ # Framework supplied packages ext-theme-classic/ # Ext JS Theme Package for Classic ext-theme-neptune/ # Ext JS Theme Package for Neptune ... # Other theme and locale packages src/ # The Ext JS source ext-*.js # Pre-compiled and bootstrap files ... index.html # The entry point to your application app.json # Application configuration app.js # Your application's initialization logic app/ # Your application's source code in MVC structure model/ # Folder for application model classes. store/ # Folder for application stores view/ # Folder for application view classes. Main.js # The initial default View controller/ # Folder for application controllers. Main.js # The initial default Controller packages/ # Sencha Cmd packages build/ # The folder where build output is placed. There is no distinction between workspace and app content in a single-page application. This distinction becomes important for multi-page applications as described in [Multi-page and Mixed Apps](#/guide/command_app_multi). ## Building Your Application All that is required to build your application is to run the following command: sencha app build **Important.** In order to execute this command, the current directory **must** be the top-level folder of your application (in this case, `"/path/to/MyApp"`). This command will build your markup page, JavaScript code, SASS and themes into the `"build"` folder. ## Extending Your Application The `sencha generate` command helps you quickly generate common MVC components such as controllers or models: sencha help generate You should see this: Sencha Cmd v3.1.0.xxx sencha generate This category contains code generators used to generate applications as well as add new classes to the application. Commands * app - Generates a starter application * controller - Generates a Controller for the current application * form - Generates a Form for the current application (Sencha Touch Specific) * model - Generates a Model for the current application * package - Generates a starter package * profile - Generates a Profile for the current application (Sencha Touch Specific) * theme - Generates a theme page for slice operations (Ext JS Specific) * view - Generates a View for the current application (Ext JS Specific) * workspace - Initializes a multi-app workspace **Important.** In order to execute the commands discussed below, the current directory on the console **must** be inside your application (in this case, "/path/to/MyApp"). ### Adding New Models Adding a model to your application is done by making the `"/path/to/MyApp"` your current directory and running Sencha Cmd, like this: cd /path/to/MyApp sencha generate model User id:int,name,email This command adds a model class called `User` with the given 3 fields. ### Adding New Controllers Adding a controller is similar to adding a model: cd /path/to/MyApp sencha generate controller Central There are no other parameters in this case beyond the controller name. ### Adding New Views Adding a view to your application is also similar: cd /path/to/MyApp sencha generate view SomeView There are no other parameters in this case beyond the view name. ## Customizing The Build There are various configuration options available in the `".sencha/app/sencha.cfg"` file. In the case of a single-page application, it is best to ignore the `".sencha/workspace"` folder, which also has a config file. When configuration options cannot accomplish the task, the next level of customization is to extend the generated "build.xml" [Ant](http://ant.apache.org/) script. All that the `sencha app build` command does inside Sencha Cmd itself is some basic validations before calling in to the `"build"` target of this build script. This means the entire build process can be examined, extended and if necessary, even modified. ### The classpath The `sencha app build` command knows where to find the source of your application due to the `app.classpath` configuration value stored in `".sencha/app/sencha.cfg"`. By default, this value is: app.classpath=${app.dir}/app,${app.dir}/app.js Adding directories to this comma-separated list informs the compiler where to find the source code required to build the application. ### Build Properties Many aspects of the build performed by `sencha app build` are controlled by properties. To see the current values of these you can run this command from your app folder: sencha ant .props To provide fine-grained control of your application, many different properties are used. In most cases you can tell where this property comes from by its prefix: * `app.` -- Check the `".sencha/app/sencha.cfg"` file * `build.` -- Check the `".sencha/app/build.properties"` file * `workspace.` -- Check the `".sencha/workspace/sencha.cfg"` file * `framework.` -- Check the `"cmd/sencha.cfg"` file in the Ext JS SDK. * `cmd.` -- Check the Sencha Cmd install folder's `"sencha.cfg"` file. It is not required that these properties be set in these files, but it is the default and following this convention will help you manage these settings. That said, there are times when a Workspace setting may need to be overridden by an application. To do this, the `workspace.foo` property must be set in `".sencha/app/sencha.cfg"` because that is the application-level configuration file. When deviating from the convention, leaving behind a comment would be advised. ### Ant Extension Points The generated `"build.xml"` [Ant](http://ant.apache.org/) script is a minimal Ant script that uses an Ant `import` task to import `".sencha/app/build-impl.xml"`. The `"build.xml"` file is intended to be edited after it is generated. The `"build-impl.xml"` file, however, will be replaced by the `sencha app upgrade` command described below and is best left alone. In addition to the `import` task, `"build.xml"` contains a comment block describing all of the various extension points it provides. These are in the form of optional Ant targets and are typically named after their build process step but with prefixes of `"-before-"` and `"-after-"`. In other words, the `"sass"` build step is wrapped by targets that will be invoked before and after the `"sass"` target named `"-before-sass"` and `"-after-sass"`. To perform additional processing before or after any build step, add an appropriately named target to `"build.xml"`. These targets will be invoked by `sencha app build`. These will also be invoked if you use Ant to directly invoke a particular target. For example, build properties are loaded by the `init` target. This means that they can be overridden by setting them prior to that time (since this follows the Ant convention of first-write-wins). The most common place to do this is in the "-before-init" target of the application's `"build.xml"`: **Note.** Because `sencha app build` simply invokes the `"build"` target of the Ant `"build.xml"` file, you can equivalently invoke a build directly from Ant. This can be useful in IDE's like Eclipse and NetBeans for invoking your builds but also in a Continuous Integration server that understands Ant (which is just about all of them). ## Upgrading Your Application Generate applications include two basic kinds of content relevant to Sencha Cmd: build scripts and the important content of the used Sencha SDK's. As such, you will occasionally need to upgrade these pieces. You can do this with the `sencha app upgrade` command. ### Preparing to Upgrade When performing any bulk operation on your application source code, it is highly advisable to start with a "clean" state with respect to version control. That is, it is best to have no uncommitted changes before performing the upgrade. This way, you can easily review and possibly discard changes made by `sencha app upgrade` with minimum trouble. ### Upgrading Just The Sencha Cmd Scaffold To bring up a new version of Sencha Cmd with your application produced by a previous version, you can run this command from inside your application: sencha app upgrade --noframework This will replace the content of `".sencha"` but will also regenerate `"app.js"` to pick up changes there. As well as a handful of other files. ### Upgrading Frameworks Since generated applications include their own copies of the SDK from which they were originally generated, applications need to be updated to use a new version of the SDK. The `sencha app upgrade` command will replace the old SDK copy with the new one: sencha app upgrade ../downloads/ext-4.2.0 The above command points to the path to a downloaded and extracted SDK. **Important.** Do not use the `-sdk` switch for this command as you would for the `sencha generate app` command. Instead use the command shown above. ### Dealing With Merge Conflicts In Sencha Cmd v3.1, the code generator incorporates a 3-way merge to best reconcile the code it generates with the code it generated last time and the current state of the code as you may have edited it. This approach allows you to edit files (like `"spp.js"`) in many ways so long as your changes don't overlap those that Sencha Cmd wants to make. The merge process follows this pseudo-code for `"app.js"` (as an example): mv app.js app.js.$old regenerate last version to app.js.$base generate new version to app.js diff3 app.js.$base app.js.$old app.js In the ideal scenario, you won't notice this mechanism at work. There are situations, however, in which you may receive an error message telling you there was a "Merge conflict" and that you need to resolve this manually. In cases where the base version cannot be recreated, the `".$old"` file is left on disk and you can compare it to the current version. Or you can use your source control system to compare the current file to what was last committed. When the base version could be produced (the majority case), the `".$old"` file is deleted because the conflicts are annotated in the target file in the standard way: <<<<<<< Generated // stuff that Sencha Cmd thinks belongs here ======= // stuff that you have changed which conflicts >>>>>>> Custom ### Alternative Strategies If you have heavily customized your application, it is sometimes simpler to just generate a new application in a temporary location and start by copying its `".sencha"` folder to replace your own. If you are using a workspace, you may need to copy the `".sencha/workspace"` folder from the generated app to your workspace's `".sencha"` folder to replace the old version there. `NOTE`: be careful to preserve any edits to `"sencha.cfg"` files you may still need.