![\"\"](\"guides/command_app/../command/sencha-command-128.png\")
Contents
\n\n
This guide walks through the process of using Sencha Cmd with Ext JS 4.2 applications\nstarting 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\nsingle-page application you might consider using Sencha Cmd to build an application\nskeleton based on this guide and then migrate your application code to this preferred\nstructure. This will provide you with the maximum leverage from Sencha Cmd. If this option\nis not right for your app, you can still use Sencha Cmd to help with many aspects of your\ndevelopment. For developing single-page applications with a custom folder structure, see\nSingle-Page Ext JS Apps.
\n\nIf you work with applications that have multiple pages, it will be helpful to start by\nlearning about the simple uses of Sencha Cmd described in this and the\nSingle-Page Ext JS Apps guide. For details on developing\nmore complex, multipage Ext JS applications, refer to\nMulti-Page and Mixed Apps.
\n\nOur starting point is to generate an application skeleton. This is done using\nthe following command:
\n\nsencha generate app MyApp /path/to/MyApp\nImportant. The above command must be able to determine the appropriate SDK. This can\nbe satisfied by either executing this command from a folder containing an extracted SDK\ndistribution or by using the -sdk switch like so:
sencha -sdk /path/to/SDK generate app MyApp /path/to/MyApp\nThe application files generated by this command should have the following structure:
\n\n.sencha/ # Sencha-specific files (e.g. configuration)\n app/ # Application-specific content\n sencha.cfg # Application configuration file for Sencha Cmd\n build-impl.xml # Standard application build script\n plugin.xml # Application-level plugin for Sencha Cmd\n workspace/ # Workspace-specific content (see below)\n sencha.cfg # Workspace configuration file for Sencha Cmd\n plugin.xml # Workspace-level plugin for Sencha Cmd\n\next/ # A copy of the Ext JS SDK\n cmd/ # Framework-specific content for Sencha Cmd\n sencha.cfg # Framework configuration file for Sencha Cmd\n packages/ # Framework supplied packages\n ext-theme-classic/ # Ext JS Theme Package for Classic\n ext-theme-neptune/ # Ext JS Theme Package for Neptune\n ... # Other theme and locale packages\n src/ # The Ext JS source\n ext-*.js # Pre-compiled and bootstrap files\n ...\n\nindex.html # The entry point to your application\napp.json # Application configuration\napp.js # Your application's initialization logic\napp/ # Your application's source code in MVC structure\n model/ # Folder for application model classes.\n store/ # Folder for application stores\n view/ # Folder for application view classes.\n Main.js # The initial default View\n controller/ # Folder for application controllers.\n Main.js # The initial default Controller\n\npackages/ # Sencha Cmd packages\n\nbuild/ # The folder where build output is placed.\nThere is no distinction between workspace and app content in a single-page application.\nThis distinction becomes important for multi-page applications as described in\nMulti-page and Mixed Apps.
\n\nAll that is required to build your application is to run the following command:
\n\nsencha app build\nImportant. In order to execute this command, the current directory must be the\ntop-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\"\nfolder.
The sencha generate command helps you quickly generate common MVC components such as\ncontrollers or models:
sencha help generate\nYou should see this:
\n\nSencha Cmd v3.1.0.xxx\nsencha generate\n\nThis category contains code generators used to generate applications as well\nas add new classes to the application.\n\nCommands\n * app - Generates a starter application\n * controller - Generates a Controller for the current application\n * form - Generates a Form for the current application (Sencha Touch Specific)\n * model - Generates a Model for the current application\n * package - Generates a starter package\n * profile - Generates a Profile for the current application (Sencha Touch Specific)\n * theme - Generates a theme page for slice operations (Ext JS Specific)\n * view - Generates a View for the current application (Ext JS Specific)\n * workspace - Initializes a multi-app workspace\nImportant. In order to execute the commands discussed below, the current directory on\nthe console must be inside your application (in this case, \"/path/to/MyApp\").
\n\nAdding a model to your application is done by making the \"/path/to/MyApp\" your current\ndirectory and running Sencha Cmd, like this:
cd /path/to/MyApp\nsencha generate model User id:int,name,email\nThis command adds a model class called User with the given 3 fields.
Adding a controller is similar to adding a model:
\n\ncd /path/to/MyApp\nsencha generate controller Central\nThere are no other parameters in this case beyond the controller name.
\n\nAdding a view to your application is also similar:
\n\ncd /path/to/MyApp\nsencha generate view SomeView\nThere are no other parameters in this case beyond the view name.
\n\nThere are various configuration options available in the \".sencha/app/sencha.cfg\" file. In\nthe case of a single-page application, it is best to ignore the \".sencha/workspace\"\nfolder, which also has a config file.
When configuration options cannot accomplish the task, the next level of customization is\nto extend the generated \"build.xml\" Ant script. All that the\nsencha app build command does inside Sencha Cmd itself is some basic validations before\ncalling in to the \"build\" target of this build script. This means the entire build process\ncan be examined, extended and if necessary, even modified.
The sencha app build command knows where to find the source of your application due to\nthe app.classpath configuration value stored in \".sencha/app/sencha.cfg\". By default,\nthis value is:
app.classpath=${app.dir}/app,${app.dir}/app.js\nAdding directories to this comma-separated list informs the compiler where to find the\nsource code required to build the application.
\n\nMany aspects of the build performed by sencha app build are controlled by properties. To\nsee the current values of these you can run this command from your app folder:
sencha ant .props\nTo provide fine-grained control of your application, many different properties are used. In\nmost cases you can tell where this property comes from by its prefix:
\n\napp. -- Check the \".sencha/app/sencha.cfg\" filebuild. -- Check the \".sencha/app/build.properties\" fileworkspace. -- Check the \".sencha/workspace/sencha.cfg\" fileframework. -- 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\nfollowing this convention will help you manage these settings. That said, there are times\nwhen a Workspace setting may need to be overridden by an application. To do this, the\nworkspace.foo property must be set in \".sencha/app/sencha.cfg\" because that is the\napplication-level configuration file. When deviating from the convention, leaving behind\na comment would be advised.
The generated \"build.xml\" Ant script is a minimal Ant script that\nuses an Ant import task to import \".sencha/app/build-impl.xml\". The \"build.xml\" file\nis intended to be edited after it is generated. The \"build-impl.xml\" file, however, will\nbe 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\nthe various extension points it provides. These are in the form of optional Ant targets and\nare typically named after their build process step but with prefixes of \"-before-\" and\n\"-after-\". In other words, the \"sass\" build step is wrapped by targets that will be invoked\nbefore 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\ntarget to \"build.xml\". These targets will be invoked by sencha app build. These will also\nbe 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\noverridden by setting them prior to that time (since this follows the Ant convention of\nfirst-write-wins). The most common place to do this is in the \"-before-init\" target of the\napplication's \"build.xml\":
<target name=\"-before-init\">\n <property name=\"foo\" value=\"42\"/>\n</target>\nNote. Because sencha app build simply invokes the \"build\" target of the Ant \"build.xml\"\nfile, you can equivalently invoke a build directly from Ant. This can be useful in IDE's\nlike Eclipse and NetBeans for invoking your builds but also in a Continuous Integration\nserver that understands Ant (which is just about all of them).
Generate applications include two basic kinds of content relevant to Sencha Cmd: build\nscripts and the important content of the used Sencha SDK's. As such, you will occasionally\nneed to upgrade these pieces. You can do this with the sencha app upgrade command.
When performing any bulk operation on your application source code, it is highly advisable\nto start with a \"clean\" state with respect to version control. That is, it is best to have\nno uncommitted changes before performing the upgrade. This way, you can easily review and\npossibly discard changes made by sencha app upgrade with minimum trouble.
To bring up a new version of Sencha Cmd with your application produced by a previous\nversion, you can run this command from inside your application:
\n\nsencha app upgrade --noframework\nThis will replace the content of \".sencha\" but will also regenerate \"app.js\" to pick\nup changes there. As well as a handful of other files.
Since generated applications include their own copies of the SDK from which they were\noriginally generated, applications need to be updated to use a new version of the SDK.\nThe sencha app upgrade command will replace the old SDK copy with the new one:
sencha app upgrade ../downloads/ext-4.2.0\nThe above command points to the path to a downloaded and extracted SDK.
\n\nImportant. Do not use the -sdk switch for this command as you would for the\nsencha generate app command. Instead use the command shown above.
In Sencha Cmd v3.1, the code generator incorporates a 3-way merge to best reconcile the\ncode it generates with the code it generated last time and the current state of the code\nas you may have edited it. This approach allows you to edit files (like \"spp.js\") in\nmany 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\nregenerate last version to app.js.$base\ngenerate new version to app.js\ndiff3 app.js.$base app.js.$old app.js\nIn the ideal scenario, you won't notice this mechanism at work. There are situations,\nhowever, in which you may receive an error message telling you there was a \"Merge conflict\"\nand that you need to resolve this manually.
\n\nIn cases where the base version cannot be recreated, the \".$old\" file is left on disk\nand you can compare it to the current version. Or you can use your source control system\nto compare the current file to what was last committed.
When the base version could be produced (the majority case), the \".$old\" file is deleted\nbecause the conflicts are annotated in the target file in the standard way:
<<<<<<< Generated\n // stuff that Sencha Cmd thinks belongs here\n=======\n // stuff that you have changed which conflicts\n>>>>>>> Custom\nIf you have heavily customized your application, it is sometimes simpler to just generate\na new application in a temporary location and start by copying its \".sencha\" folder to\nreplace your own.
If you are using a workspace, you may need to copy the \".sencha/workspace\" folder from\nthe 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.