Using Cmd with Ext JS 6
Many classes have shortcut names used when creating (instantiating) a class with a
configuration object. The shortcut name is referred to as an alias (or xtype if the
class extends Ext.Component). The alias/xtype is listed next to the class name of
applicable classes for quick reference.
Framework classes or their members may be specified as private or protected. Else,
the class / member is public. Public, protected, and private are access
descriptors used to convey how and when the class or class member should be used.
Public classes and class members are available for use by any other class or application code and may be relied upon as a stable and persistent within major product versions. Public classes and members may safely be extended via a subclass.
Protected class members are stable public members intended to be used by the
owning class or its subclasses. Protected members may safely be extended via a subclass.
Private classes and class members are used internally by the framework and are not intended to be used by application developers. Private classes and members may change or be omitted from the framework at any time without notice and should not be relied upon in application logic.
static label next to the
method name. *See Static below.Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).
Let's look at each part of the member row:
lookupComponent in this example)( item ) in this example)Ext.Component in this case). This may be omitted for methods that do not
return anything other than undefined or may display as multiple possible values
separated by a forward slash / signifying that what is returned may depend on the
results of the method call (i.e. a method may return a Component if a get method calls is
successful or false if unsuccessful which would be displayed as
Ext.Component/Boolean).PROTECTED in
this example - see the Flags section below)Ext.container.Container in this example). The source
class will be displayed as a blue link if the member originates from the current class
and gray if it is inherited from an ancestor or mixed-in class.view source in the example)item : Object in the example).undefined a "Returns" section
will note the type of class or object returned and a description (Ext.Component in the
example)Available since 3.4.0 - not pictured in
the example) just after the member descriptionDefaults to: false)The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.
classInstance.method1().method2().etc();false is returned from
an event handler- Indicates a framework class
- A singleton framework class. *See the singleton flag for more information
- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)
- Indicates that the class, member, or guide is new in the currently viewed version
- Indicates a class member of type config
- Indicates a class member of type property
- Indicates a class member of type
method
- Indicates a class member of type event
- Indicates a class member of type
theme variable
- Indicates a class member of type
theme mixin
- Indicates that the class, member, or guide is new in the currently viewed version
Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.
Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.
Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.
Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.
If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.
Both API docs and guides can be searched for using the search field at the top of the page.
On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level, inheritance, and read only. This is done using the checkboxes at the top of the page.
The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.
Clicking on an empty search field will show your last 10 searches for quick navigation.
Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:
Ext.button.Button class has an alternate class name of Ext.Button). Alternate class
names are commonly maintained for backward compatibility.Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.
Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.
Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:
The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.
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.
The following guides are recommended reading before proceeding further:
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.
Note: The above instructions will generate a Universal application. This means that both classic and modern toolkits individual "view" folders with a central shared core. To create a single-toolkit application, simply append the toolkit name to your generate command.
sencha -sdk /path/to/ext generate app classic MyApp /path/to/MyApp
sencha -sdk /path/to/ext generate app modern MyApp /path/to/MyApp
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.
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.
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.
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.
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").
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.
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.
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.
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 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 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.
To learn more about the build process provided by Sencha Cmd, please refer to Inside The App Build Process.
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.
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.
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:
For details on how to configuring the build process, consult Inside The App Build Process.
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
Cmd | Terms of Use