{@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.
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. For details on developing
more complex, multipage Ext JS applications, refer to
Multi-Page and Mixed Apps.
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.
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.
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 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 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 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.
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 script. All that thesencha 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 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.
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" 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
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, theworkspace.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.
The generated "build.xml" Ant 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":
<target name="-before-init">
<property name="foo" value="42"/>
</target>
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).
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.
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.
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.
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 thesencha 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
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
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.