Creating App Templates and User Extensions
You can create App Templates and User Extensions to share code with others. The contents of both Templates and User Extensions are displayed in the canvas for the project like all other Architect components. This guide gives instructions for creating Custom App Templates and User Extensions; see the Integrating App Templates and User Extensions guide for information about using these facilities in a project.
- App Templates can be created using Sencha Architect; User Extensions are usually created outside Sencha Architect.
- App Templates can only be used when creating a new project; you cannot start a project and then later import a Template. User Extensions are installed as a set of components in the Toolbox that can be imported to your project like any other component.
- User Extensions enable you to package up a few components that implement some sort of non-standard functionality so it can be easily reused.
- Custom App Templates are easier and faster to create than User Extension packages.
Sencha Architect also provides facilities that can be used to share individual classes or components with other projects and other users; these are discussed in the Working with Classes guide.
Creating a Custom App Template
A Custom App Template can be created out of any valid Sencha Architect project. Typically, you will create a project that contains only the code that you want used in all projects that are based on this App Template.
A good possible use for a custom App Template would be to create login functionality that can be used in all projects that require the user to log into the company site. Sencha Architect includes App Templates to create Login functionality for either Ext JS or Sencha Touch; you can start with one of these templates or write your own login program starting with a Blank Screen. Typically, you would then customize the view to contain your company name, perhaps create and apply a custom theme that uses your corporate colors, and add hooks to your login infrastructure.
To illustrate this process, we are going to create a very simple Custom Template that is based on the Ext JS Login/Register template; the process is identical if you start with the Sencha Touch Login/Register App Template.
- Launch Architect and Create a New Project.
- Choose the Ext JS 4.2.x framework and select the "Login/Register" template from the "Basic" category.
- With the "MainView" component selected in the App Inspector, double-click on the "Header" string at the top of the Canvas display and replace the text with "Please log into the MyCompany network".
- Save the project as you would save any other Architect project. Note that the screen displays the actual path where the project will be saved based on what you type in the "Project Name" field.
- Click on "File" in the Menu Bar and select "Add Template".
- Choose "Use Current Project" from the pop-up dialog box that is displayed.
- A dialog box similar to the following is then displayed:
- Enter a title, category and optionally a description for the template, then save.
- The template will be saved to your local templates folder. You can view this location by going to Edit menu > Preferences > File > Templates. This location can be changed at any time and templates will be automatically migrated to the new location. You may also copy/paste template folders into this folder at any time.
You may also edit items in the templates folder if need be.
You can create a custom App Template from an Architect project archive file (.xda) on your system. The process is similar:
- Click on "File" in the Menu Bar and select "Add Template".
- Choose "Select File" from the pop-up dialog box that is displayed, then select the .xda file you want to use from the File Browser window that is displayed.
- Fill out the pop-up dialog box for the Template.
To share an App Template with other users, you may export it:
- Select "Export Template" from the "File" menu, or "Export selected" from the Template Management drop-down.
- Verify or correct the information in the pop-up menu to define the template name and file location, then click "Save".
This creates a .xdt file that you can share with other users.
User's can import templates as follows:
- Download the file to the local file system.
- From Architect, select the "File" menu > "Add Template".
- Choose "Select File" from the pop-up dialog box that is displayed, then select the .xdt file you want to import.
- You may edit the title, description and category if needed.
- Click the "Save" button and Architect imports the template into your location templates folder.
The template will be saved to your locale templates folder. Once a template has been imported, it can be edited as needed.
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 and saved 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 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 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.
- 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 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/directory
To create a package, navigate to the workspace and type the following, replacing “FooExtension” with the name of your Extension:
sencha generate package -type code FooExtension
This 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 in 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 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 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.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".
- 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
versionfield 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.