Saving and Sharing Projects

When you build or save a project, Architect stores the project as an entire working directory within the folder you chose when you first saved. The directory structure is similar to the structure used for Ext JS and Sencha Touch projects. This project file directory should be kept under a source control management system.

When the Architect project files are stored in a source control management system, several people can collaborate on one project.

You can also create an archive of a project; this is essentially a zip file (suffix .xda) that another user can download to view and modify under Architect.

How Architect stores a project

Architect 2.2 implements more sophisticated methods for storing projects than earlier releases; these improve efficiency for people working collaboratively on large projects. The major changes are:

• Opening a project now opens only the files that you are modifying and their dependents.
• Saving a project only regenerates the files that have been opened or modified; it does not regenerate all the files in the project, which speeds the time to preview the effects of your changes.
• The Build button has been added to regenerate the entire project as appropriate.

Note that files modified outside Architect and included as Resources to your project are incorporated only when you "Build" your project, not when you "Save" it.

When you build or save a project, Architect stores the project as a directory tree under the folder you chose, with subfolders for app, metadata, and resources plus other folders you might create for your project such as data to hold local data required for your app. This is the structure that is saved on your local system, in the source code control repository that you use and, when you are working collaboratively on a large project, with other members of your team.

The following image shows the project directory for the completed CarStores example app:

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

• .xds file, which Architect uses as the entry point for 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 the only Architect file you touch directly. Every time you build your project, Architect creates all the code files needed to run your project.
• app.html and app.js files, the index files that load in the browser when you preview and run an application. Again, do not edit these files directly. If you need to modify the index file, simply make a copy of the app.html file, make your changes, then open that in your browser directly.
• .architect file that 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

app directory

The app directory contains .js files for each part of your application, including subfolders for each class, or top-level component: Controllers, Models, Stores, and Views. You should not directly edit any of these files, since Architect creates them and overwrites them every time you save or build your project.

When you need to do something special that is not provided by the Architect facilities, use the internal 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.

The app directory looks like this:

data directory

Directory the user creates to hold local data, if any, required by the project.

metadata directory

The metadata folder 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.

Here’s what the metadata directory looks like:

resources directory

Any other files and folders you need to support your project. You create and edit these files and folders outside of Architect, depending on the needs of your project. Examples include a data directory, code that implements business logic that is included in the controller component, or a CSS styles directory. 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.

Share Your Project (Project Archive)

The Architect Archive Project feature is a quick way to share your project for collaborative development or just to let other developers explore your project. For example, if you want the Sencha community to have a look at your project, create an archive of it and post it to the forums. Other members of the community can then download it, load it into Architect, and have a look at it. They can also download the project to their disk and add functionality.

The archive can also be used as a way to define a template for starting a new project by creating default settings and using the archive as the starting point.

To create a project archive:

• be sure that the project has been built, not just saved.
• With the project open in Architect, go to the File menu.
• Select Archive Project.
• Give the project archive a name in the dialog box that opens, and click Save.

Architect creates a file with the .xda extension that can be uploaded to a server. Another person can then download this file and open it inside Architect. If they make modifications to the project, they can create an archive that contains those changes.

NOTE: Project files that are edited outside Architect cannot be imported into Architect except as Resources.

You can also override Architect code using the Architect code editor and Architect will recognize the changes.

Sharing and Reusing Top-Level Components

Architect lets you save top-level components separately for reuse and sharing. To reuse a component along with all its configs, you can use either the Save to Toolbox or Export to File features, both available in the Actions menu. Export to File also lets you share a top-level component with other members of your team, either for additional development in a collaborative project or for reuse in their own Architect projects.

Save Component to Toolbox

Save to Toolbox lets you save a project's top-level components directly to the component Toolbox for later use. This feature enables you to save and reuse components across multiple projects. To save a component you have already built, with all of its configs and any child components, select the top-level component you want to save and go to Actions-->Save to Toolbox. Architect prompts you to rename the component and choose the Toolbox category in which the component will appear, as shown here:

Once you have typed in a name and chosen the appropriate category, click OK and Architect saves the component to the Toolbox. The component is then available for reuse, either in the same or other projects; it appears with your specified name within the specified category, represented by a green component icon. You can find it under the category you chose, or by typing the name you gave the component in the Filter field at the top of the Toolbox.

To update the saved component, make the modifications in your project then save it to the Toolbox again using the same name. Architect lets you overwrite the original and save it to the same category.

Export Component to File

Architect lets you to export a top-level component with all its configs and child components to file. To do this:

• Select the component in the Inspector
• Go to Actions-->Export to File
• Navigate to the directory where you want to save the component
• Give the component a name and click Save

Architect saves the component with the file extension .xdc. You should check that file into your source control system, or make it available to your team according to whatever process you have worked out. From there, here’s an example workflow your team could follow, say for a common login form that you might want all your apps to use:

1. Another member of your team, Angela, imports the component to Architect using the Import Component feature discussed in the next section. Architect places the imported component in the Toolbox.
2. Angela drags the component from the Toolbox into a project. If the component is a View, it can be dragged into the Canvas; if its a Controller, Model, Or store, it must be dragged to the Inspector.
3. She adds to the component using Architect.
4. Next she exports the revised component and makes it available to you (using source control or another process you have set up).
5. You reimport the component, then add it back the original project, making sure to place it in the right place in the Inspector. Its new functionality will be available to the app you are building.

If Angela subsequently modifies the component, you must re-import the modified component into your toolbox and manually delete the old one unless you need it for some reason. Note that the modifications Angela made to the toolbox item only affect newly-created components; components in projects that were created from the original toolbox item are not updated automatically.

Import Component

A component that has been exported using the Export to File feature can then be imported into another developer's instance of Architect for further development or reuse in other projects. Note that only components created in the Sencha Architect Ext JS environment can be imported to an Ext JS project, and only Sencha Touch components created under Sencha Architect can be imported into Sencha Touch projects.

If another developer adds to the exported component, it can then be reimported back into Architect and added back to the project. This is a great way to collaborate with other members of a team on a single Architect project. To import a component that has been exported, be sure the exported component has been placed at a location where it can be accessed, either on the desktop or on a server. In Architect, open the Edit menu and select Import Component. Navigate to the location of the component, select it, and click Open. Architect prompts you to rename the component and choose the Toolbox category in which the component will appear, using the same dialog used when you save a component to the Toolbox. See the image just above, under "Save to Toolbox".

After you have typed in a name and chosen the appropriate category, click OK and Architect saves the component to the Toolbox. The component is now available in the Toolbox to add to any Architect project, just as you would any other component.

Saving and Exporting Child Components

The process shown above works only for top-level components. A different process is required to save and export child components. For example, if you have a LoginScreen container, and you want to add to it a previously created LoginForm component, you can drag and drop your LoginForm component onto your LoginScreen container and establish a Linked Instance. A linked instance is analogous to an instance of an object when speaking in object-oriented programming terms. Consequently, any changes made directly to your LoginForm component are reflected in the linked instance. You can create as many linked instances as you want, either by drag-and-drop of a top-level component or by duplicating an existing linked instance. By using this technique, you can build each logical piece of your project separately and later view all of these pieces together by establishing linked instances into an aggregate container such as a Viewport.

Architect 2.1 supported this but it was a difficult process appropriate only for experts. Architect 2.2 provides a more accessible method; both are described here.

Linked Instance and Promote to Class (Architect 2.1)

Architect 2.1 provided the Linked Instance and Promote to Class features that let you create instances of a top-level component as a child item to another top-level component. Note that Architect 2.2 introduces the createAlias feature (discussed below) that is an easier and better way to achieve the same goal.

Linked instances can be very helpful in building complex projects. If you create multiple linked instances of the same component, you can change them all at once by editing the original component, and each linked instance inherits all the changes. You can still edit each linked instance separately; changes made to the linked instance override the attributes you give the original component. This is particularly useful when you use another Architect feature, Promote To Class. For more information about linked instances, see Working With Linked Instances.

Promoting a child component to a class

Any child item in a component can be promoted to a top-level component and become its own class in the Architect project directory using the Promote to Class feature. For example, Grid Columns can only be added to Grid Panels or Tree Panels when they are initially created because they do not serve any purpose on their own.

To do this, first drag a Grid Panel to Views in the Inspector. A new Grid Panel receives several columns by default. Right-click “Boolean” -- the header of one of the columns -- in the Inspector -- and choose Promote to Class.

The column becomes its own top-level component and is replaced by a linked instance in the Inspector. When Architect exports the project, it generates a separate .js file for the component/class. This works for most View components in Architect.

Using this feature can make it easier to share and manage a project if you are working with a team. In addition to generating more manageable code, organizing a Architect project as a collection of top-level components can make it easier to continue to develop the project. By using linked instances within main application views, it is still easy to view all the top-level components in context.

Promote to Class works in tandem with Linked Instance and lets you convert any nested component into a top-level component. When you do this, Architect creates separate .js files for the component when you save and archive your project. When you use Promote to Class, the original component is replaced by a linked instance to its new top-level version. This makes it easy to break up a large component into smaller, reusable, and more manageable subsets. It also means that you can implement behavior, override functions, or implement function-typed configuration options on our new component class.

Our Architect 2.1Kiva example application illustrates the Linked Instance and Promote to Class process. You must specify an override in order to add custom outside libraries to Architect and use those libraries within Architect's components. In the Kiva example application, a special JSONP Proxy library is provided that passes through YQL in order to perform queries that Architect can handle natively.

This is achieved by adding a library, KivaProxy.js, as a resource. Then, rather than adding a JSONP store, a plain store is added and the code is manually overridden to use the code from KivaProxy.js (which is given the alias 'proxy.kiva' within that file) The excerpt from the Architect 2.1 code illustrates this:

Ext.define('Kiva.store.override.Loans', {
    override: 'Kiva.store.Loans',

    requires: [
        'Kiva.model.Loan'
    ],

    config: {
        autoLoad: true,
        model: 'Kiva.model.Loan',
        remoteFilter: true,
        storeId: 'Loans',    
        proxy: {
                type: 'kiva',
                reader: {
                    type: 'json',
                    successProperty: 'success',
                    rootProperty: function(data) {
                            if (data.error || data.query.count === 0) {
                                return [];
                            } else {
                                return data.query.results.loans;
                            }
                        }
                }
            }
       }

});

The Architect 2.1 method has serious drawbacks:

• It requires some working knowledge of ExtJS overrides, and is a somewhat cumbersome means of achieving a simple goal.

• Because of the manual override, you must also write code for the 'reader' -- the code that tells the store where in the data to look for the relevant records.

• Any other properties underneath the store, must also to be adjusted in code rather than in the Architect GUI when the user needs to make changes.

For these reasons, the createAlias feature was added to Architect 2.2. If your Architect project has implemented the Architect 2.1 features described above, it still works in Architect 2.2, but the features described below are much easier to maintain for projects being developed.

createAlias and createClass instantiation (Architect 2.2)

Sencha Architect 2.2 include features called createAlias and createClass that enable developers to bring in external libraries, inserting custom code into components without using code overrides. Many applications use other libraries with the Sencha frameworks and the createAlias and *createClass configs allow simpler integration of these external JavaScript libraries by setting up an xtype or class name for the external component.

The Architect 2.2 Kiva example application illustrates how to achieve the same effect by using createAlias and no override. Instead, the same affect is achieved through the following:

• add a JSONP store
• set the createAlias config to "kiva".
• set the "root" property of our reader to 'query.results.loans'

This is not only faster to implement but it provides the flexibility and comfort of using a simple GUI to continue any further customization of a store, proxy and/or reader. createAlias gives you a name by which to reference the child component and you can then easily reference that child component using this name rather than having to override the store as you did in Architect 2.1.