Jorge is the author of three software development books: "Building a Sencha Touch Application", "How to Build a jQuery Mobile Application", and the "Ext JS 3.0 Cookbook". He runs a software development and developer education shop that focuses on mobile, web and desktop technologies. Jorge is a DZone MVB and is not an employee of DZone and has posted 44 posts at DZone. You can read more from them at their website. View Full User Profile

How to Create a Sencha Touch 2 App: Part 1

02.20.2012
| 13578 views |
  • submit to reddit

In this series we will create the Sencha Touch 2 version of the Notes Application, an application that allows its users to take notes and store them on the device running the app. Along the way, we will dive into the following areas:

  • The building blocks of a Sencha Touch application.
  • How to implement navigation in an application with multiple views.
  • How to edit data using Sencha Touch form elements.
  • How to render information using lists views.
  • How Sencha Touch stores data with HTML5 local storage.

In the first part of the series, we are going to define the features of the application along with its look and feel, and we will start building its main screen.

The Features Of The Notes App

We want our app to its give users the following abilities:

  • Create notes.
  • Edit existing notes.
  • Delete notes.
  • Render a list of the notes currently saved on the device.
  • Persist notes on the device running the application, across browser sessions.


The Application’s User Interface

The main screen of the Notes App will render a list of the existing notes. We will name this View NotesListContainer. Here is its mockup, depicting the Sencha Touch Components we will use to build it:


As you can see, the NoteListContainer View is an Ext.Container Component that hosts a Toolbar Component and a List Component. We will treat the Ext.Lit as a separate View – the NotesList View.

A second screen, the NoteEditor View, will allow users to create, edit and delete notes. This view will look just like the following mockup:


The NoteEditor View is an Ext.form.Panel Component that contains a couple of Toolbars and the form elements needed to edit a note’s properties.

We also need a mechanism for our users to navigate to these screens. As each Sencha Touch Application gets a Viewport instance upon launch, we will use the Viewport to take care of rendering the NotesListContainer and NoteEditor Views, as well as manage the navigation between them:


The Viewport is ideal for this task. It extends from the Container Class, and it defaults to a full screen Card layout, which is what we need in the Notes App.

Organizing A Sencha Touch Application In Directories And Files

With the application features and user interface already defined, we can begin writing the source code. We will organize our source code in a directories tree like this:

We will place our files under the NotesApp directory, with the Application’s setup code in the app.js file.

We will also have an app directory, in which we will have the controller, model, profile, store, and view directories. The controllers, models, profiles, stores and views used in the Application will reside in these directories.

The index.html file will launch the app. In it, we will include the Sencha Touch framework, along with our application:

<!--<!DOCTYPE html>
<html>
<head>--> <!--Remove comments!-->
    <title>My Notes</title>
    <link href="../Lib/ST2/resources/css/sencha-touch.css" rel="stylesheet" type="text/css" />
    <script src="../Lib/ST2/sencha-touch-debug.js" type="text/javascript"></script>
    <script src="app.js" type="text/javascript"></script>
<!--</head>
<body>
</body>
</html>--> <!--Remove comments!-->


Note that we are keeping the framework files in the Lib/ST2 folder:


Creating a Sencha Touch Application Instance

Our first step in the app.js file will consist of creating an instance of the Sencha Touch Application Class. We are going to define an Application instance as follows:

Ext.application({
    name: "NotesApp",
    launch: function () {

        console.log("App launch");
    }
});


The application() method loads an Application instance after the page is ready, and it uses the supplied config object to configure the app. In our case, we are simply giving the app a name, and defining the launch() function.

One important role of the application() function is to trigger the load of any Models, Views, Controllers, Stores and Profiles the application depends on. This happens automatically when we define these dependencies using the models, views, controllers, stores and profiles config objects. We will see this feature in detail in this tutorial.

The launch() function is invoked as soon as the app loads its dependencies and instantiates its Controllers.

If we navigate to this page on the emulator, we should see something like this:


Extending Classes In Sencha Touch

We already know that the main screen of our application will render the list of notes currently cached on the device. To build this screen, we will use an instance of the Container Class, which will host a Toolbar and a List:

First, we will create the NotesListContainer.js file in the view directory:

In the NotesListContainer.js file, we will then define the NotesListContainer View like so:

Ext.define("NotesApp.view.NotesListContainer", {
    extend: "Ext.Container",
    config: {
        items: [{
            xtype: "toolbar",
            docked: "top",
            title: "My Notes",
            items: [{
                xtype: "spacer"
            }, {
                xtype: "button",
                text: "New",
                ui: "action",
                id:"new-note-btn"
            }]
        }]
    }
});


Here we are using Ext.define() to define an extension to the Ext.Container class. We have added a Toolbar instance to this view, docked to the top. The Toolbar will in turn contain one Button, the New button, which will allow our users to activate the NoteEditor View and create a new note.

Pay attention to how we included a Spacer Component before the button. This will place the New button on the right end of the Toolbar. Also, how the ui=”action” config allows us to give the button a distinctive look, indicating that it represents the default button on the view.


Specifying Application Dependencies In Sencha Touch

With the NotesListContainer Class defined, it is time to make the Application aware of it. Back in the app.js file, we are going to add the views config to the application() function:

Ext.application({
    name: "NotesApp",
    views: ["NotesListContainer"],

    launch: function () {

        var notesListContainer = Ext.create("NotesApp.view.NotesListContainer");
        Ext.Viewport.add(notesListContainer);
    }
});


We inform the Application that it has a dependency on the NoteListContainer View by using the views config:

views: ["NotesListContainer"]


The Application Class expects its models, views, controllers, stores and profiles to exist in the app/model, app/view, app/controller, app/store, and app/profile directories. With this convention, we can define models, views, controllers, stores and profiles using the last part of their names, as we do here. If we use a different directory structure, we will need to refer to them using their fully qualified names.

Time to check out how the View looks. On the emulator, you should see something similar to this:

Very nice, right? Let’s move on to the Controller. We need a Controller Class to be in charge of handling user input, modifying the models, and governing the transitions between views.

Creating Sencha Touch Controllers

Let’s define a very simple Notes Controller Class. We will place this Class in the Notes.js file, which we will add to the controller directory:

And this is the Controller’s definition:

Ext.define("NotesApp.controller.Notes", {
    extend: "Ext.app.Controller",
    launch: function () {
        this.callParent();
        console.log("launch");
    },
    init: function () {
        this.callParent();
        console.log("init");
    }
});

Controllers contain a couple of functions, init() and launch(), that run at different moments during the Application’s startup process. The init() function is invoked by the framework before the Application’s launch() function. The Controller’s launch() function is invoked after the Application’s launch() function runs.

We will make the Application aware of the Notes Controller Class by adding this Controller to the app’s controllers config:

Ext.application({
    name: "NotesApp",
    controllers: ["Notes"],
    views: ["NotesListContainer"],

    launch: function () {

        var notesListContainer = Ext.create("NotesApp.view.NotesListContainer");
        Ext.Viewport.add(notesListContainer);
    }
});

As we already know, having the Notes Controller Class listed in the controllers config will cause the Application to automatically instantiate and keep a reference to this Controller.

How To Handle View Events In a Sencha Touch Controller

At this point we have our Controller set up, and we are ready to start adding features to it. The first thing the Notes Controller needs to do is handle taps on the New button. We can accomplish this by making the following modification to the Controller’s definition:

Ext.define("NotesApp.controller.Notes", {
    extend: "Ext.app.Controller",
    config: {
        refs: {
            newNoteBtn: "#new-note-btn"
        },
        control: {
            newNoteBtn: {
                tap: "onNewNote"
            }
        }
    },
    onNewNote: function () {
        console.log("onNewNote");
    }

    // init and launch functions omitted.
});

Notice the change? Exactly – the refs and control configurations. They are the foundation of the mechanism by which a Controller acquires references to the Components in the app, and defines event handlers for them.

Refs give the Controller the ability to find Components in the app. They use the ComponentQuery Class, which retrieves components using a CSS selector-like syntax. I will not go into the details of ComponentQuery in this article, but I highly recommend that you take some time to study it.

In the Notes Controller, we use the newNoteBtn ref to create a reference to the Component whose id is #new-note-btn. This is the New button.

refs: {
    newNoteBtn: "#new-note-btn"
}

Based on this ref, the framework generates a getter function that we can use to work with the New button reference if we need to. Ref-derived getter functions are named following a simple format, consisting of the word get and the capitalized name of the ref in question. In our case, the name of the function will be getNewNoteBtn().

Refs also give us the ability to instantiate the components they reference if such components do not already exist. Although we are not taking this approach in our app, I recommend that you study these features. They are important, especially if you will be building large applications where you cannot afford or do not need to instantiate all the application’s components upon application launch.

The control config allows us to define event handlers for any of the Application’s Components. We can use refs or ComponentQuery selectors to define event handlers within control. In the Notes Controller, we are using the newNoteBtn ref to define a tap handler for the New button:

control: {
    newNoteBtn: {
        tap: "onNewNote"
    }
}

Obviously, we also need to define the handler function, which we do further down in the Controller’s source:

onNewNote: function () {
    console.log("onNewNote");
}

The onNewNote() function is simply writing a message to the console, but we will soon add to it the code that will open the NoteEditor View.

Let’s take a moment to check the application on the emulator. In particular, what happens when we tap the New button. If a tap occurs, the console output should display the message we just added in the onNewNote() handler:

One important takeaway from this tutorial is that when you need your Controller to handle a particular event on a Component, you can follow the following steps:

  1. Create a ref for the Component.
  2. Create an entry for the ref in the Controller’s control config.
  3.  Use the entry in the control config to specify the handler for the events in which you are interested.

Next Steps

We are going to end this first part of the tutorial taking a minute to recap what we have done so far.

After defining the features and the user interface of the application we will build, we started to become familiar with how Sencha Touch works. We learned how to create the directories for the app, and how to create an instance of the Application Class.

We also created the first version of the Application’s main View, which we named NotesListContainer, and started working on the Notes Controller instance that will manage the interactions between the different parts of the Application.

In the next chapter of this series we will continue working on the Application’s main View and its child elements, as we need to create the List that will render the notes cached on the device.

Stay tuned!

Downloads

Download the source code for this article: NotesApp-1.zip

 

From http://miamicoder.com/2012/how-to-create-a-sencha-touch-2-app-part-1/

Published at DZone with permission of Jorge Ramon, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Paul Shezier replied on Fri, 2012/04/13 - 2:57pm

Hi Jorge, when is the 2nd part coming out? I love your tutorials and I’m really depending on the stores part to make my move to Sencha Touch 2. Cheers!

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.