Architect Sencha Docs

Files and Directories in the Architect Project Tree

This guide provides information about the files that are stored for an Architect project, Custom App Template, and User Extension. Architect 3 uses Sencha Cmd to build projects; in most cases, you do not need to understand much about Cmd because Architect handles the builds for you. If you want to learn more about the inner workings of Cmd, you can read the Advanced Sencha Cmd documents:

These are published as part of the Ext jS documentation; the Advanced information is also relevant for Touch.

Storage Locations

The storage locations for Projects, Components, Extensions, Templates, and Themes are configurable on the File section of the Architect Preferences screen.

Project File Structure

The basic structure and the files that are required by all Architect projects are generated the first time you click the "Save" button for the project. This guide explains this file structure, including some files that are optional and others that are created later in the project cycle.

The application files for an Architect project named "MyApp1" are stored under the "myapp1" directory with the following structure. Note that this discussion includes some files that are optional and others that are probably created later in the project cycle. The basic structure and the files that are required by all Architect projects are generated the first time you click the "Save" button for the project.

By default, these files are located under the Documents/Architect/Projects directory in a folder that has the name you assigned when you saved the project.

myapp1/
    myapp1.xds                    # File used as entry point to saved project
    .architect                    # User settings for your project such as nodes in Inspector
    index.html                    # HTML index file
    app/
        controller/               # .js files for components in Controllers node
                override/         # Optional folder that contains override files     
        form/                
                override/         # Optional folder that contains override files     
        model/                    # .js files for components in Models node
                override/         # Optional folder that contains override files     
        Readme.md
        store/                    # .js files for components in Stores node
                override/         # Optional folder that contains override files     
        view/                     # .js files for components in Views node
                override/         # Optional folder that contains override files     
    app.js                        # Launches the Application class
    app.json                      # Application decriptor
    README.md
    bootstrap.css
    bootstrap.js
    bootstrap.json
    build/                        # Folder where build output is placed
    build.xml                     # Defines the app build process
    ext/                          # Copy of the Ext JS SDK (Ext JS projects only)
    index.html                    # Entry point to your application
    metadata/                     # Files that describe the pieces of the project
        Application               # Metadata for the Application node
        model/                    # Metadata for components in the Models node
        resource/                 # Metadata for components in the Resources node
        store/                    # Metadata for components in the Stores node
        view/                     # Metadata for components in the Views node
    overrides/
    packager.json                 # Configuration for native packaging (Touch only)
    packages/                     # Sencha cmd packages
    resources                     # Library file plus project files developed outside Sencha Architect
        project-images/           # (optional) Contains images to use for styling the app
     sass/
     .sencha/
     theme/                       # Custom Themes and Themes applied from Toolbox (Ext JS only)
     touch/                       # Touch libraries (Touch projects only)

Top-level Directory

The top-level directory for your project contains the following files:

.xds file

The file Architect uses as the entry point for your project has the .xds suffix; the main part of the name is whatever you give it when you first save your project. It contains a small amount of data used by Architect to open and maintain your project. Whenever you relaunch Architect and work on a saved project, Architect opens the .xds file for the project.

This is a simple JSON configuration file and is the only file that is directly modified as you are working in Architect. Every time you build your project, Architect creates all the code files needed to run your project.

index.html and app.js Files

These are the index files that load in the browser when you preview and run an application; they contain the application's initialization logic.

.architect** File

The .architect file contains user settings for your project such as the nodes that are expanded and contracted in the Inspector. You may want to exclude this file from source control.

packager.json File (Touch Projects Only)

The packager.json file contains configuration information for native packaging for Sencha Touch projects.

app Directory

The app directory contains .js files for each top-level component in your project, arranged in subfolders that correspond to the Nodes listed in the Project Inspector -- Controllers, Models, Stores, and Views -- plus a folder for Forms. You should not directly edit any of these files, since Architect creates them and overwrites them every time you save or build your project.

An optional override subfolder to Controllers, Models, etc. contains overrides created with the "Create Override" button in the Code Editor. Note that overrides created with the "Create Override for this Class" option accessed by right-clicking a component in the Toolbox become new classes, not sub-classes.

When you need to do something special that is not provided by the Architect facilities, use the Architect Code Editor to create an override file. Each top level component or class allows for this. Override classes are saved in an override sub-directory under the appropriately typed directory such as view/override or store/override.

bootstrap.js, bootstrap.css, and bootstrap.json

These files are used when building your app in dev mode (previewing the index.html file without a build). bootstrap.css pulls in the correct theme in dev mode; you may need to add your .css file to the app.json file or include it in your index.html file outside the bootstrap comments.

For more information, see Building a Web App.

build.xml and the Build Diretory

The build.xml file defines the build process for your application; it is generated by Cmd and is not normally modified, although reading it may be interesting if you want to understand the build process. The build output is put under the build directory.

metadata Directory

The metadata directory contains the files that describe all the pieces of your project. Each class (Controller, View, Model, Store, and Resource) has its information stored in its own file. You should not edit the metadata files directly. However, they are important to your project and should be tracked in your source control repository. Normal source control operations (such as revert changes, update from source code control) will alter these files; this is completely expected.

packages Directory

The packages directory contains framework packages that are autogenerated for this application such as packages that contain the themes that are used.

resources Directory

The resources directory contains files and folders that were created and edited outside of Architect. Examples include CSS files, images, SCSS files, and JavaScript that was developed outside Architect. These are integrated into your app as external resources; for example, after adding an external .css file to the archive add a CSS resource to your project and point it to this file; for example, css/styles.css. See Using Resources for more information.

CSS and JavaScript files that are added as Resources can be edited using the Architect Code Editor.

Note that, while a "Library" node is displayed under "Resources" in the Project Inspector, there is no file that represents the library in the folder structure.

NOTE: Project files that are edited outside Architect can be imported into Architect as Resources or can be packaged into a User Extension.

theme

Contains files that are autogenerated by the Sencha Architect theme building process.

ext or touch Directory

Each saved Architect 3 project includes a directory tree that contains a copy of the framework SDK being used for that project. This includes libraries for both GPL and Commercial builds as well as debug and production versions of the libraries. When you first open an Architect project, it is set to access a copy of the framework SDK that is located on a Sencha server, but when you first save your project, it pulls a copy of the SDK into your project tree.

If you are creating and maintaining multiple applications that use the same framework SDK, you may want to create an ext or touch directory that is outside the directory for any single application. This enables you to share a single copy of the framework SDK among all of your applications instead of embedding a private copy of the SDK in the directory for each application. If you do this, you must inform the build tools of the location of your SDK by selecting the Library Node under the Resources Node and changing the value of the "Library Base Path" config (which defaults to ext/ or touch/) to reflect the location of the framework SDK directory. For example, if you put your ext directory at the same level as the Extensions, Projects, and Templates directories, set this config to "../../ext".

For more information about how Sencha Cmd uses the framework SDKs to generate an application, see:

User Extension Structure

By default, the files for an installed User Extension (UX) are located under the Documents/Architect/Extensions directory named for the Extension. Each version of a User Extension has its own subdirectory, named 1.0, 1.1, and so forth. Note that you can change this directory by going to Edit Menu > Architect Settings > Asset Storage section > Extension.

The files and directories under the directory named for the version number are:

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. You must manually populate the information in the packager.json file and create and populate a Definitions file for each class/component in the User Extension. The following sections provide full reference information for these two files; instructions and guidelines for setting up these files are in Creating App Templates and User Extensions.

Definition Files

The Definition file defines:

  • How the extension is presented to the user
  • The configurations that are exposed to the user
  • Behavior within Sencha Architect

You must create one definition file for each class that is included in your extension. The file must have a .js extension; we recommend 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,
        merge: false
    },
    {
        name: 'drop',
        type: 'boolean',
        hidden: false,
        initialValue: true,
        merge: false
    },
    {
        name: 'group',
        type: 'string',
        hidden: false,
        initialValue: 'ddg',
        merge: false
    },{
        name: 'notifyEnterCls',
        type: 'string',
        hidden: false,
        initialValue: 'highlightDropZone',
        merge: false
    },
    {
        name: 'dragLabel',
        type: 'string',
        hidden: false,
        initialValue: 'Untitled Region',
        merge: false
    },
    {
        name: 'frameSwapped',
        type: 'boolean',
        hidden: false,
        initialValue: 'true',
        merge: false
    },
    {
        name: 'frameColor',
        type: 'string',
        hidden: false,
        initialValue: '#99FF99',
        merge: false
    },
    {
        name: 'frameCount',
        type: 'number',
        hidden: false,
        initialValue: 2,
        merge: false
    }]
}

The tables below describe all these properties.

Required 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.

Optional Properties

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.

toolbox Property

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

configs

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).
hidden boolean -- If true
initialValue -- -- Value that is automatically set on creation.

listener Objects

An array of listener objects for events such as onCreate, onSetup, etc.

Property Type Default Description
name string -- Name of this object
fn string   Function to be called when the event is observed

package.json File

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,
    "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" .
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"],
        "css": []
    },{
        "definition": "ResourceStore.js",
        "className": "Sch.data.ResourceStore",
        "js": ["ResourceStore.js"],
        "css": []
    },{
        "definition": "EventModel.js",
        "className": "Sch.model.Event",
        "js": ["EventModel.js"],
        "css": []
    },{
        "definition": "EventStore.js",
        "className": "Sch.data.EventStore",
        "js": ["EventStore.js"],
        "css": []
    },{
        "definition": "SchedulerGridPanel.js",
        "className": "Ext.ux.SchedulerGrid",
        "js": ["SchedulerGridPanel.js"],
        "css": [
            "editor.css",
            "sch-all.css"
        ]
    }]
},

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, so "touch22" or "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. but note that you cannot specify Ext JS and Sencha Touch frameworks for one User Extension package.
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.
css Array of filenames in your resources/css folder that corresponds to this class. If you have CSS definitions that apply to the entire User Extension rather than to just one class, you can put this declaration outside the classes array.
css Array of CSS files to load from the src/css folder. These are CSS files that are independent of classes; they are loaded only if at least one class from the user extension package is used in your Architect project.

All fields must be included in the file although some may be be empty. For example, if a class does not have its own CSS file, the css field is empty.

App Template File Structure

For instructions about creating a Custom App Template, see Creating App Templates.

The files and directories for an installed custom App Template are:

template.json               # Template metadata such as title, category and description 
template.xda                # Project archive containing the template code
preview.png                 # (Optional) Preview PNG image. 
preview/                    # (Optional) Provides a live preview of template within architect       
    app/                    # Any architect app with index.html can be used for preview
        controller/
            Tasks.js
        model/
            Tasks.js
        store/
            Tasks.js
        view/
            FormPanel.js
            MainView.js
            TaskList.js
    index.html
    app.js

By default, the files for a custom App Template are located under the Documents/Architect/Templates directory. Templates are dynamically read from the folder, which means you can easily share sets of templates via source control, or by simple copy/paste.

This location can be changed in settings by going to Edit Menu > Preferences > File > Templates. Any existing templates will automatically be migrated if this location is changed.

It is important to try and keep templates as lean as possible. When templates are created from current projects or project archives (.xda) files, any unneeded items such as build files, user settings, or SDK files are automatically removed.

Template Preview Images

You may include a "preview.png" file with a template to provide users with a visual preview in Architects template browser.
The recommended sizes for preview images in pixels are:

  • For desktop or tablet targeted templates: 800x600
  • For phone targeted templates: 325x525

Template Previews

You may also include a live preview along with a template. When you create a template from the current project or from a project archive (.xda) file, a preview folder is created automatically for you, however you may edit the preview files at any time.

Note that the preview folder must contain an "index.html" file to work properly.

Template Metadata

The template metadata is stored in template.json like so:

{
    "title": "Button Template",
    "name": "ButtonProject",
    "description": "A template with a big button.",
    "category": "My Templates",
    "framework": "ext42"
}

The following template values are stored there.

Property Type Required Default Description
name string true -- The project name of the template. (Should not be edited)
framework string true -- The template framework. Example "ext42". (Should not be edited)
title string true -- Display title to use in the template browser.
category string true -- Category to display the template within the template browser.
description string false -- A detailed description for the template.
usePreviewImage boolean false false Force the template to use a preview image rather than a live template.
profile string false -- Determines how a template is displayed and previewed in the template browser. Automatically uses "desktop" for ExtJS, and "phone" for Sencha Touch. You may also provide a value of "tablet to force a tablet like display.

Advanced Template Editing

For editing templates after they have been created or imported, you may edit them directly in your local templates folder. You may edit the template.json metadata file, preview image, and live preview files directly. However, since the actual template code is stored internally as a project archive (template.xda), you must edit it in architect using the following method.

  • Locate the template.xda file in the template folder.
  • Select "File" > "Import Archive"
  • Edit the project as needed, then save to a temporary location.
  • When done, select "File" > "Archive Project".
  • Save the new project archive as *template.xda" to the template folder overwriting the original archive file.
  • Ensure that the framework and category values in the template metadata match that of the archived project.

Template Versioning and Upgrades

Templates are specific to a version of ExtJS or Touch. The framework value in template.json should not be changed unless the template.xda is also upgraded. If you are upgrading a template, it is probably best create a new project from the template, upgrade the project to the desired framework, and then create a new template from the open project. For more details on upgrading a projects library version, see Using Resources > Upgrading the Library