View Full Version : Is there any good tutorial talking about how to create an user extension

9 Jan 2014, 9:08 AM
Hi Everyone,

Just wondering if there is any good tutorial about how to create an user extension for Sencha Architect? I found the blog post is useful but it's not completed (still waiting for part 2.) Could anyone please advice?



9 Jan 2014, 10:07 AM

Creating a User Extension

User Extensions are user interface components that are developed outside of an Architect project. In earlier releases of Sencha Architect, components could be included as Resources in an Architect project but they were static, did not display in the Canvas, and could not be used and manipulated like the components that are included in Architect.
Beginning with Sencha Architect 3.0, properly packaged User Extensions can be integrated into an Architect project. Full interactivity with components is not supported; you cannot click on and manipulate elements as if they are active within an application, but the components can be dragged to and displayed in the Canvas and you can set configs for the components in the Config Panel.
An individual class/component can be easily exported to a file (http://docs-origin.sencha.com/architect/3/#!/guide/classes-section-export-a-component-to-a-file) and saved to the toolbox (http://docs-origin.sencha.com/architect/3/#!/guide/classes-section-saving-a-component-to-the-toolbox); these are easier ways to share and reuse a class/component. A User Extension package (.aux file) is appropriate when one or more of the following are true:

You need to share more than just a class/override, such as when you want to expose new or special configs, or automatically create "sub" or "related" components.
It is important that people who import this code can render the functionality in the Canvas and/or have it work well when they preview (http://docs-origin.sencha.com/architect/3/#!/guide/packaging-section-previewing-an-app) an app.
You want to share and reuse components that do more than the built-in components for a framework can do. For example, the DragDrop (https://market.sencha.com/extensions/dragdrop) User Extension provides functionality that is not readily available with the standard components.
The steps to creating an Architect User Extension are:

Use Sencha Cmd to generate the User Extension (UE) package.
Create the JavaScript files (one for each class) to use in the Extension. You can use either the Ext JS or Sencha Touch framework and can create them using Architect or the framework tools.
Add the JavaScript files to the src folder in the UE package.
Add an architect directory to the root directory of your UE package and create a JSON definition file for each class defined in your User Extension; put these definition files in the architect directory.
Add any CSS files that are specific to your UE to the resources/css directory.
Populate the package.json file with information about your UE.
Package your User Extension.
Test your User Extension package.
Each of these steps are discussed in detail below. If you want to see examples of any files discussed here, you can download and install any of the Sencha User Extensions that are available on the Sencha Market (http://market.sencha.com/) and view the source.
Create the Extension Package

If you do not already have a Sencha Cmd workspace set up, choose the directory you want to use as your workspace and type the following:

sencha generate workspace /path/to/directoryTo create a package, navigate to the workspace and type the following, replacing “FooExtension” with the name of your Extension:

sencha generate package-type code FooExtensionThis creates a packages folder in your workspace if one does not already exist, with a directory under packages named for your package (e.g. “FooExtension”)
Sencha Cmd does most of the work but you must create a few directories on your own and add some data. The format of an Extension package is shown inUser Extension Structure (http://docs-origin.sencha.com/architect/3/#!/guide/file_struct-section-user-extension-structure).
Add .js and CSS Files

Populate the Extension package by copying the .js files for all the classes into the src directory. Most User Extensions only contain one or two classes but you can include a virtually unlimited number of classes.
Add any CSS files that are specific to your Extension to the resources/css directory.
Create Definition Files for all Classes

Each class in the User Extension package must have a JSON definition file in order to be utilized via the toolbox in Architect. Definition files are located in the architect directory that you created earlier in the root directory of your package tree. The definitions define the characteristics and behaviors of a User Extension as it is integrated into the Sencha Architect infrastructure. They may be extremely simple files that simply give the item a name in the toolbox and correspond to a class, but more complex behavior is also possible.
See User Extension Structure (http://docs-origin.sencha.com/architect/3/#!/guide/file_struct-section-user-extension-structure) for detailed information about the definitions files and the fields that must be populated.
Populate the package.json File

The sencha generate command sets up a skeletal package.json file. You must manually edit the file to provide additional information about your Extension. See User Extension Structure (http://docs-origin.sencha.com/architect/3/#!/guide/file_struct-section-user-extension-structure) for detailed information about the package.json file and the fields that must be populated.
Create the Readme.md File

Every User Extension package should include a Readme.md File with the following information:

Description of the package and its components.
Specify the ownership of the UE and any relevant licensing information.
Any known issues with the package.
When you update the package, describe what is new in this Version of the package and any compatibility issues.
Test Your User Extension Package

To test your User Extension package, follow these steps:

install it on your test system by copying it into the directory specified in your Architect settings for Extension storage, into a versioned folder. For example: C:\Users\YOURNAME\Documents\Architect\Extensions\MyExtension\1.0\
open an Architect project that uses a framework you've marked your extension compatible with, and use your User Extension in the project.
Specific items to test include:

Verify that your definitions are properly loaded and that it shows up in the Toolbox under "Extensions".
Add each component from the User Extension into a project and Save/Build the project. Verify that all JavaScript and CSS files are properly referenced in a previewed version of the application.
Modify values of any configs that are available for the components and verify that the new values are implemented.
Try setting config values to invalid values and ensure that the error is handled appropriately.
Export the project to an archive and/or check it into Source Code Management. Then download this project to another system and ensure that all components are included and available.
Package Your User Extension Package

To package a user extension from Architect:

Simply right click the extension name and choose "Package Extension"
Choose a file and path to save the extension
The resulting .aux file can now be shared with other users of Architect!
To package your User Extension manually (not recommended):

Zip up all the files in your package, from the directory that contains package.json (do not zip from a directory above the extension - when unzipping the extension, its contents must be decompressed at the working directory level)
Rename the .zip file to have a .aux extension.
When packaging a new version of your User Extension:

Increment the value of the version field in your package.json file. Architect compares version numbers upon installation, and missing this step will result in users being unable to install your newly updated extension.

Source: http://docs-origin.sencha.com/architect/3/#!/guide/ux_extend


9 Jan 2014, 10:31 AM
Edited as I was being 'special'. (:|

As an example download this user extension: https://market.sencha.com/extensions/login-panel

Then just rename it to .zip and have a look inside :)

A package.json file would look like this:

"name": "LoginPanel",
"type": "code",
"creator": "anonymous",
"summary": "Login Panel Extension",
"detailedDescription": "This extension allows easy creation of a commonly used login panel widget",
"version": "1.0.1",
"compatVersion": "1.0.0",
"format": "1",
"architect": {
"compatFrameworks": [
"classes": [{
"className": "sencha.login.LoginPanel",
"definition": "LoginPanel.js",
"js": [
"css": [
"local": true,
"requires": []

9 Jan 2014, 3:39 PM
Hi Paul,

First of all, welcome and congrats on being the first poster to our new forum!We're actually going to be releasing a new blog post soon that runs through the creation of an AUX file, based on an existing user extension made for ExtJS. However, you've already found some of our documentation which is great!

We're definitely interested in hearing your feedback on creating extensions and getting a better understanding of what aspects of it are good, what aspects are difficult, etc. We imagine as more users have bigger and bigger ideas, we may find there are some limitations that need to be addressed, so we welcome your input.

Take care,

30 Jan 2014, 9:22 AM
For the sake of any users coming across this thread who would like more in the way of tutorials, part 2 of our blog on creating user extensions was finally released a few days ago!


24 Feb 2014, 6:01 PM
Hacking my way through creating my first user extension and have a couple of questions --Is there a way to have the user extension automatically add an entry to the Resources panel? I'm trying to build an aux-packaged extension for TinyMCE, and there's a resource that needs to be loaded.Also, running into an odd bug where after I drag my widget into the design canvas, the CSS styles get blown up. The log entry reads: "Framework Error: tinymce is not defined" even though I have the script that creates the tinymce variable manually configured to load as a "JS Resource" in architect.Any ideas?

I should note that the app does actually work when run through a browser. Really, the only major issue that I seem to be having is the blowing up of the styles in the design canvas.

2 Mar 2014, 12:19 PM
I swear I replied to you about this once already, but I'm back on the forums looking for people who need responses and I'm not seeing mine, so maybe you posted this same message in two places, or maybe my message didn't actually go through?

Anyway, if tinymce.js is a requirement of your class, you'd just declare that in the package.json -- something like:

"classes": [{
"definition": "YourDefinition.js",
"className": "Ext.ux.YourClassName",
"js": [

"css": [

Now, when you drag your class out in Architect, it'll first load the tinymce javascript (and I've put an example here of loading tinymce's CSS also)...

When you add tinymce as a JS resource, it doesn't actually run in the canvas, which is why you'd want to do it the way I'm describing above.

2 Mar 2014, 1:26 PM
Right, but when I do as you described, the only change that I see is to the app.js file, which now contains:


Which isn't really going to do much for me. Note the the tinymce.js file is not an Ext JS class. It's simply an external script (similar to if you wanted to load Google Maps). What I'm really looking for (I think) is something similar to what occurs when you drag a Google Map view into a Touch project and the Google Maps script automatically appears as a resource. Or is there a better method for dealing with a non Ext JS script dependency?

2 Mar 2014, 2:13 PM
yeah, I've used tinymce before (though not in an extjs project) - the loader.setPath thing is an issue we need to address/fix actually - we should only generating that line for last file in the list. However, I think the project may still work with it even though it's extraneous... does it?

2 Mar 2014, 4:44 PM
No, it doesn't work -- because no code actually gets inserted to load the tinymce.js file.I'll be happy to upload it to Git for you to take a look at, if you're interested.

2 Mar 2014, 4:59 PM
Gotcha, I think as a short term solution you could probably get away with leaving it as a javascript resource _and_ using the requires in the way I describe. If you wouldn't mind sharing your project with me that'd be great - if you prefer not to have it publicly accessible you can just email it to us too.