Architect 2 Sencha Docs

Build Your First Desktop Application

Contents

  1. Application description
  2. Preliminary steps
  3. Project setup
  4. Set up the initial view
  5. Loading data into a grid
  6. Working with data: Models and Stores
  7. Binding the grid to the Store
  8. Connect grid to a detail panel
  9. Add a Chart
  10. Run the application
  11. Files for this article

This guide provides step-by-step instructions for using Sencha Architect to build a web application that runs in a desktop browser. The example application is called CarListings and uses the Ext JS 4.x framework.

Application description

CarListings is a simple application that illustrates the use of data binding. In the finished application, the user selects a car in a grid to see details about the car, including a picture of it. By the end of this tutorial, you should have a better understanding of how to build and configure views, how to model data, and how to bind your data to views.

Preliminary steps

Before using this guide, do the following:

  1. Download, install, and set up Architect, then set up a web server and create a folder for your projects on the web server, following the instructions in Getting Started with Sencha Architect.

  2. Read through that document to familiarize yourself with the basic concepts of Architect and the various components of the Architect display.

  3. Download the data files http://www.github.com/SenchaArchitect/CarListings/data.zip) for the example to a convenient place in your file system. (The complete project source for the example can be downloaded as an archive or you can view the github repository.)

Project setup

When you begin a project, you must:

  • Launch Architect
  • Point Architect to the URL of your web server so you can preview and test applications
  • Name your project
  • Save your project

Launch Architect

Select the most recent Ext JS 4.x framework for the project from the splash screen displayed when you start Architect or from the list presented when you click the disclosure triangle to the right of "New Project" in the upper left of the screen. Architect will set up a new project for you.

Point Architect to the URL Prefix of the Web Server

You must point Architect to the URL of the web server. To do this, click Settings in the menu bar at the top of the screen. Go to the Project tab, which looks like the following:

Edit the URL prefix field to point to the folder you just created. It should contain a URL that looks something like http://localhost/myprojects/sampleproject1 (replacing myprojects with the folder name you chose if it is something else). Do this carefully or you will not be able to save your project correctly or preview it in a browser.

You must edit the URL prefix for each new project in order to save and preview it correctly. Note that this location is used for developing your Architect application; when you deploy your application, it should be moved to a different location as discussed below.

Name your application

The first step of creating an Architect project is to name the application. To do this:

  1. Click on "Application" at the top of the Inspector window located on the upper right side of the screen
  2. Find "name" in the config panel and set it to "CarListings".

For more details, see Application node configuration notes.

Save your project

When you first Save your project, Architect creates a project directory for the project; the dialog shows you where it is saved. The convention is to use a lowercase version of the Application Name you assigned in the previous step so, in this case, it would be carlistings. for the project and the Application Name but this convention makes it easier to but it makes it easier to keep track of what you’re doing.

Next, save your project by clicking on the "Save" icon on the Menu. You will be prompted for the location in which to save the project. For the "Save path", use the URL of the Web Server you set up such as http://localhost/myprojects. For the Project Name, use the folder name you just created, which in this case is carlistings. Architect stores all the files for the project there. You do not have to use the same name.

Architect 2.2 and later includes a "Build" button as well as a "Save" button. In earlier releases, clicking the "Save" button rebuilt the entire app, which can take a significant amount of time for a large app. In Architect 2.2, the "Save" button only rebuilds the application pieces that you have modified. Of course, you need to Build the project before releasing it and regularly during the development cycle but using the "Save" button is a fast way to preserve your work without waiting for the entire application to rebuild. Note that, when you first save a new project, only the "Save" button is available.

If you can not save your application, check that

  • Be sure that you have set up your Web Server, created a subdirectory for your projects, and a subdirectory within that directory for this project
  • Be sure that you have permissions to write to that directory

You can view your code at any time from within Architect. Use the Design and Code toggle -- at the top right of the main panel -- to toggle between the graphical design canvas and the code editor.

Set up the initial view

  1. Add a Panel component to the project by searching for panel in the Toolbox and dragging the Panel to the Canvas in the center of the application.

  2. Initial View - After creating the Panel, MyPanel is listed under the Views node in the Inspector. The Initial View indicator appears on the right hand side; position the cursor over it, and Architect should display the message "This component is your Initial View," which means that the Panel will display first when the application runs. An application can have only one Initial View.

  3. Save your project by choosing a save path that is within your web server's webroot. Some common settings here are /Users/<username>/Sites/, C:\Inetpub\wwwroot\, C:\wamp\www\ or /var/www/. Name the project CarListings.

As you set the location where your project is saved, Architect displays the precise path, as shown below.

Note - Sencha Architect stores a project as a directory tree. Everything within the CarListings directory is in the Architect project. For general information on storing Architect projects, see Saving and Sharing Projects.

  1. Preview your project by clicking the Preview button in the Toolbar.

  2. Configure the URL Prefix by configuring the location of your project relative to http://. This prefix maps your project location to the webserver where you just saved it on the filesystem. In our current example, this is http://localhost/CarListings/. (This can vary depending on where you saved your project and your specific environment.)

Click the Preview button, and a browser window launches showing the single Panel you added to the project.

Loading data into a grid

Let's continue by adding a Grid to our Panel and loading data into it.

As you progress through the tutorial, you can see the code for your project at any time. Select a component in the Canvas or Inspector and use the Design/Code view toggle control in the upper right of the Canvas to switch between Design and Code view.

Adding and configuring the grid view

  1. Double click on the title of the Panel and change it to Car Listing.

  2. Change the frame config to true by checking the checkbox in the Config panel.

  3. Select the Panel and click the Flyout Config button (the gear at the top right). Set the layout config to vbox. This will arrange future child components of the Panel vertically.

  4. Drag a Grid Panel from the Toolbox and drop it on the Panel container in the Canvas.
  5. Remove the title bar from the grid by selecting the grid in the Canvas or Inspector and clicking the clear icon (x) to the right of the title configuration in the Config panel.

  6. Change the userClassName configuration for the top-level Panel from MyPanel to CarListings. This changes its name in the Inspector. It also changes the name of the generated JavaScript class in the Ext.define of the underlying source code.

If you followed the above steps properly you should have something that looks like this.

Note. We use vbox layout here because we intend to add more panels in a vertical stack. The above example alone could have been achieved with a single Grid Panel with the frame configuration set to true. Be careful not to nest containers unless it is necessary, since overnesting can cause performance issues in large applications.

Working with data: Models and Stores

If you preview the application now, you see an empty grid without data and the default column headers -- String, Number, Date, and Boolean. This is because we have not bound our grid to a data Store. Let's bind our grid to a new Store and load in information about some sports cars. For a closer look at the data package, see the Ext JS Data guide.

Download and unzip the data files into your project directory. The data folder should be at the same level as your CarListings.xds file.

The application folder structure should look like the following:

CarListings/
|____app/
| |____view/
| | |____CarListings.js
| | |____Viewport.js
|____app.html
|____app.js
|____data/
| |____2004_Porsche_911_Carrera_type_997.jpg
| |____250px-2007_Audi_TT_Coupe.jpg
| |____250px-Audi_S5.jpg
| |____250px-BMW_M3_E92.jpg
| |____250px-Nissan_GT-R.jpg
| |____cars.json
|____metadata/
| |____Application
| |____resource/
| | |____Library
| |____view/
| | |____CarListings
|CarListings.xds

If you open the cars.json file in a plain text editor, you can see the format of the data and the key value pairs. Let's take a closer look at the entry for the Porsche 911. Next, we will be creating a Model to represent this data in Architect.

{
    "img" : "2004_Porsche_911_Carrera_type_997.jpg",
    "manufacturer" : "Porsche",
    "model" : "911",
    "price" : 135000,
    "wiki" : "http://en.wikipedia.org/wiki/Porsche_997",
    "quality" : [{
        "name" : "overall",
        "rating" : 1
    },{
        "name" : "mechanical",
        "rating" : 4
    },{
        "name" : "powertrain",
        "rating" : 2
    },{
        "name" : "body",
        "rating" : 4
    },{
        "name" : "interior",
        "rating" : 3
    },{
        "name" : "accessories",
        "rating" : 2
    }]
}

Note that you must manually configure IIS with a JSON MIME type in order to serve .json files. See the Installation and Setup guide for pointers to instructions.

Create Model

Let's create a Model with the proper fields (keys) that we would like to know about the car entity.

  1. Click the Add button ("+") at the top right of the Inspector and then click Model. A new Model will be created named MyModel and will appear under the Models node of the Inspector.

  2. Select the newly created Model and set its userClassName config to CarData.
  3. Add manufacturer, model, price, wiki, img and quality fields. Search for fields in the Config panel. Click the Add button ("+"), and when prompted to Enter one or more field names, type in each field name separated by commas, as shown below. Then click Finish or press Enter.

If you followed the above steps properly you should have something that looks like this.

Create Store

Now that we have a Model representing the data structure, we can create a Store that uses the CarData Model.

  1. Click the Add button ("+") at the top right of the Project Inspector and select Json Store under the Store submenu. A new Store is created named "MyJsonStore". It appears under the Stores node of the Inspector. Note - A JsonStore automatically adds a JsonReader and makes the assumption that we will load our data in JSON format. Other formats such as XML or Array are also supported.

  2. A warning icon should appear to the right-hand side of the newly created Store in the Inspector, indicating that there is a problem with the Stores configuration. Clicking on the icon will provide more detailed information as to why the configuration is invalid.

  3. Select the Store in the Inspector and set the Model config to CarData. The warning icon should go away.
  4. Select the Store and set its userClassName configuration to CarDataStore. The Store's name should update in the Inspector.
  5. Select AjaxProxy underneath the CarDataStore and set its URL to data/cars.json. Note that this URL is relative to your project. Your URL prefix must be set properly to load data within Architect.
  6. Right-click CarDataStore and click Load Data. After loading the data you should see an eye icon next to your Store, like this:

    Note - The Load Data feature in the context menu becomes enabled when the url configuration of the proxy or data configuration of the Store has been set.
  7. Positioning the cursor over the eye icon displays the number of records that have been loaded into your Store. Note that only 1 record was loaded. Looks like we may have made a mistake.

  8. Click the eye icon to see the response data. Looking at the response data, you can see that individual entities are within a data array. This is why only one record was loaded. Select the JsonReader in the Inspector and set its root config to data. Your Store has now been properly configured.

  9. Right-click CarDataStore and click Load Data again. Because we made changes to the stores configuration that would affect data loading, Architect has cleared the data cache.
  10. Finally, set the autoLoad configuration on the Store to true so that we do not have to programmatically load it.

Binding the grid to the Store

Next, we bind the grid to the Store. Because the grid is bound to the Store, any time records inside of the Store change, the grid automatically updates itself to reflect the changes. Additionally, if any records are added to or removed from the Store, they are also reflected in the grid.

  1. Select the Grid Panel in the Inspector. Set its store configuration to CarDataStore. Notice that all the data disappears because our mappings are not set up yet.
  2. Right-click the Grid Panel in the Inspector and select Auto Columns. This will automatically map your grid's columns 1-to-1 with the associated Model (or Store's) data fields.

If you followed the above steps properly, you should have something that looks like this.

Save or Build your application and click on Preview. You can see your grid and its data in your operating systems default browser.

If you see a blank screen and/or a blank grid in your browser, ensure the following:

  • No errors appear in the browser JavaScript console
  • Ext JS is being loaded properly
  • the autoLoad config is set on the Store.

You have completed the first major step to building the CarListings application.

Connect grid to a detail panel

Next, we add a detail panel to display additional information about each entry in the grid as a user selects individual records.

Adding the detail panel

  1. Select the top-level CarListings Panel. Resize the Panel by dragging the blue handle at the bottom right of the Panel in the Canvas so that it is big enough to accommodate a detail panel. Make it approximately double the height.

  2. With the CarListing panel still selected, search for panel in the Toolbox. Double click Panel to add a new Panel to the currently selected item in the Inspector. This is an alternate and frequently faster way of adding components rather than dragging and dropping.

  3. Select the newly added Panel. Search for the tpl config and click the Add button ("+") to its right. All components have a tpl config, which accept an XTemplate. Refer to the XTemplate reference to learn more about the templating library.

  4. Once the tpl config has been added, click the forward arrow icon to its right to open the code editor in the center stage. Paste the following template into the code editor:

      <img src="data/{img}" style="float: right" />
  Manufacturer: {manufacturer}<br>
  Model: <a href="{wiki}" target="_blank">{model}</a><br>
  Price: {price:usMoney}<br>

The curly brackets with names in them represent variables that conveniently correspond to the fields in our CarDataModel. If you followed the above steps properly, you should see something that looks like this in the Design view.

Note These steps are order dependent. When containers have a vbox or hbox layout set, their newly added child items automatically get their flex settings set to 1. If you add the child items before setting the layout to vbox, you need to manually set each of the child items flex settings to 1.

Updating the detail panel

Let's add the code that glues together the two panels via an Event Binding. When a user chooses a particular entry in the grid, we want the application to show the detailed information below it in the detail panel using the template that we just set up.

  1. Select the panel you added last (the one with the template) and set its itemId configuration to detailPanel. This lets the application easily retrieve a reference to this specific panel within the CarListings class.

  2. Select the grid panel in the Inspector, search for the Event Binding config, and click the Add button ("+") to its right. Choose the select event and click Finish or press Enter.

  3. Click the arrow icon to select the new event binding. Architect has already generated a sensible method name for the new function but you can change this with the fn config if you would like.

  4. Double-click the event binding in the Inspector to display Code view for this event handler. Notice that we will only be writing the method body. Function arguments have already been defined for us.

  5. Paste the following code into the event handler.

     // grab a reference to the detailPanel via itemId
 // the # in front of the id indicates that we would like to grab a reference by
 var detailPanel = this.child('#detailPanel');
 // update the detailPanel with data
 // this will trigger the tpl to become updates
 detailPanel.update(record.data);

Note Event bindings run in the context of the class in which they are defined. this. will refer to the top-level panel.

Note In some very rare exceptions this. will not refer to the top-level class, such as when adding an initialize or painted event handler to a component that resides in a container in a project targeting the Sencha Touch framework.

Important Note Notice that we used the itemId config when providing an identifier for the detailPanel rather than the id configuration. The itemId configuration must be unique within a particular container but has no restrictions in the global space. The id config on the other hand must be globally unique. If you use the id config, you can have only one instance of that component available at any given time. Architect promotes code reuse and using multiple instances of components through advanced features like Linked Instances.

Save the project and preview it in the browser. When you select a particular record in the grid, additional information should appear in the bottom panel.

Add a Chart

To start the final leg of this project, we will add a Chart to display the quality of a selected car.

Modeling ChartData

  1. Add a second Model to the Inspector. Set its userClassName config to CarChart.

  2. Examine the contents of the quality field as shown below. We are already loading the quality field into the CarStore from cars.json. We are now creating an additional Model to hold its contents specifically for charting.

      "quality" : [{
      "name" : "overall",
      "rating" : 1
  },{
      "name" : "mechanical",
      "rating" : 4
  },{
      "name" : "powertrain",
      "rating" : 2
  },{
      "name" : "body",
      "rating" : 4
  },{
      "name" : "interior",
      "rating" : 3
  },{
      "name" : "accessories",
      "rating" : 2
  }]

  3. In the Config panel, add two fields to the CarChart Model that map directly to each key defined in the quality field. Create two fields in the Model named name and rating. These fields will map directly to cars.json.

  4. Create a Store and set its userClassName to CarChartStore. Directly clicking the submenu Store creates a plain Store without a proxy or reader.

  5. Link the CarChart Model to CarChartStore by setting the model config on the Store to the CarChart Model.

Adding the Chart

  1. Resize the CarListings panel if you need additional room for the chart to fit below.

  2. Drag an additional Panel onto the CarListings Panel. Drop it on the title of the Panel or the Views node in the Inspector. Because the grid is stretched to the size of the top-level Panel, you cannot drop it in the center. Alternately, you can select the top-level Panel and then double-click Panel in the Toolbox.

  3. Drag a Column Chart onto the third Panel (the last Panel you added, which should be the bottom-most Panel in the Canvas).

  4. Select the newly created Panel in the Inspector. Click its Flyout Config button (gear on top right) in the Canvas, and set its layout to fit. This stretches the chart in both directions to fit its parent Panel.

  5. Clear the title configuration of both the middle and bottom panel.

  6. Add margins around the middle and bottom panels. Select the middle Panel (detailPanel) in the Inspector, type margins into the filter field. Now set margins to "5 0 0 0". (Be careful to set the margins configuration for Ext.layout.VBoxLayout and not the margin configuration for Ext.Abstract.Component.) Add the same margins to the bottom Panel (chartPanel).

  7. In the Canvas, click the Flyout Config button on the Chart and select CarChartStore to bind the Chart component to the JSON Store. Note This makes the chart disappear and that's OK for now. We only care that it shows up when a user selects a record.

  8. Select Category Axis under the chart in the Inspector to edit the chart's x axis. This Category `Axis displays the categories for the quality of the cars in the CarListing app. Make the following changes:

    • Change its title configuration to Quality.
    • Change its fields configuration from x to name. The name field provides values for the x axis of the chart -- the quality categories.

  9. Select Numeric Axis under the chart in the Inspector to edit the chart's y axis. The Numeric axis will display the values for each car quality category. Make the following changes:

    • Change its title configuration to Score.
    • Change the fields configuration from y to rating. This configuration determines what is rendered on the axis but does not actually influence the columns rendered on the chart.

    • Change the value of the maximum configuration to 5, which will be the maximum value for the y-axis.
    • Change the value of the minimum configuration to 0, which will be the minimum value for the y-axis. This is important because it causes numbering on the y axis to begin at 0 rather than at the lowest-reported value.
    • Change the value of the majorTickSteps configuration to 4. This determines how many markers are in between the minimum and maximum.

  10. Select MyColumnSeries under the chart in the Inspector. In the Config panel, find the label config and change it to the following:

      {
      display: 'insideEnd',
      field: 'rating',
      color: '#333',
      "text-anchor": 'middle'
  }

    Note - We had to quote the key text-anchor because it has a - in the key name.

  11. Make the following additional changes to the MyColumnSeries. These configurations determine the actual columns that are rendered as a series on the chart.
    • Change the xField configuration to name.
    • Change the yField configuration to rating.
  12. Set the itemId configuration of the chart to qualityChart so that we can access it via code.

  13. Add the following code in onGridpanelSelect (the event handler added to the grid earlier in the tutorial) to update the charts Store when the user selects a record.

      // grab a reference to the qualityChart, notice we use down here instead of child
  // because down will go down the container hierarchy at any depth and child
  // only retrieves direct children
  var chart = this.down('#qualityChart');
  // get the quality field out of this record
  var qualityData = record.get('quality');
  chart.store.loadData(qualityData);

For more information about the Ext JS Charting API, see the Ext.chart.Chart reference page.

Run the application

Let's have a look at the application running in a browser.

When you first save a project, Architect puts all the files needed to run it -- including .html and .js files as well as .js files for Controllers, Models, Stores, and Views -- in the directory indicated when you first saved the project. Every time you build again, Architect updates all the files automatically. Older versions of Architect required you to export a project before you could run it, but that is no longer the case.

To see the final application, launch a browser or simply click Preview and the application UI should display. Click on a grid row, and the car detail should display along with the car image and the chart showing the car quality data for various categories.

Files for this article