Build Your First Mobile App

Contents

Preliminary steps
Begin your Architect project
Build views to define the UI
Build a Model and a Store to Define the Data
The Controller
Add a style sheet
Have a look at your hard work
What if it doesn't work?
Additional steps

This guide shows you how to build an example mobile app using the Sencha Touch framework and the Sencha Architect development tool.

The application we will develop is called CityBars. It helps users find local watering holes based on information from the Yelp API. Once you have completed the steps detailed here, you will have a working mobile app based on the Sencha Touch framework. You should also have a basic understanding of how to use Sencha Architect to start building your own mobile apps.

An archive of this project and the accompanying CSS file are part of the examples released with Architect:

The .xda file for the completed project
The accompanying CSS file.

Note that this is a skeletal application to familiarize you with the Sencha development tools. We invite you to build out the app further -- and, if you do, share your results by posting them to the Architect forum.

Preliminary steps

Before getting started, do the following:

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.
Read through that document to familiarize yourself with the basic concepts of Architect and the various components of the Architect display.
Register in the Yelp Developer Program and get your own key; this is free. You must insert your own key in the application in order to load data; see "The Controller" section below for more details.

Begin your Architect project

When you begin a project, you should:

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 Sencha Touch 2.1.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

In order to preview your project, you must point Architect to the URL of the web server. You can set this up now or wait until you are ready to preview your project.

To do this, in Architect 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 the project 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 in the Application Node. To do this:

Click on "Application" at the top of the Inspector window located on the upper right side of the screen
Click in the Config window and type the name you want to use for the application in the box that is displayed
Click on the + sign next to that box..

For this example, use the following:

name: CityBars

It is traditional to use a camel-case name here.

For more details, see Application node configuration notes.

Save your application

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 file system location that maps to the URL of the Web Server you set up such as http://localhost/myprojects. For the "Project Name", enter a meaningful name; this is the name of the directory where Architect stores all the files for the project.

The convention is to use a lowercase version of the Application Name you assigned in the previous step so, in this case, name the folder citybars. You can use any name you choose for the directory but this convention makes it easier to to keep track of what you’re doing. which in this case is citybars.

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 the following:

Ensure that you have created a subdirectory for your projects and that the name matches the name you gave exactly; remember that this name is case sensitive.
Ensure that you have permissions to read and write to the directory you specified.

You can view your code at any time from within Architect. Use the Design and Code views above the left edge of the Canvas to toggle between the graphical design display and the code.

Build views to define the UI

Start by building the visual UI of the citybars application.

Now click on "Views" under the "Everything" list in the Toolbox to display a list of all the possible views. We will create a main navigation view, list view, and detail view.

Add a Navigation view to the project by selecting it from the "Views" menu and dragging it onto the Canvas. In Config, set the following:

userAlias: mainnav
userClassName: MainNav

Click the "Save" icon on the Menu Bar to save your work. You should do this frequently.

List view

Add a Container to the project as a top-level component. Set the following configs:

userAlias: listcontainer
userClassName: ListContainer
layout: fit

Add a List as a child of the container (ListContainer) you just created. Set the following configs for List:

id: dataList
itemTpl: <img class="photo" src="{photo_url}" width="40" height="40"/>{name}<br/><img src="{rating_img_url_small}"/> <small>{address1}</small>

For more information about the tpl configuration and templates, see the Ext.Template page.

Create a linked instance of the container (listcontainer) by dragging it onto the MainNav view in the Inspector and selecting the Link option from the Copy Component dialog box that appears. The Inspector shows the container under MainNav as follows:

Select the linked instance of the container (listcontainer) under MainNav and set the following configs:

title: City Bars

Detail view

Select the linked instance of the container (listcontainer) under MainNav and set the following configs:

title: City Bars

Detail view

Add a Tab Panel as a top-level component and set the following configs:

userAlias: detailpanel
userClassName: DetailPanel

Find the Tab Bar Config property in Config and add a tab bar under the tab panel (DetailPanel) by clicking the add button ("+"). Move the tab bar above the three tabs by right-clicking it in the Inspector and selecting Move Up three times. Set the following configs for the Tab Bar:

pack: center
docked: top
ui: light

Contact tab

Select Tab 1 in the Inspector. Note that this is a container (Ext.Container). Set the following configs:

id: contact
title: Contact

In the Inspector, drag Tab 2 and Tab 3 into the contact container to make them children of contact. We are simply reusing containers that otherwise would be deleted and re-added. The Inspector should look like this:

Select MyContainer2 in the Inspector and set the following configs:

id: info
layout: hbox
padding: 10
tpl: <img class="photo" src="{photo_url}" width="100" height="100"/>;<h2>{name}</h2><div class="info">{address1}<br/><imm src="{rating_img_url_sall}"/></div>

Add a Component as a child of info (note that it is added as MyComponent in the Inspector) and set these configs:

id: photo
height: 100
width: 100
tpl: <img class="photo" src="{photo_url}" width="100" height="100"/>

Add a second Component as a child of info and set the following configs:

id: data
padding: 10
tpl: <h2>{name}</h2><div class="info">{address1}<br/><img src="{rating_img_url_small}"/></div>

Select 'MyContainer3' under the contact container and set the following configs:

layout: hbox
pack: center

Add a Button to the container you just added and set the button's configs as follows:

text: Call
width: 100

Add a Spacer to the just-added container and set the spacer's width config to 57.

Add another Button to the just-added container and set the button's configs as follows:

text: More
width: 100

In this tutorial, we set up the buttons but do not assign any functionality to them. You are invited to add functionality to the buttons; if you do, please share your results by posting them to the Architect forum.

Map Tab

Add a Map to the DetailPanel sibling to contact and set these configs:

id: detailMap
title: Map
height: Be sure this remains unset.

Save your project.

Build a Model and a Store to Define the Data

Now that we have defined Views for the application, we need to provide some data to display in those Views. The Controller will query the Yelp! database and create a Store, which in this case is a JsonP file that contains the relevant information. The Model defines how this data is represented by your application.

The Model

First, we add a Model that is used to represent the data objects used in the application; think of it as sort of a schema definition for the data. Set its userClassName config to Business.

Note that you can create several of the fields at once by supplying a comma-separated list of fields to userClassName. See Stores and Models for more information.

Add 12 fields to the Model and name them as follows:

id
name
latitude
longitude
address1
address2
address3
phone
state_code
mobile_url
rating_img_url_small
photo_url

Note that, in this case, the Model contains a number of fields that we are not using. This is legitimate for our purposes; those fields might be used for other Views within the application.

For a simple application like this one, using a Model rather than just directly accessing the data in the Store may seem cumbersome but in real applications, the Model supports associations (BelongsTo or HasMany), ID Generators (Sequential or UUID), a variety of Proxies (Ajax, Direct, REST, and so forth), and Validations (Exclusion/Inclusion, Format, Length, and so forth) and so offers very powerful ways to manage data within the application.

The Store

The Store is a file that serves as a client-side data cache for the UI components. In this case, we are using a JsonP Store, which is similar to a Json Store but it can retrieve Json data from a domain other than the one in which your application is running. For more detail, see the API documentation for Ext.data.JsonPStore. You can also create Array Stores, XML Stores, and Tree stores

Add a JsonPStore and set its configs as follow:

userClassName: BusinessStore
storeId: BusinessStore
model: Business.

Note that the value of model matches the value assigned to userClassName for the Model; this associates the Store with that Model. The two values must be identical and they are case sensitive; one of the most common mistakes people make is having different values for the Model's userClassName config and the Store's model config.

Select MyJsonReader in the Inspector and set its rootProperty config to businesses.

Note that a JsonPStore is automatically configured with an EXT.data.reader.Json and an Ext.data.proxy.JsonP

The Controller

A Controller implements the actual functionality for the app; in this case, it queries the Yelp database for a list of bars with their locations and saves that information into the JsonP Store that we defined above.

To add a Controller, select "Behaviors" from the "Everything" comlumn in the Toolbox, then select "Controller" for the list that is displayed. Set its userClassName to Business, then add a launch function, and choose "Code" in the menu bar or double-click the Controller in the Inspector to open the code editor. Insert the following code:

var me = this;

Ext.Viewport.setMasked({ message: 'Loading...' });
// get the location, then...
me.getLocation(function (location) {

    // then use Yelp to get the businesses
    me.getBusinesses(location, function (store) {

        // then bind data to list and show it
        me.getDataList().setStore(store);

        Ext.Viewport.setMasked(false);
    });
});

See the comments for an explanation of what the code does.

Next, add four controller references. In Config, find the References property. Click the add button on the right under Value ("+") to add the first controller reference. When prompted name it dataList and set its selector to #dataList. Add three additional controller references using the same technique, as follows:

Name the second reference listCard and set its selector to #listCard.
Name the third reference mainNav and set its selector to mainnav.
Name the fourth reference detailCard and set its selector to detailpanel.

Note: the first 2 references use an id to query -- #listCard -- and the last 2 use an alias -- mainnav.

Add a function to the Controller and set its configs as follows:

fn: getLocation
params: callback

Double-click the function in the Inspector, and insert the following code into the code editor:

if (navigator && navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(function(position) {
        callback(position);
    }, function(error) {
        // give a warning for error
    });
}

Add another function and set the configs:

fn: getBusinesses
params: location, callback

Double-click the getBusinesses function in the Inspector, and insert the following code into the code editor. This is the code that obtains data for the app from Yelp:

// NOTE ABOUT YELP KEY
// You must use your own yelp key, available by registering (for free) with Yelp:
// http://www.yelp.com/developers/getting_started/api_overview
// (in this app, we use the Review Search API v1.0)
var store = Ext.data.StoreManager.lookup('BusinessStore'),
    yelpKey = '', // enter your yelp key here
    url = 'http://api.yelp.com/business_review_search' +
    '?ywsid=' + yelpKey +
    '&term=Bars' +
    '&lat=' + location.coords.latitude +
    '&long=' + location.coords.longitude;
store.getProxy().setUrl(url);
store.load(function() {
    callback(store);
});

Note that you need to use your own Yelp key, available by registering (for free) with Yelp. In this example, we use the Review Search API v1.0.

Now complete the Controller by adding a controller action to it. Add the action in the Config panel, choosing Ext.dataview.List for the target type and itemtap for the event.

controlQuery: #dataList
fn: onListItemTap

Double click the action (itemtap onListItemTap) in the Inspector to open the code editor and add the following code:

var me = this,
    map,
    lat,
    lon,
    loc,
    marker,
    info, details;

if (record) {

    details = Ext.create('CityBars.view.DetailPanel', {
        title: 'Details'
    });

    // set the map
    map = details.child('#detailMap');
    lat = record.get('latitude');
    lon = record.get('longitude');

    map.setMapOptions({
        zoom: 18
    });

    // fixes a bug in touch 2.1.1
    map.element.un('painted', 'setMapCenter', map);

    map.setMapCenter({
        latitude: lat,
        longitude: lon
    });

    // set the info
    info = details.child('#contact').child('#info');
    info.child('#photo').setData(record.data);
    info.child('#data').setData(record.data);

    me.getMainNav().push(details);
}

An important concept to grasp is that the View never calls the Controller to invoke methods. Instead, the View generates an event and the Controller responds to that event. After you build a View, you associate it with a Controller by using a controller action that is set using the Config panel.

For more information, see Controllers

Add a style sheet

To improve the look of the app, giving it an attractive grey theme, you need to add a style sheet. To do this, in the Inspector, click the add button ("+") and choose Resource-->CSS Resource. The Resources node will display a new css resource, as shown here:

Select it there and set its url config to citybars.css.

Download and unzip the citybars.css. Place the citybars.css file in the citybars folder you set up at the beginning of the project to store your app. Optionally, you can create a styles directory within the folder and set the url config to styles/styles.css.

Have a look at your hard work

View the application in the Inspector and be sure it now has the following:

Models: Business
Store: BusinessStore
Views: MainNav, ListContainer, DetailPanel

Now save your project one last time. Point Architect to the URL Prefix of the web server where the application is located (see instructions at the beginning of this guide), and open the app.html file for it. Here's what it should look like.

You can also deploy the project to a hosted location and view it there. You can then navigate using your browser to view the application. Chrome should work fine, or view it through a WebKit browser on a mobile device.

What if it doesn't work?

If the app does not work, check the following:

You must be using a Webkit-aware browser like Chrome or Safari
Be sure that you have your own Yelp key and code it into the Controller of your application
Check for typos in the userAlias and *userClassName** configurations for the views you defined and the code that calls them.
Check that the item IDs are set correctly.
Architect protects you against many common typos you can make in JavaScript such as missing semicolons but look carefully at what you typed.

If you are really baffled, you can download the completed project from the locations linked at the beginning of this article and see where your code differs to find the problem.

Additional steps

Additional steps are required to build and package your application for production. See Publishing, Packaging, and Simulating a Project for more information.

Build Your First Mobile App

Preliminary steps

Begin your Architect project

Launch Architect

Point Architect to the URL Prefix of the Web Server

Name your application

Save your application

Build views to define the UI

Main navigation view

List view

Detail view

Detail view

Build a Model and a Store to Define the Data

The Model

The Store

The Controller

Add a style sheet

Have a look at your hard work

What if it doesn't work?

Additional steps