Creating Cmd Packages
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.
Sencha Cmd includes the Sencha Package Manager. Packages have many uses even if you do not intend to distribute the packages you create. This guide covers to process of creating your own packages as well as distributing them. For information on using packages please refer to Sencha Cmd Packages.
Before we can generate a new package, we must first create a home for it: a Workspace. For this example we will use Ext JS for this package, so we start with this command:
sencha -sdk /path/to/ext-n.n.n generate workspace /path/to/workspace
Now we navigate to the new workspace and generate the package:
cd /path/to/workspace
sencha generate package foo
The above steps produce a starter package that contains many commonly used pieces.
You can delete many of these but it is important to keep the ".sencha" folder intact.
The structure of a package generated by sencha generate package is as follows:
packages/
local/
foo/ # Top-level folder for the package
.sencha/
package/
sencha.cfg # Sencha Cmd configuration for this package
build-impl.xml # Generated build script for package
plugin.xml # Sencha Cmd plugin for this package
codegen.json # Data to support 3-way merge in code generator
classic/ # Classic toolkit-specific src code
examples/ # Example applications demonstrating the package
licenses/ # License agreement
modern/ # Modern toolkit-specific src code
overrides/ # Folder for automatically activated overrides
resources/ # Static resources (typically has images folder)
sass/ # Container for styling code
etc/ # General, non-component oriented styling
example/ # - internal use
src/ # Style rules named by component
var/ # Variables and mixins named by component
src/ # Folder for normal JavaScript code
build.xml # Build script (called by `sencha package build`)
package.json # Package descriptor
Readme.md # High-level information about this package
While the above is quite extensive, the only parts that are required to be a package are
"package.json" and ".sencha/package/sencha.cfg".
The "package.json" file contains a description of the package. An example of this from
the "theme-neptune" package:
{
"name": "theme-neptune",
"type": "theme",
"creator": "Sencha",
"summary": "Ext JS Neptune Theme",
"detailedDescription": "The Neptune Theme provides a clean, modern style for Ext JS",
"version": "n.n.n",
"compatVersion": "n.n.n",
"format": "1",
"extend": "theme-neutral"
}
The creator property is something you need to set as a package author. There is no
verification of this text, but it must match the name you assign to your local package
repository discussed later.
The purpose of most packages is to (eventually) become integrated in an application. To
accomplish this, Sencha Cmd incorporates the various pieces of each required package in
to an application during the sencha app build process.
Precisely how this takes place depends on the type of the package.
Different types of packages play different roles. Sencha Cmd understands the following types of packages:
code - An arbitrary package of code for use by applications or other packages.
These packages are general purpose and are included when there is a require statement
that selects them.theme - A package to be used as an application's theme. Themes are special in that
only one package of type theme is allowed to be "active" in a build. This theme is
selected by the theme property in app.json. Themes can also use extend to inherit
styling and resources from another theme package.locale - This package type is deprecated in favor of a standard code package
that includes theme.name in its classpath. See the Ext JS locale package for an
example.The "src" folder is the place for classes such as custom components or other useful
code. This code is automatically included in the classpath for applications or other
packages to require and use.
This is where you would likely put most of your JavaScript code. Classes placed in this folder should follow the Compiler-Friendly Code Guidelines.
The "sass" folder contains three sub-folders designed to handle different aspects of
style compilation.
"sass/etc" - Code that does not relate directly to JavaScript classes"sass/var" - Variable definitions (mirroring JavaScript class hierarchy)"sass/src" - Mixins and rules (mirroring JavaScript class hierarchy)The folders and files in "sass/var" and "sass/src" are organized such that they are
mirror images of the JavaScript classes to which they apply. This correspondence allows
Sencha Cmd to include the files needed by the application. Files in these folders that
do not conform to this will never be included since the process proceeds by mapping the
JavaScript class hierarchy to the file system and not be scanning these folders.
The name correspondence is driven by the namespace property in "package.json":
{
"name": "MyPkg",
...
"sass": {
"namespace": "MyPkg",
...
}
The namespace comes into play when mapping a class name for a required JavaScript class
to the appropriate .scss files. For example, given the class MyPkg.foo.Bar and the
namespace above, Sencha Cmd removes "MyPkg." and looks for a relative path of
"foo/Bar.js" in the "sass/var" and "sass/src" folders.
Note: Even though Fashion is not an implementation of Sass, the "sass" configuration name is preserved for compatibility sake.
The "resources" folder is where you place static resources needed by the package. When
applications consume the package, they will copy these resources into a sub-folder of their
own "resources" folder named by the package name. In this case, "resources/foo". The
relative paths used in CSS files will be automatically corrected if you use the provided
theme-background-image method.
The "overrides" folder is specifically intended for your package to provide mandatory
overrides, hence its name. This mechanism should be used cautiously because all code you
place in this folder will be automatically required in to any application that uses this
package.
The Ext JS Neptune Theme uses this mechanism to change certain default config properties on various components. Locale packages use this to inject their own text on to the prototypes of various components or to provide locale-specific logic for things such as date formatting.
Packages have a version property that describes its current version number. In
addition the current version (in the version property), packages can also indicate the
degree to which they are backward compatible using the compatVersion property.
These versions are used when resolving package requirements. Each release of a package should have an updated version number. The meaning assigned to version numbers by Sencha may help you:
x.y.z.b
x = Major release number (large, impacting changes and features)
y = Minor release number (new functionality but few if any breaking changes)
z = Patch release number (bug fix / maintenance release - goal of 100% compatible)
b = Build number (assigned by build system)
The version property is typically the easiest to maintain. The compatVersion, however,
is an intentional statement about the degree to which users should be able to transparently
upgrade and not require code changes.
Packages can require other packages in the same way that applications can require packages.
To do this, you add to the requires array:
{
"name": "bar",
"type": "code",
"creator": "anonymous",
"summary": "Short summary",
"detailedDescription": "Long description of package",
"version": "1.0.0",
"compatVersion": "1.0.0",
"format": "1",
"local": true,
"requires": [
'ext-easy-button'
]
}
NOTE: When using version restrictions as a package author, it is important to consider that an application and all of the required packages will have to agree on a common version. If you are too restrictive, this process can fail to find a mutually agreeable version for all of the required packages.
The notion of inheritance for packages is intended exclusively for Themes. These are most important ways in which the inherited package contents are rolled into the derived package:
"resources" folders of inherited packages is copied in to the "resources"
folder in the "build" output folder.overrides of base packages are automatically included in the build output of
the derived package.To publish the package, you will need to build it using:
sencha package build
This produces a "build" folder inside the package. This is needed by applications when
they are running in "dev mode" (without being compiled).
It also produces "foo.pkg" file in your workspace's "build" folder. This file is not
placed in the package's "build" folder because:
The "foo.pkg" file is used to add the package to your local repository. See below.
You'll need to manually add a package.framework designation to your "package.json" file.
"framework": "ext"
You'll need to manually add a package.theme designation to your "package.json" file.
The value will be the name of the theme package to use for generated CSS.
"theme": "theme-triton"
The local repository was introduced in Sencha Cmd Packages, but there is more to know about it when you want distribute the packages you have created.
The local repository generated by Sencha Cmd looks like this:
.sencha/
repo/
sencha.cfg # Sencha Cmd configuration for the repo
plugin.xml # Plugin for repository hooks
private-key.json # Private key for repo
remotes/ # Storage for remote repositories
remoteName/ # Name given at `sencha repo add`
catalog.json # Last catalog from this remote
trust/ # Unused in this release
<somename>.cert.json # Copy of `cert.json` (a public key)
pkgs/
catalog.json # Catalog of all packages in this repo
cert.json # Public key for this repo
Foo/
catalog.json # Catalog for all versions of Foo package
cert.json # Public key for creator of Foo package
1.0/ # Folder containing version 1.0
Foo.pkg # Zip file of package
package.json # Extracted package descriptor
1.1/
...
Bar/
...
When Sencha Cmd generates the default local repository, it does not require you to provide any kind of identity. This is fine for its role as a cache, but as a package author you need to put your name on the packages you publish. Before you can publish packages you need to initialize your local repository with an identity:
sencha package repo init -name "My Company" -email "[email protected]"
After this step, your name and email address will be recorded in the local repository along with a new public/private key pair.
NOTE: The name argument must match the value of the creator property you set in
the "package.json".
Your name, email and public key are stored in the "pkgs/cert.json" file. This file will
be automatically added to the packages you create to identify you as the package author.
Obviously given its name, your private key is not intended to be shared with others. It
is stored in your local repository in ".sencha/repo/private-key.json".
You might want to back up these two files as they will serve more important roles in future releases.
The "pkgs" folder is where all the packages are stored. These may be packages you have
created or packages that you have downloaded.
When you add package ".pkg" files, these will be copied in to the "pkgs" folder tree.
The ".sencha/repo/plugin.xml" file is an Ant script that you
can use to provide "hooks" into repository actions such as sencha package add. For more
details on this, refer to the comments in the generated file.
Once you have the ".pkg" file from the build, and assuming that the name you have set
as your identity on your local repository matches the creator property defined in your
"package.json", you can run this command:
sencha package add foo.pkg
Sencha Cmd will produce a hash of the ".pkg" file using your private key and add it to
the ".pkg" file you specify and it will then copy that file to the local repository.
Now that the package reside in the repository, other developers can require it if they
have added your repository as a remote.
The process to request that Sencha add your ".pkg" to the Sencha Package Repository is
still being finalized, but you can check Sencha Market for
updates on this.
The structure of the "pkgs" folder is the structure expected for a remote repository. All
that is required for others to require the packages you create is for them to add a
remote repository:
sencha package repo add my-company http://my.company.com/packages
That is, assuming you have hosted your "pkgs" folder content at the above HTTP URL. There
is nothing required of that hosting beyond HTTP GET access so a static file server or CDN
will work.
Cmd | Terms of Use