Using App Templates and User Extensions
App Templates and User Extensions allow you to easily share code with others. The differences between the two are:
- App Templates can be used only to start a project; User Extensions can be incorporated into your project at any time during the development process.
- Templates are used in totality whereas user extensions add components to your toolbox that can be included with or without other components from the user extension package.
This guide discusses how to use App Templates and User Extensions in your project. See the Creating App Templates and User Extensions guide for information about creating your own App Templates and User Extensions.
Using App Templates
App Templates are provided to streamline the process of starting a new project. Several common project types are included in the Sencha Architect package; you can add additional templates that you or someone else created.
When you first launch Architect and choose "Create New", you see a screen that allows you to choose the framework to use and then select a App Template to use for your project. This is the display for Ext JS; the display for Sencha Touch is similar:
- Choose your desired framework (Ext JS or Sencha Touch).
- Click on the arrow to the right of the framework name to select another version of the framework. When you do this, "Blank Project" is displayed; click on this to enter the standard Architect development screen. You can click on "Blank Project" for the current framework as well if you want to begin your project without using a template.
- The available templates for each framework are grouped logically into "Basic", "Layouts", "Examples", and "Starter Apps"; links to each group are displayed in the left column. You can look through the available templates and select the one that is closest to what you need.
- To see a Preview of a App Template, click on the "Eye" icon that is displayed on the upper-right when you hover on the template.
- Click on the App Template that is close to what you need for your project, click the "Create" button in the lower right of the screen and Architect sets up a project for you that is based on this Template.
- When you click on the "New Project" button on the Toolbar, you will be taken to the Template page you used to start the previous project.
These templates set up the application's structure, and may include Views, Controllers, Models, Stores, Themes, and so forth -- basically, any building block that can be used in an Architect project can be included in a template. You can then customize the template as appropriate to create your project.
You can always start development with a blank canvas by selecting "Blank Canvas".
Note the following details about App Templates:
- These templates can only be used when first starting a project. You cannot add a template to an existing project.
- App Templates are only provided for ExtJS 4.2 and above, and Touch 2.2 and above.
- A project created from a template is not updated when the template itself is updated.
- Users can create their own App Templates; this is documented in the Creating Templates and User Extensions guide.
Incorporating User Extensions
The User Extensions feature enables you to incorporate components (classes) that are developed outside of Architect into your Architect project. With the User Extension feature, components from User Extensions that have been packaged for Architect can be dragged from the Toolbox, rendered in the Architect Canvas, configured through the Architect Config panel and maintained inside Architect, just like any other component.
Using these extensions saves you the effort of rewriting functionality that someone else has already coded, with the added benefit that these extensions get extensive testing because over time, many members of the community have downloaded and used them.
Architect User Extensions are delivered in packages that are easily downloaded and installed. Each User Extension package works with either Ext JS or Sencha Touch; be sure to select a package that is compatible with the framework you are using for your Architect project. A User Extension runs in its own sandbox which provides the security that is warranted when running code that is downloaded from the web.
This document tells you how to incorporate a User Extension into an Architect 3 project.
For instructions about creating your own User Extension package, see Creating User Extensions.
Downloading User Extensions
To download a User Extension:
- Log into Sencha Market.
- Click on the "Product" tab.
- Select "Sencha Architect 3":
- Be sure to choose an extension that is packaged for use with Sencha Architect 3.
- Be sure that the extension you choose works with the framework and version you are using for your project.
Installing a User Extension
To incorporate a User Extension into an Architect project:
- Download the User Extension package. This is a file with a .aux extension.
- Open (or start) an Architect project, using a framework with which this User Extension is compatible.
- Click on the icon to the right of "Extensions" in the Toolbox
or go to the
Filemenu and choose "Install User Extension".
- When the file browser comes up, browse to the downloaded .aux file and select it.
- You should receive a message indicating that the Extension was installed successfully.
After the Extension is installed successfully, it is listed in the Toolbox in its own category below "Extensions" with a number in parenthesis that indicate the number of classes included in the Extension, and the number listed for the "Extensions" category is incremented to add the classes included in this Extension.
Classes that are included in User Extensions may also be included in other Categories. For example, the "Drag Drop Region" and "Scheduler Grid" classes are both listed under Containers category:
Note the icon shaped like a jigsaw puzzle; this indicates that this class is part of a User Extension. This same icon shows in the Project Inspector when a class from a User Extension is used.
If the Extension does not install successfully, the Extension package may be missing files, be missing some key configuration parameters from the package files, or have some other problem. Architect outputs some useful debugging information into the Sencha Architect Log to help you analyze the problem.
Using Components from a User Extension Package
After you successfully install a User Extension package, the components from the Extension are listed in your Toolbox under the "Extensions" category and possibly another appropriate category. You can drag any component to the Canvas or Project Inspector like any other component and can set its configs (if any) in the Config Panel.
Some components from User Extensions automatically create more than one top-level component. For example, a special type of View might come with a Store and Model with pre-configured fields. When this is done, Architect creates them as a linked group. This linkage allows Architect to warn you if you attempt to delete a component that is a member of that linked group, since these components rely on each other.
You can also use the keyboard shortcuts ⌘+ and ⌘+- (Mac) or Ctrl++ and Ctrl+- (Windows and Linux) to cycle between selecting the components in a linked group.
When you Save or Build your project, a copy of each Extension that has been used in the project is saved inside your project folder so it is included in your project going forward. Extension developers control which config items are visible, create additional config items and assign reasonable default values. The end user can then tweak those values as appropriate.
User Extension packages are versioned. You can install multiple versions of a User Extension Package on your system, but only the most recent (highest numbered) package is loaded and visible in your Toolbox.
If you open a project that used an older version of that User Extension package, by default Architect loads the older version of that package but prompts you for alternatives:
- If you have a later version of that Extension installed (e.g. v1.1, while the project contains v1.0), you will be asked if you want to upgrade the project to use that later version; the version contained in the project will be used unless you choose to upgrade.
- If the project contains a later version of an Extension than what is currently installed in your Sencha Architect, you will be asked if you want to install that Extension so it is available to you to use in other projects.
- If the project contains an Extension that is not currently installed in your Sencha Architect, you will be asked if you want to install that Extension so it is available to you to use in other projects.
Uninstalling a User Extension Package
To uninstall a User Extension package from your system, right-click on the User Extension in the Toolbox, then select "Uninstall Extension" from the drop-down menu:
Note that you can change the installation location for User Extensions by going into the Preferences screen click "Preferences" on the Sencha Architect drop-down menu on Mac, or the Edit drop-down menu on Windows and Linux) and modifying the value of the "Extensions" field: