User Extension Structure
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.
By default, the files for an installed Architect user extension .aux file are located under the
Documents/Architect/Extensions directory named for the extension. You can change this directory by going to
Edit Menu > Architect Settings > Asset Storage section > Extension.
Each version of a user extension has its own subdirectory, named 1.0, 1.1, and so forth.
The files and directories within this directory are named for the version number are as follows:
architect/ # JSON definition files for each of the UX classes
Xx1.Definition.js # Definition file for the Xx1.Definition class
Xx2.Definition.js # Definition file for the Xx2.Definition class
...
build.xml # Generated file that controls how the UX is built
docs/
package.png # Graphic used on Sencha Market for this UX
screenshots/
pict.png # Graphic used for Sencha Market
licenses/ # License agreement for this UX
Readme.md
overrides/ # Contains any overrides that are required
package.json # Describes the user extension package to be built
Readme.md # Description of this UX used on Sencha Market
resources/ # Static resources used in this UX
css/ # CSS resources for this UX
images/ # Files for images used in this UX
sass/ # SASS files used in this UX
config.rb
etc/ # General, non-component oriented SASS
example/
Readme.md # Information about this SASS
etc/ # SASS files that must be used explicitly
src/ # SASS sources that mimic the component-class hierarchy
# These files are gathered in a build of the CSS
# based on classes used by the build.
var/ # Contains variable declaration files named by component class
src/ # Javascript source files for each extension class
xxxx.js
yyyy.js
Most of these files are generated automatically. However, you must manually populate the information in the
package.json file and create and populate a definitions file for each class/component in the user extension.
The following guide provides full reference information for these two files along with instructions and guidelines for setup:
The package.json file defines how the user extension package is assembled, specifying the version number of this package,
the framework versions with which it can be used, and all the files that are required to create the package.
The sencha generate command sets up a skeletal package.json file:
{
"name": "DreidelExtension",
"type": "code",
"creator": "anonymous",
"summary": "Short summary",
"detailedDescription": "Long description of package",
"version": "1.0.0",
"compatVersion": "1.0.0",
"format": "1",
"local": true,
"css": [{
path: "resources/css/dreidel.css"
}],
"requires": []
}
You must manually edit the file to provide additional information about your Extension. The fields are defined as:
| Field | Description |
|---|---|
| name | Name of the user extension package. This name is generated from the name provided on the sencha generate line. It determines the name of the directory and should not be changed |
| type | Must be "code". |
| creator | Put your name here if you want to take credit for this user extension. |
| summary | A short summary describing your extension, e.g. Fancy Panel component with extra widget. (Reserved for future use) |
| detailedDescription | A more fully detailed description of your extension. (Reserved for future use) |
| version | Version number of this release of your user extension. This is a version string such as 1.1.2. Sencha Cmd automatically makes this 1.0 when you create a new user extension package; you can change this number to reflect upgrades. |
| compatVersion | Currently unused by Architect. |
| local | Valid values are "local" . |
| css | Array of CSS files to load from the src/css folder, specified as objects, requiring a "path" attribute. |
| requires | An array of classes that must be loaded before any classes in your user extension package are loaded. This is useful in cases where you may have a large library upon which your extension classes are dependent, for example. Without the requires, your component might try to execute before the prerequisite library has completely loaded. |
You must also add an architect section
between the compatVersion and local lines.
Here is a sample from the SchedulerGrid user extension,
which is a rather complicated user extension
that has five classes and some other complexities:
"architect": {
"defsonly": true,
"compatFrameworks": [
"ext42"
],
"requires":[
"sch-all-min.js"
],
"classes": [{
"definition": "ResourceModel.js",
"className": "Sch.model.Resource",
"js": ["ResourceModel.js"]
},{
"definition": "ResourceStore.js",
"className": "Sch.data.ResourceStore",
"js": ["ResourceStore.js"]
},{
"definition": "EventModel.js",
"className": "Sch.model.Event",
"js": ["EventModel.js"]
},{
"definition": "EventStore.js",
"className": "Sch.data.EventStore",
"js": ["EventStore.js"]
},{
"definition": "SchedulerGridPanel.js",
"className": "Ext.ux.SchedulerGrid",
"js": ["SchedulerGridPanel.js"]
}]
},
The fields are defined as:
| Field | Description |
|---|---|
| defsonly | (Optional)
Allows you to specify definitions, but no JavaScript files, for a class.
For example, the Scheduler Grid user extension
has a scheduler-grid-all.js that defines five clases
with a definition for each of those five classes
but they all define things that are already take care of
by the schedulergrid-all.js class. |
| compatFrameworks | Version(s) of the framework with which this user extension works. This is expressed as a string without dots, "ext42". You cannot use more than two digits in this string; if you specify, for example, "ext421", the package does not load. Separate multiple values with commas. |
| requires | (Optional) List any classes that must be loaded before any of the classes in this extension are executed. |
| classes array | Array listing all classes that are a part of the package's custom code. The .js Javascript source file for each class must be included in the src directory and the architect directory must include a Description file for each class. |
| className | Fully qualified Class Name for this class. |
| definition | Name of the Definitions file for this class. The Definitions file must be included in the architect directory. |
| js | Array of filenames in your src folder that correspond to this class; often this is just one file. |
All fields must be included in the file although some may be be empty.
The Definition file defines:
You must create one definition file for each class that is included in your extension. The file must have a .js
extension with a name that includes the class name as well as the "Definitions" or "Def" string.
For example, if your extension is called FancyPants, name the definition file FancyPantsDef.js.
All definition files are located under the architect section of the user extension project directory.
The package.json file identifies the definition file for each class that is included in the extension.
A sample definition file is:
{
classAlias: "plugin.dragdropregion",
className: "Ext.ux.DragDropRegion",
inherits: "abstractplugin",
autoName: "MyDragDropRegion",
validParentTypes:["abstractpanel"],
"toolbox": {
"name": "Drag Drop Region",
"category": "Containers",
"groups": ["Containers","Views"]
},
configs: [{
name: 'drag',
type: 'boolean',
hidden: false,
initialValue: true
},
{
name: 'drop',
type: 'boolean',
hidden: false,
initialValue: true
},
{
name: 'group',
type: 'string',
hidden: false,
initialValue: 'ddg'
},{
name: 'notifyEnterCls',
type: 'string',
hidden: false,
initialValue: 'highlightDropZone'
},
{
name: 'dragLabel',
type: 'string',
hidden: false,
initialValue: 'Untitled Region'
},
{
name: 'frameSwapped',
type: 'boolean',
hidden: false,
initialValue: 'true'
},
{
name: 'frameColor',
type: 'string',
hidden: false,
initialValue: '#99FF99'
},
{
name: 'frameCount',
type: 'number',
hidden: false,
initialValue: 2
}]
}
The tables below describe all these properties.
| Property | Type | Default | Description |
|---|---|---|---|
| className | string | -- | classname of your extension; e.g., Ext.ux.Coverflow;
this must match the contents of the extend line
in the src file for this class.
|
| classAlias | string | -- | alias of your extension; e.g. widget coverflow;
this must match the contents of the alias line
in the src file for this class.
|
| Property | Type | Default | Description |
|---|---|---|---|
| inherits | string | Ext.Base | Class which this class extends. |
| autoName | string | -- | String used to automatically generate a name for this class when it is first included in a project; the name displays in the Project Inspector and Code Editor file. |
| toolbox | object | -- | Object that describes how this component displays in the toolbox; see below |
| configs | array of objects | -- | Array of configuration objects |
| listeners | array of objects | -- | Array of listener objects. A more detailed explanation of available events is given below |
| validParentTypes | array of strings | all parents | Array of valid parent types (use strings corresponding to xtype) for this object; if any types are listed here, this component will only be allowed to be dropped onto components matching one of the types in this list |
| validChildTypes | array of strings | all children | Array of valid child types for this object; if any components are listed here, they are the only types of components that can be children to this component |
| disableInitialView | boolean | false | If true, this component cannot be shown as the user's initial view |
| disableDuplication | boolean | false | If true, this component cannot be duplicated |
| hideConfigs | array of strings | -- | Array of configurations to hide. This is useful when you are inheriting another definition and want to hide some of its configurations. |
| showConfigs | array of strings | all configs | Array of configurations to show. If any configurations are listed here, these are the only ones that will be displayed. If this property is not specified, all configs are displayed in the Config panel. |
The toolbox property is an object that describes this extension’s representation in the toolbox.
| Property | Type | Description |
|---|---|---|
| name | string | User friendly name that is displayed in the Toolbox |
| category | string | category for the extension. Category in which this extension appears in the Toolbox. "Extensions" is always added to this value so that all user extension components appear under the Extensions category; you should also supply an appropriate functional category such as "Container" or "Buttons". To have this class displayed in multiple categories, populate an array similar to that displayed for "groups" in the example. |
| groups | array of strings | array of filter groups. This defines the groups in which this class is listed in the right column of the Toolbar. This can be a group that exists in the Toolbox by default or a new one |
This contains an array of configuration objects that describe the configs supported for this component. Any config
listed here can be set in the Config panel for the component unless the "hidden" property is set to true.
| Property | Type | Default | Description |
|---|---|---|---|
| name | string | -- | Display name to use in the Config panel. |
| type | -- | -- | Type of this config (e.g. boolean, string - see table below) |
| bindable | boolean | false | Enable binding for this config |
| hidden | boolean | false | If set to true the config is not shown to the users |
| initialValue | -- | -- | Value that is automatically set on creation. |
| defaultValue | -- | -- | Default value of the config |
| doc | string | -- | Shows the documentation icon on the config with the defined text |
| editor | string | -- | Editor can be 'options' or 'combo' defined like this:
{
editor: 'options',
options: ['top', 'bottom']
}
|
| alternates | array | -- | Alterante types of the config, for example:
{
name: 'render',
type: 'boolean',
alternates:[{
type: 'object'
}]
}
|
| Type | Description |
|---|---|
| array | allows the user to enter an array literal - this will be editable in the code editor |
| boolean | presents the user a checkbox to store a true/false value. |
| controller | presents the user a list of available controllers |
| date | presents the user with a date picker, accepts only formatted dates as a valid value. |
| function | presents the user the ability to write a function using the code editor
{
name: 'myFunction',
type: 'function',
params: [{
name: 'first'
},{
name: 'second'
}]
}
|
| model | presents the user a list of available models |
| number | similar to ‘string’, but allows only numerical input |
| object | presents the user the ability to write an object literal using the code editor |
| store | presents the user a list of available stores, filtered using the optional storeSelector parameter which usually have these values:
'storeSelector': '' // When you want all types of stores (the empty string is important)
'storeSelector': 'treestore' // When you want store of type treestore
'storeSelector': 'calendar' // When you want calendar store
'storeSelector': ':not(treestore)' // This is default value
|
| string | presents the user a simple text input box |
| template | allows the user to add and edit an XTemplate object as a config |
| typedarray | allows the user to specify that multiple items of a specific type can be added (e.g. multiple models), for example:
{
"name": "typedArrayOfModels",
"type": "typedarray",
"memberConfig": {
"type": "model",
"confirmDelete": false
}
}
|
| uri | similar to a string, with added functionality of automatically url encoding any value set (e.g. converting space characters to %20) |
| view | presents the user a list of available views |
This contains an array of listener names / functions to call when the event is fired.
| Property | Type | Default | Description |
|---|---|---|---|
| name | string | -- | Name of this object |
| fn | string | -- | Function to be called when the event is observed |
Currently the following event listeners are supported:
| Event name | Callback parameters |
|---|---|
| create | -- |
| validate | -- |
| cfgadd | cfg name |
| cfgchange | cfg name, newValue, oldValue |
| cfgchangecheck | cfg name, newValue, oldValue |
Architect | Terms of Use