Using Sencha Cmd with Ext JS 6

This guide walks through the process of using Sencha Cmd with Ext JS 6 applications starting with the sencha generate app command and ending with a running application.

The process for upgrading an existing (non-Sencha Cmd) application to conform to the expectations of Sencha Cmd is covered at the end of this guide. It is important to first understand the “ideal” or “default” structure as a point of comparison. The differences between this default structure and the structure of an existing application are what drive the upgrade process for existing applications.

Prerequisites

The following guides are recommended reading before proceeding further:

• Introduction to Sencha Cmd

Generating Your Application

Our starting point is to generate an application skeleton. This is done using the following command:

sencha -sdk /path/to/ext6 generate app MyApp /path/to/my-app

To use the Trial edition, you can automatically download it at the same time using this command:

sencha generate app -ext MyApp /path/to/my-app

If you have purchased the Commercial edition, you will need to download the Ext JS ZIP archive and use the first command shown.

The application files generated by either of the above commands will have the following structure:

.sencha/                        # Sencha-specific files (primarily configuration)
    app/                        # Application-specific content
        sencha.cfg              # Application configuration file for Sencha Cmd
        Boot.js                 # Private, low-level dynamic loader for JS and CSS
        Microloader.js          # Loads app based on app.json content
        build-impl.xml          # Standard application build script
        *-impl.xml              # Implementations of various build phases
        defaults.properties     # Default values and docs for build properties
        ext.properties          # Build property values specific to Ext JS
        *.defaults.properties   # Build properties by environment (e.g. "testing")
        plugin.xml              # Application-level plugin for Sencha Cmd
        codegen.json            # Data for merging generated code during upgrade
    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
    classic/                    # Packages related to the Classic Toolkit
        classic/                # Ext JS Classic Toolkit package
        theme-neptune/          # Classic Toolkit Theme Package for Neptune
        theme-triton/           # Classic Toolkit Theme Package for Triton
        ...
    modern/                     # Packages related to the Modern Toolkit
        modern/                 # Ext JS Modern Toolkit package
        theme-neptune/          # Modern Toolkit Theme Package for Neptune
        theme-triton/           # Modern Toolkit Theme Package for Triton
        ...
    packages/                   # Framework supplied packages
        charts/                 # Charts package
        ux/                     # Contents of "Ext.ux" namespace
    ...

index.html                      # The entry point to your application
app.json                        # Application manifest
app.js                          # Launches the Application class
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/                   # Folder for the classes implementing the Main View
            Main.js             # The Main View
            MainModel.js        # The `Ext.app.ViewModel` for the Main View
            MainController.js   # The `Ext.app.ViewController` for the Main View
    Application.js              # The `Ext.app.Application` class

packages/                       # Sencha Cmd packages
workspace.json                  # Workspace JSON descriptor

build/                          # The folder where build output is placed

There is no distinction between Workspace and app content in a single-page application. To learn about Workspaces, see Workspaces in Sencha Cmd.

Building Your Application

All that is required to build your application is to run the following command:

sencha app build

This command builds your markup page, JavaScript code and themes into the "build" folder.

Important. In order to execute this command, the current directory must be the top-level folder of your application (in this case, "/path/to/my-app").

Important Do NOT specify the -sdk parameter for sencha app commands. Because these commands must be run from the application’s root folder, Sencha Cmd knows which SDK to use. Using -sdk on these commands causes Sencha Cmd to believe your current directory is the SDK specified, which is not the proper current directory for an application.

Development Mode

Sencha Cmd generates what is called a “bootstrap” based on your "app.json" file and the source code in your application. The bootstrap passes this information on to the dynamic class loader (Ext.Loader and the Microloader) so you don’t have to maintain this manually.

The bootstrap is not effected by changes to your JavaScript source code, so the normal workflow of “edit, save, reload, repeat” works as expected. Occasionally changes to styling or movement and renaming of JavaScript code will invalidate this bootstrap information or the generated CSS needed to run your application.

There are two basic approaches to updating the bootstrap.

sencha app watch

The simplest way to keep your application runnable in the browser is to run app watch:

sencha app watch

This command will start by performing a “development build” (see below) but instead of dropping back to the command prompt, app watch waits and watches for changes to any of the files it just built.

Watch also starts the internal Sencha Cmd web server to serve files from your workspace via “http:”. This web server uses default port 1841.

To access the Sencha Cmd web server, use:

http://localhost:1841/

Watch runs until stopped with Ctrl+C.

Using app watch, you can also enable Fashion and use Live Update to keep your CSS up to date as it changes.

Development Builds and Refresh

If you want to update the bootstrap and CSS manually, there are two commands to use:

sencha app build development
sencha app refresh

The app refresh command only updates the JavaScript portion of the bootstrap. This is the fastest update to run and is all that is needed when changing locations of classes due to renames or other movement of code.

The app build development command will perform a refresh but will also compile your styling to generate a fresh CSS file.

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 vX.Y.Z.nnn
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”).

Generating 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.

Note. This is the only generate command that is compatible with a Sencha Architect project. The typical use of this command is to automate or script the creation of data models in Sencha Architect.

Generating Views

Adding a view to your application is similar:

cd /path/to/MyApp
sencha generate view foo.Thing

The above will generate the following files:

app/
    view/
        foo/                    # Folder for the classes implementing the new view
            Thing.js            # The new view
            ThingModel.js       # The `Ext.app.ViewModel` for the new view
            ThingController.js  # The `Ext.app.ViewController` for the new view

There are no required parameters in this case beyond the view name. You can, however, add a base class if desired:

cd /path/to/MyApp
sencha generate view -base Ext.tab.Panel foo.Thing

This will change the extend used by the view class to use Ext.tab.Panel.

Note. This command is not compatible with a Sencha Architect project.

Generating Controllers

In Ext JS 5+, each view generated by Sencha Cmd has a default Ext.app.ViewController, so it is not necessary to generate global controllers based on Ext.app.Controller in most cases. If you need a new controller, you can generate one in the same basic way as with Models and Views:

cd /path/to/MyApp
sencha generate controller Central

There are no other parameters in this case beyond the controller name.

Note. This command is not compatible with a Sencha Architect project.

Customizing The Build

The first place to look when you need to customize the build is "app.json". This file contains many options and associated documented. There is also the "workspace.json" file that contains additional settings.

Going Further

Going beyond the ".json" files is not recommended but may be needed in some cases. If you need to modify files in the ".sencha" folders of the application or workspace, you may end up with an unsupported configuration. In previous releases the ".sencha/app/*.properties" files, the ".sencha/app/sencha.cfg" file and the ".sencha/workspace/sencha.cfg" file were occasionally modified. With Sencha Cmd 6, this practice should be avoided.

Sencha Support may elect to close tickets if a problem cannot be reproduced by only modifying the JSON descriptors. If there are tasks you cannot accomplish in the JSON files, please file a Feature Request on our forum or in the Support Portal.

The classpath

The sencha app build command knows where to find the source of your application due to the classpath property stored in "app.json". By default, this value is:

"classpath": [
    "app",
    "${toolkit.name}/src"
],

Adding directories to this array informs the compiler where to find the source code required to build the application.

Further Reading

To learn more about the build process provided by Sencha Cmd, please refer to Inside The App Build Process.

Upgrading Your Application

Generated applications include two basic kinds of content relevant to Sencha Cmd: build scripts (or scaffolding) 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 following command:

sencha app upgrade [ path-to-new-framework ]

The “path-to-new-framework” is optional and is used to upgrade both the Sencha Cmd scaffold and the framework used by the application.

See Understand App Upgrade for more details.

Porting Application to Sencha Cmd

The key pieces of scaffold produced by Sencha Cmd are these:

.sencha/
app.json
build.xml
index.html

The first three of these can be simply copied from an application generated to a temp folder. An existing application will typically have some markup entry page and if this is not "index.html", you can add the following to your "app.json":

{
    ...

    "indexHtmlPath": "index.php"
}

Naturally, the value should be whatever is correct for the application. In order for the generated build script to understand this markup file, however, the file should contain the standard boilerplate found in the generated "index.html":

<script id="microloader" type="text/javascript" src="bootstrap.js"></script>

In development mode, this loads a file generated by Sencha Cmd during sencha app build or sencha app refresh. The sencha app build command is a complete build which includes as one step the “refresh” operation.

Configuration

There are probably several pieces of an existing application that will not match with the default structure of a Sencha Cmd application. At this point, there are two paths to consider:

• Restructure the application to conform to the generated structure
• Configure the build process to match the application structure

For details on how to configuring the build process, consult Inside The App Build Process.

Alternatives

If an existing application cannot be made to conform with the expectations of the build script (either by restructuring the app or configuring the build), Sencha Cmd still has useful functionality accessible via low-level commands.

For lower-level details, see

• Sencha Compiler Reference
• Ant Integration

Next Steps

• Workspaces in Sencha Cmd
• Inside The App Build Process