Stores and Models

Architect projects use Stores and Models to handle data in their applications. Ext JS and Sencha Touch apps both use the Stores and Models paradigm to store and manipulate data; Sencha Architect provides a simple, unified interface to both.

This guide is an introduction to this topic.

• For more information about the Ext JS data package, see the Ext JS Data guide and follow the links from that guide for more details.
• For more information about the Sencha Touch data package, see the Sencha Touch Data guide follow the links from that guide for more details.

Let's start with Models. At its most basic level, a Model describes the structure of a set of fields for a type of data and the type of each field. For example, a Model for a "User" might contain the following fields: "username", "department", "date_joined", and "manager" defining the "date_joined" field as date type and the other fields as string type. In other words, Models define the schema of the data accessed by your application.

A Store is an object that holds a collection of data records and allows the application to iterate, search, and manipulate those records. Each of a Store's records is an instance of the particular Model associated with that Store. Following our example of having a Model that describes the fields contained for a "User", our "Users" store would contain a list of all users.

Views in either Ext JS or Sencha Touch access Stores to populate their respective visual counterparts. For example, a "user details" view might access the "Users" store, query for a specific user, and populate the contents of the fields (such as username and date joined) in the application.

Stores need a source from which to pull their data. The most basic Store is a static, hard-coded set of data, but it is much more common to pull that data from the web. For this, we have two tools:

• A Proxy tells a Store where and how to load in data from an outside source. In modern applications, this is usually JSON data that is requested from a web server
• A Reader tells the application where in the data to look. For example, If the object returned from a web server returns our data in a root level called user_list, the Reader's root would be set to user_list.

Here is an example JSON file to illustrate:

{
"response_code": 200,
"response_message": "OK",
"response_timestamp": 1363208209,
"user_list": [
  {
    "username": "bob",
    "date_created": 1363148384,
    "profile": "Bob is from Arkansas. He enjoys reading, live music, and cookies."
  },
  {
    "username": "jane",
    "date_created": 1363106223,
    "profile": "Jane is from Virginia. She loves math, cooking, and this application!"
  }
]
}

To summarize the data paradigm:

• Stores provide a client-side data cache for UI components.
• Stores in Architect retrieve data from either a local or remote source and make it available for display within a UI component such as a grid panel, tree panel, or combo box in Ext JS projects or a data view, list, or nested list in Touch projects.
• Stores work with a proxy to load data and a reader to parse the data into the proper schema, which is determined by a Model.
• A Store is essentially a collection of Model instances.
• The Store also provides functions for sorting, filtering, and querying the Model instances contained within it.

For more details about Stores, see the appropriate reference page: for Ext Data Store or Touch Data Store

The basic process for setting up Stores and Models is as follows:

1. Add and configure Model(s); this includes adding fields to Model(s) and mapping fields to data.
2. Add a Store along with the appropriate proxy and reader; in Architect, the appropriate proxy and reader are added automatically when you select a type of Store.
3. Configure the Store, proxy, and reader.
4. Associate Model(s) with Store(s).
5. Associate the Store with View components.

The rest of this guide includes instructions to complete each of these steps.

For further reading:

• Three examples of Stores are included at the end of this guide.
• For examples that include all of these steps in a real application, see Build Your First Desktop App and Build Your First Mobile App.

Models

Architect provides a complete MVC package using Models to represent the data objects used in an application. You work with Models just as you do other components in Architect, adding them to your project and then configuring them.

Adding Models

Click the add button ("+") on the top right of the Inspector and select Model to add a Model to a project or select a Model from the "Data" category in the Toolbox.

Architect displays the Model under the Models node in the Inspector.

Configuring Models: The basics

Select the Model in the Inspector to open its configs in the Config panel. Following are basic configs to set for Models to enable and associated Store to load data:

userClassName -- Give the Model a unique name.

Fields -- Use to add fields to a Model. To add a field:

1. Click the add button ("+") to the right, under Value, to add a field.
2. Give the field a name; the name should match the record field name. You can add and name multiple fields at once by typing them in a comma-separated list (for example, "name, birthday, hobbies".
3. The Inspector displays each config under its corresponding Model.
4. After a field has been added, it can be configured further by selecting it in The Inspector. For example, the "mapping" config is used when, for example, the data source you are requesting returns a field called "user_name" but you want to call your field "username"; in this case, set the "mapping" config for the "username" field to "user_name".

For an example of this, see the "Add and configure Stores and Models" section of Build Your First Mobile App.

Additional Model Configs

Although not required for a Store to load data, you can also add associations, proxies, and validators to Models through the Config panel. Here are other significant Model configs.

Associations: Add associations to a Model. Choose from BelongsTo, HasMany, or HasOne. See the Association docs for more information

Proxy: Add proxies to a Model. Usually you define the proxy on the Store but you can define it on the model instead; this is useful if your project has multiple stores that use the same Model and share the same proxy so you do not have to redefine it for every Store. Choose from the following types:

• Ajax
• Direct
• JsonP
• LocalStorage
• Memory
• Rest
• SessionStorage

Validators: Add validators to Models. Choose from the following types:

• Email
• Exclusion
• Format
• Inclusion
• Length
• Presence
• Range

See the Validator for more information.

Field configs

Select fields in the Inspector to set their configs, including the following:

• name
• type
• mapping
• sortDir
• sortType

See the Field for more information.

Stores

Stores contain the actual information for the application. Architect provides a generic Store in the Toolbox, which you can add to your project. You can then assign it a Proxy, which tells the Store how and where to load its data from (URL, protocol, and so forth); you can also assign a Reader, which knows the format of the incoming raw data so it can be parsed into the target Model records.

Architect also provides several specialized Store types that are pre-configured with some of the most common Proxy/Reader combinations. For example, a JsonP Store is automatically configured with an Ajax Proxy plus a JSON Reader. This is only a starting configuration; you are free to remove or replace the initial proxy and reader as you wish.

Note that you can also add a Store by using the drop-down menu you get by clicking the + at the top of the Project Inspector.

The following Store types are provided in the Toolbox:

Store

A generic store with no initial proxy or reader

• Store Class - Sencha Ext JS | Touch
• Proxy Class - None
• Reader Class - None

JSON Store

A store initially configured with an Ajax Proxy and JSON Reader. Commonly used to retrieve JSON-encoded data via an AJAX call.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

JsonP Store

A store initially configured with a JsonP Proxy and JSON Reader. Commonly used to retrieve JSON-P wrapped JSON data via a script tag; particularly useful when the data is being loaded from a different domain.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

Array Store

A store initially configured with an Ajax Proxy and Array Reader. Similar to a Json Store, but for when the target JSON data's individual records are encoded as arrays rather than objects.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

XML Store

A store initially configured with an Ajax Proxy and Xml Reader. Commonly used when the data is XML-encoded. The end of this guide includes an example of using an Xml Store.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

Direct Store

A store initially configured with a Direct Proxy and Json Reader. Commonly used when the data source is exposed using the Ext Direct protocol.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

Tree Stores

Architect also provides the following Tree Store types, that hold their data in a nested tree-like structure rather than in a flat collection. These are generally used only in conjunction with a view component that knows how to display tree-like data, such as a Tree Panel in Ext JS or a Nested List in Sencha Touch.

Tree Store

A tree store initially configured with an Ajax Proxy and JSON Reader. Commonly used to retrieve JSON-encoded tree data via an AJAX call.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

JsonP Tree Store

A tree store initially configured with a JsonP Proxy and JSON Reader. Commonly used to retrieve JSON-P wrapped JSON tree data via a script tag; particularly useful when the data is being loaded from a different domain.

• Store Class - Ext JS | Touch
• Proxy Class - Ext JS | Touch
• Reader Class - Ext JS | Touch

XML Tree Store

A tree store initially configured with an Ajax Proxy and Xml Reader. Commonly used when the tree data is XML-encoded.

• Store Class - Ext JS / Touch
• Proxy Class - Ext JS / Touch
• Reader Class - Ext JS / Touch

To get additional details about what each Store does while running Architect, just mouse over the ? next to each store type in the Toolbox; this displays a brief description of the class and a link to the API documentation.

Adding Stores

You have two different options for adding a Store to a project. The first is to click the add button ("+") on the top right of the Inspector and drag the cursor to Store to open the alphabetized list of Store types.

Alternately, you can drag a Store from the Toolbox: click on the "Data" category then scroll down to the "Data Stores" group on the drop-down menu. Select the Store you want and drag it to the Inspector panel; drop it on "Stores" node.

When you select a Store, it is added to your project under the Stores node in the Inspector along with the appropriate proxy and reader. You can look at the Code View in the center panel to see the code that is generated.

You do not have to use the default type of Proxy and/or Reader that is created; to choose a different type:

• Go to the Project Inspector panel.
• Right click on the Proxy or Reader you want to replace.
• Select "Transform" from the drop-down menu that is displayed.
• Choose the Proxy or Reader you want from the drop-down menu.

Configuring Stores: basics

Select the Store in the Inspector to open its configs in the Config panel. Select proxies and readers to see their configs.

Stores, proxies, and readers have many configs but only a few basics are really necessary to get started.

Until you have successfully completed these steps, the Store cannot load data. Architect lets you know this by displaying an exclamation point to the right of the Store in the Inspector.

(For details about any property in Config, position the cursor over the question mark next to the property name to display a description and a link to API documentation for the config.)

In the Store, set the following:

userClassName -- Give the Store a unique name. This will become the class name of the store in the generated code.

storeId -- Main identifier used for stores. In Sencha Touch, this is what is listed in the dropdown menu when associating the Store with a View. In Ext JS, this should be set to the same value as the userClassName.

autoLoad -- Optional configuration that allows the Store to load its data automatically when the application starts. To activate it, place a check in the box on the right of Config, which sets autoLoad to true. For this to work, be sure the buffered config is unchecked.

model -- The Value field displays a list of Models that have been added to the project. Select a Model to associate with this Store. Enabled when Models have been added to a project. See the next section of this guide to learn how to add and configure Models. The process of associating Stores and Models is described in greater detail below, in the section "Associating Stores with Models and Views."

In the proxy, set the following config:

url -- The URL from which to load the remote data. Typically, the url config in the proxy is set to a relative path. It can also be absolute in cases like JsonP proxy. Unless the URL is able to resolve, you cannot load data within Architect. If the URL is a relative path, the URL Prefix in Architect settings needs to be set. This only applies to proxies that load remote data and is not required for proxies such as the memory proxy that are local.

In the reader, set the following:

root/rootProperty -- Specifies the property or element in the response data that contains the collection of row objects, if that collection is not at the root. Not applicable to the Array Reader.

Adding custom Store configs

In addition to the other Store configs shown, add custom configs by typing the config name into the Filter field at the top of Config and clicking Add. The custom config will appear in the Config panel, where you can set it.

Esoteric notes

In most cases, the configs discussed here are all you need to use but other options are available if you need them:

• You can use a generic Store if none of the standard Store types meets the needs of your application. To add a generic Store, click the add button and click Store. The Store is added to the Stores node. No default proxy and reader are defined for a generic Store but you may add a proxy and a reader to it if needed. With the Store selected in the Inspector, look for the Proxy config. Click the add button to the right and choose the kind of proxy you want to add to the Store. It will appear under the Store in the Inspector. Select the proxy there, look for the Reader config, and use the add button to add a reader to the Store.

Loading data into a Store

Once a Store is successfully configured, the exclamation point no longer appears next to the Store in the Inspector and the Store is ready to load data. To do that, right-click the Store and select Load Data from the context menu that appears. If the Store loaded the data successfully, Architect displays an eye icon next to the Store in the Inspector. Position the cursor over the eye and Architect displays a message saying how many records were loaded. Click the eye to see the data in raw format in a separate window.

If the Store is unable to load data, Architect displays an exclamation point next to the Store. Click the exclamation point to open an error message, which suggests what to do to enable the Store to load data.

Associating Stores with Views

After creating a Store with an associated Model, the Store needs to be bound to a View component to display the data.

To bind the Store to a View, select a View in the Inspector to View it in the Canvas. In the Canvas, click the Flyout Config button on the View to display a list of Stores you have created in the project. Select a Store to bind it to the View. You can also do this by finding the "store" config in the Config panel when the View component is selected.

Note that only some View component types can be bound to a data store. Some of these are:

• Data View
• Charts
• List (Sencha Touch only)
• Grid Panel (Ext JS only)
• Tree Panel (Ext JS only)

You may need to set additional configurations for the View so that it displays data correctly. For example, if you use a grid, you need to link grid columns to appropriate fields in the Store. You do this by right-clicking the grid in the Inspector and selecting Auto columns. If you use a chart, you have to set its series and axis configs to correspond with the kind of data that will populate it.

Working with Databases

The Sencha frameworks provide Readers that know how to load data in either JSON or XML format. If your data is stored in a database, you can use any server-side language to generate the JSON or XML file that can be passed to your Sencha Architect application.

Using Mock Data

Architect supports the Mock Data feature that allows you to input "dummy data" into a Store or View component so you can see what it looks like on the Canvas but the data is not included your application's generated code; you can still have your Store set up to pull its data from a server. This enables you to simulate data for testing when it is difficult or costly to access and store the data, such as when additional information (such as a login token or geolocation) is required to access the real data.

Two different mock data facilities are available:

• You create the mock data you want to use (available in Architect 2.2 and later)
• Architect generates data that conforms to the Model and Store you have defined (available in Architect 3.0 and later)

To see how mock data works, start up a new project using the Sencha Touch "Task List" template. Select the "Tasks" store, find the "data" config, and click on the "Edit" icon:

This brings up a Code Editor panel that has a JSON-formatted array of objects that correspond to the information that was displayed. You can edit this information; for example, try changing the first item to "Write a song". When you have made the changes you want, Check the checkbox labeled "Mock up data" at the upper right corner of the editor:

Now go back to the Design view; the information you changed is displayed.

In Architect 3 and later, Architect can generate data for you, based on the fields and types defined in the Model that is associated with this Store. To do this, click the "Generate Data" button. Architect displays the fields and types to use and lets you choose the number of records to create.

You can modify the types to be used for each field, to fine-tune the data that is generated. For example if your model has a "first_name" field with a type of "string" then you can choose to generate a First Name for that field rather than a random string. Note that the types selected here only affect the mock data that is generated; the fields and types that are defined for the Model will not be changed.

Once you have made your type selections, click the "Generate Data" button; Architect displays the JSON file it has created. If you like, you can edit this information. When you go back to the Design view, you will see the new data used in the display.

Example 1: Json Store

The first example shows you how to build a Json Store. The Store will need some data, so create a dummy JSON file that contains data to be loaded into the project. For this example, create a file called customers.json that contains the following:

{
    "customers": [
    {"name": "Bradley Banks", "age": 36, "zip": "10573"},    
    {"name": "Sarah Carlson", "age": 59, "zip": "48075"},
    {"name": "Annmarie Wright", "age": 53, "zip": "48226"}
    ]
}

Save the customers.json file on the host specified by the URL Prefix for the project. For example, if the URL Prefix is set to http://localhost, make the file available at http://localhost/data/customers.json.

Add and configure a Model

Add a Model to the project and set its userClassName to a name you can easily remember. It is easier to use something close to the Store name, since you will associate the Store and the Model in the project.

Now add three fields to the Model, one for each of the name:value pairs to access from the elements in the customers array. You add fields using the Fields property in Config. Set the name of the first field to name. Set the name of the second field to age and set it’s type to int. Setting the field type enables the field to be sorted correctly. Set the name of the third field to zipcode. Since this is different from the name used to reference this value in the Json file, the field’s mapping attribute also needs to be set, in this case to zip.

Add and configure Json Store

In Architect, go to the Inspector, click the add button ("+"), and select Json Store to add the Store, along with its reader and proxy, to the project. Note that Architect displays an exclamation point next to the Store in the Inspector indicating that it is not ready to load data.

Select Json Store in the Inspector. Set userClassName in Config to a name that will be easy to remember. The object type in this example data is a customer, so a good name for the Model is "Customer" and a good name for the Store is "Customers". This is a good practice to follow: name the Model to describe the type of "thing" it is and name the Store as the plural of that name. Put a check in the box next to the autoLoad config so the Store loads data automatically.

Select the proxy in the Inspector, and in Config set its url attribute to the location of the source file on the host specified by the project URL Prefix. In this case, the Json Store has been saved in the data directory on localhost, so set the url attribute to data/customers.json.

Select the reader, and set its root (rootProperty in Touch) config to customers. This matches the name of the array specified in the Json file you just created.

Associate Model and Store

Now associate the Model with the Store. Go back to the Store in the Inspector. Locate its Model config and open the field to its right in Config under Value. Look for the name of the Model you just added and select it.

If you have completed all of the steps correctly, the Inspector no longer displays the exclamation point next to the Store, which means it can now load the data from the customers.json file.

Load data

With the Store selected, right-click and choose Load data. When the data is successfully loaded from the source, Architect displays an eye icon next to the Store in the Inspector. Position the cursor over the eye and Architect displays a message saying how many records were loaded. Click the eye to see the data in raw format in a separate window.

If the Store is unable to load data, Architect displays an exclamation point next to the Store. Click the exclamation point to open an error message, which suggests what to do to enable the Store to load data. Correct the problem, and try loading the data again.

Example 2: Array Store

The next example shows how to build an array Store. For its data, create a Json file called contacts.json that contains the following data array:

[
    ["Ace Supplies", "Emma Knauer", "555-3529"],
    ["Best Goods", "Joseph Kahn", "555-8797"],
    ["First Choice", "Matthew Willbanks", "555-4954"]
]

Save the contacts.json file on the host specified by the project’s URL Prefix. For example, if the URL Prefix is set to http://localhost, make the file available at http://localhost/data/contacts.json.

Add and configure a Model

Add a Model to the project and set its userClassName to a name you can easily remember. Add three fields to the Model, one for each element the application needs to reach from the row arrays in the source file. Name the three fields name, contact, and phone.

Add and configure Array Store

Add an Array Store, along with its reader and proxy, to the project, and select the Array Store in the Inspector. Set userClassName and storeId to the same name, and check the box next to the autoLoad config. Set the proxy's url attribute to the location of the source file on the host specified by the project URL Prefix, in this case data/contacts.json.

Associate Model and Store

Select the array Store in the Inspector and set its Model config to the name of the Model you just added.

Load data

With the Store selected, right-click and choose Load data. Click the eye to see the data in raw format in a separate window. If the Store was unable to load data, click the exclamation point to find out why. Correct the problem and load the data.

Example 3: XML Store

This example shows how to use an XML Store. For data, create an XML file called products.xml that contains the following data:

<?xml version="1.0" encoding="UTF-8"?>
<Products xmlns="http://example.org">
    <Product>
        <Name>Widget</Name>
        <Price>11.95</Price>
            <ImageData>
                <Url>widget.png</Url>
                <Width>300</Width>
                <Height>400</Height>
            </ImageData>
    </Product>
    <Product>
        <Name>Sprocket</Name>
        <Price>5.95</Price>
            <ImageData>
                <Url>sc.png</Url>
                <Width>300</Width>
                <Height>400</Height>
            </ImageData>
    </Product>
    <Product>
        <Name>Gadget</Name>
        <Price>19.95</Price>
            <ImageData>
                <Url>widget.png</Url>
                <Width>300</Width>
                <Height>400</Height>
            </ImageData>
    </Product>
</Products>

Save the products.xml file on the host specified by the project’s URL Prefix, such as http://localhost/data/products.xml.

Add and configure a Model

Create a Model, name it, and add three fields to it. Set the name of the first field to name and its mapping config to Name. Note that the mapping is case sensitive and must match the element name. Set the name of the second field to price, its mapping to Price, and its type to float. Set the name attribute of the third field to imageUrl and the mapping attribute to ImageData > Url. Note that this uses a DomQuery selector to access the Url sub-element of ImageData.

Add and configure XML Store

Add an Xml Store, with its proxy and reader, to the project. Set the Proxy’s url config to the location of the source file on the host specified by the project’s URL Prefix, such as data/products.xml. Set the reader’s record config to the name of the XML element that contains the data to load, in this case Product.

Associate Model and Store, load data

Select the XML Store in the Inspector and set its Model config to the name of the Model you just added. Load the data as you did in the previous examples.