MiamiCoder

Building a jQuery Mobile Application, Part 4

Jorge — Sun, 15 Jan 2012 16:49:50 +0000

In this fourth part of my series on how to build a jQuery Mobile application, we are going to complete the following tasks:

Implement the behavior of the app when a user tries to save an invalid note.
Implement the ability to delete notes.
Create and apply a custom theme swatch, to change the look of one of the application’s dialogs.

Getting Ready to Validate a Data Model

In the previous chapter of the series, we decided that we are going to consider that a note is valid when it has a title, and we are not going to force our users to enter the note’s narrative before they can save the note. We defined this behavior through the isValid() function of the NoteModel module:

Notes.NoteModel.prototype.isValid = function () {
    "use strict";
    if (this.title && this.title.length > 0) {
        return true;
    }
    return false;
};

We also left an empty branch in the onSaveNoteButtonTapped() function of the Controller module, where we need to add the code that will inform our user that her note is invalid. Here is the function as we originally created:

var onSaveNoteButtonTapped = function () {

    // Validate note.
    var titleEditor = $(noteTitleEditorSel);
    var narrativeEditor = $(noteNarrativeEditorSel);
    var tempNote = dataContext.createBlankNote();

    tempNote.title = titleEditor.val();
    tempNote.narrative = narrativeEditor.val();

    if (tempNote.isValid()) {

        if (null !== currentNote) {

            currentNote.title = tempNote.title;
            currentNote.narrative = tempNote.narrative;
        } else {

            currentNote = tempNote;
        }

        dataContext.saveNote(currentNote);

        returnToNotesListPage();

    } else {
        // TODO: Inform the user the note is invalid.
    }
};

Before we complete this function, we need to define what UI elements we will use to inform the user that her note is invalid. We can accomplish this with a jQuery Mobile dialog. In our case, we want to create a very simple dialog, made of a header and a short message to explain our users what is happening:

How to Create a Dialog With jQuery Mobile

One of the ways you instruct the framework to display a page as a dialog is using the data-role=”dialog” attribute. We will follow this approach, defining an Invalid Note dialog in the index.html file as follows:




Wait!

Enter a title for this note.

We will insert this markup right after the Note Editor page in the index.html file. A detail I don’t want you to miss is how we use the data-theme=”e” attribute to change the appearance of the dialog. Applying the E swatch to the dialog helps give it more of a warning look.
With the dialog in place, we need to go in the controller module and add an identifier for it:

var invalidNoteDlgSel = "#invalid-note-dialog";

This identifier will allow us to activate the dialog in the onSaveNoteButtonTapped() method of the controller like so:


var onSaveNoteButtonTapped = function () {

    // Validate note.
    var titleEditor = $(noteTitleEditorSel);
    var narrativeEditor = $(noteNarrativeEditorSel);
    var tempNote = dataContext.createBlankNote();

    tempNote.title = titleEditor.val();
    tempNote.narrative = narrativeEditor.val();

    if (tempNote.isValid()) {

        if (null !== currentNote) {

            currentNote.title = tempNote.title;
            currentNote.narrative = tempNote.narrative;
        } else {

            currentNote = tempNote;
        }

        dataContext.saveNote(currentNote);

        returnToNotesListPage();

    } else {
        $.mobile.changePage(invalidNoteDlgSel, defaultDlgTrsn);
    }
};

Note that we are making the dialog the active page using the $.mobile.changePage() method, which you can use to trigger page changes programmatically. This function takes a reference to the page in question, as well as the transition you want to use when bringing the page into view.

Instead of passing an inline-defined transition, we are going to define a default transition, which we will use for all the dialogs in the application. We will use the following on-liner to create defaultDlgTrsn right at the beginning of the controller module:

var defaultDlgTrsn = { transition: "slideup" };

All right, time to check how the dialog looks. Start your favorite WebKit browser or emulator, and try to save a note with a blank title. You should see the Invalid Note dialog become active:

The Right Place For The mobileinit Event Handler

Our refactoring step for this chapter will consist of moving the mobileinit event handler out of the index.html file. We don’t want to contaminate our html files with JavaScript, so we’re going to move the handler to the Controller.js file. We will place it right after the controller module’s definition:


Notes.controller = (function ($, dataContext, document) {

    // Controller’s implementation omitted for brevity.

} (jQuery, Notes.dataContext, document));

$(document).bind("mobileinit", function () {
    Notes.controller.init();
});

The index.html file is now virtually free of JavaScript code, which is desirable in order to keep the maintenance costs of the application low.

Creating a Confirmation Dialog

The second feature we need to address is deleting a note. Users of the application will initiate this workflow by tapping the Delete button on the Edit Note page:

When the user taps the button, we are going to render a small dialog, asking her for confirmation:

If the user taps the No button on the confirmation dialog, we will just return to the Note Editor page. However, if she taps the Yes button, we will proceed to delete the note, and then return to the Notes List page.

Let’s first create the dialog, and then connect it to the Delete button on the Note Editor page.

We will create the Confirm Delete Note dialog in the index.html file, using the following markup:

Delete Note?

No Yes

Notice how we use the data-role=”dialog” attribute to have the framework render this page as a dialog. We will use the delete-note-content-placeholder div to render the selected note. The interesting thing about the buttons, which are links decorated with the data-role=”button” attribute, is how we’re using theme swatches to define their colors.

We’re using the B swatch, a built-in swatch of the default theme, for the No button. The Yes button uses the F swatch to give the button the red color. We will create the F swatch in a few minutes.

With the dialog created, we need to focus on how we will render it from within the controller module. Evidently, we need to create an identifier for the dialog:

var confirmDeleteNoteDlgSel = "#confirm-delete-note-dialog";

We also need identifiers for the Delete button in the Note Editor page, the Yes button in the Confirm Delete Note dialog, and the div element that will serve as placeholder in the dialog. Let’s add them to the controller module like so:

var deleteNoteButtonSel = "#delete-note-button",
deleteNoteContentPlaceholderSel = "#delete-note-content-placeholder",
okToDeleteNoteButtonSel = "#ok-to-delete-note-button";

As the dialog will be activated upon the user tapping the Delete button in the Note Editor page, we will define a tap handler for this button in the init function of the controller. Something like this will do:

var init = function () {

    // Rest of the function omitted for brevity.

    d.delegate(deleteNoteButtonSel, "tap", onDeleteNoteButtonTapped);
};

Here we are saying that the tap event on the button will invoke the onDeleteNoteButtonTapped() function, which we will now add to the controller module:

var onDeleteNoteButtonTapped = function () {

    if (currentNote) {
        // Render selected note in confirmation dlg.
        // Deletion will be handled elsewhere, after user confirms it's ok to delete.

        var noteContentPlaceholder = $(deleteNoteContentPlaceholderSel);

        noteContentPlaceholder.empty();
        $("

" + currentNote.title + "

" + currentNote.narrative + "

").appendTo(noteContentPlaceholder);

        $.mobile.changePage(confirmDeleteNoteDlgSel, defaultDlgTrsn);
    }
};

In onDeleteNotebuttonTapped(), we first render the current note’s title and narrative in the content area of the dialog. We can accomplish this by simply appending html nodes to the placeholder we defined within the dialog. Then, we make the dialog the active page, using the $mobile.changePage() function. Note how once again we use the defaultDlgTrsn, previously defined when we were creating the Invalid Note dialog.

Now we are at a point where we are waiting for the user’s answer to our question – delete the note, yes or no? The answer will tell us whether to delete the note or cancel the workflow.

Deleting a Note

Cancellation will occur upon the user tapping the No button. We don’t have to write code for this scenario, as we are using the data-rel=”back” attribute for the No button:

No

This role will cause the button’s tap event to initiate a transition to the previous page, the Note Editor page, which is exactly what we want.

The Yes button is a little different. When the user taps this button, we need to delete the note and initiate a transition to the Notes List page. The Notes List page should then render the updated notes list.

We will define the tap handler for the Yes button in the controller module’s init function, binding to the button’s tap event:

var init = function () {

    // Rest of the function omitted for brevity.

    d.delegate(okToDeleteNoteButtonSel, "tap", onOKToDeleteNoteButtonTapped);
};

Then, we will define onOKToDeleteNoteButtonTapped() like so:

var onOKToDeleteNoteButtonTapped = function () {

    dataContext.deleteNote(currentNote);
    returnToNotesListPage();
};

Easy, right? We first call the data context module’s deleteNote(), and then transition to the Notes List page by calling returnToNotesListPage(), a function that we created when we were working on the steps required to save a note.

The problem is that we have not defined a deleteNote() function in the data context module. Before doing so, let’s define a test for this function in the AppSpec.js file:

it("Removes a note from local storage", function () {

        // Create a note.
        var dateCreated = new Date();
        var id = new String(dateCreated.getTime());
        var noteModel = new Notes.NoteModel({
            id: id,
            dateCreated: dateCreated,
            title: "",
            narrative: ""
        });

        // Start with an empty notes list.
        var notesList = [];
        // Add note to local storage.
        notesList.push(noteModel);
        $.jStorage.set(notesListStorageKey, notesList);
        notesList = $.jStorage.get(notesListStorageKey);
        expect(notesList.length).toEqual(1);

        // Proceed to delete.
        Notes.dataContext.init(notesListStorageKey);
        Notes.dataContext.deleteNote(noteModel);

        // Should retrieve empty array
        notesList = $.jStorage.get(notesListStorageKey);
        expect(notesList.length).toEqual(0);

        // Clean up
        $.jStorage.deleteKey(notesListStorageKey);

    });

In the test, we first create a note and save it directly into local storage. Then, we use the function being tested, deleteNote(), to remove the note. Of course, the expectation is that we can delete a note using this function.

The test should fail, as deleteNote() still does not exist:

With the test in place, let’s head over to the DataContext.js file, and define deleteNote() like so:

var deleteNote = function (noteModel) {

    var i;
    for (i = 0; i < notesList.length; i += 1) {
        if (notesList[i].id === noteModel.id) {
            notesList.splice(i, 1);
            i = notesList.length;
        }
    }

    saveNotesToLocalStorage();
};

Again, a very simple function that loops through the array of existing notes, trying to find one with the id of the note we want to delete. If found, the note is removed from the array. The updated array is then serialized to local storage through a call to saveNotesToLocalStorage().

We also need to add deleteNote() to the public interface of the module so we can invoke it from the controller module:

var pub = {
    init: init,
    createBlankNote: createBlankNote,
    getNotesList: getNotesList,
    saveNote: saveNote,
    deleteNote: deleteNote
};

Time to re-run the test, which should pass if we didn’t make any mistakes:

This completes the code that we needed for the Delete Note feature. The UI elements are in place, and the Controller and Data Context modules are ready to handle this workflow. Now you can fire up your favorite device emulator or WebKit browser, and verify that you can delete notes.

Using a Custom Theme Swatch in jQuery Mobile

Before we end this chapter, let us take care of a cosmetic issue. How about changing the color of the Yes button in the dialog?

One approach to accomplish this consists of using a custom jQuery Mobile theme swatch. We will take advantage of the ThemeRoller for jQuery Mobile to change the swatch of the Yes button.

As you already saw, we assigned the data-theme=”f” attribute to the button when we created the dialog:

Yes

With this in mind, we will head over to the ThemeRoller site and define an F swatch. The swatch has several properties, but we’re only interested in those that apply to buttons. Let’s use the following properties for the different buttons states:

After entering these values, we can use the Download Theme link to download the theme file.

The file contains styles for all elements enhanced by the jQuery Mobile framework. We will copy the styles that apply to button elements, or elements decorated with the data-role=”button” attribute, which we will add to our app.css file like so:

.ui-btn-up-f {
	border: 1px solid #c1272d /*{f-bup-border}*/;
	background: #c1272d /*{f-bup-background-color}*/;
	font-weight: bold;
	color: #ffffff /*{f-bup-color}*/;
	text-shadow:  0  /*{f-bup-shadow-x}*/  1px  /*{f-bup-shadow-y}*/  1px  /*{f-bup-shadow-radius}*/ #444444 /*{f-bup-shadow-color}*/;
	background-image: -webkit-gradient(linear, left top, left bottom, from( #D42A31 /*{f-bup-background-start}*/), to( #AD2328 /*{f-bup-background-end}*/)); /* Saf4+, Chrome */
	background-image: -webkit-linear-gradient(top, #D42A31 /*{f-bup-background-start}*/, #AD2328 /*{f-bup-background-end}*/); /* Chrome 10+, Saf5.1+ */
	background-image:    -moz-linear-gradient(top, #D42A31 /*{f-bup-background-start}*/, #AD2328 /*{f-bup-background-end}*/); /* FF3.6 */
	background-image:     -ms-linear-gradient(top, #D42A31 /*{f-bup-background-start}*/, #AD2328 /*{f-bup-background-end}*/); /* IE10 */
	background-image:      -o-linear-gradient(top, #D42A31 /*{f-bup-background-start}*/, #AD2328 /*{f-bup-background-end}*/); /* Opera 11.10+ */
	background-image:         linear-gradient(top, #D42A31 /*{f-bup-background-start}*/, #AD2328 /*{f-bup-background-end}*/);
}
.ui-btn-up-f a.ui-link-inherit {
	color: #ffffff /*{f-bup-color}*/;
}

.ui-btn-hover-f {
	border: 1px solid #DD2C33 /*{f-bhover-border}*/;
	background: #DD2C33 /*{f-bhover-background-color}*/;
	font-weight: bold;
	color: #ffffff /*{f-bhover-color}*/;
	text-shadow:  0  /*{f-bhover-shadow-x}*/  1px  /*{f-bhover-shadow-y}*/  1px  /*{f-bhover-shadow-radius}*/ #444444 /*{f-bhover-shadow-color}*/;
	background-image: -webkit-gradient(linear, left top, left bottom, from( #F33038 /*{f-bhover-background-start}*/), to( #C6272D /*{f-bhover-background-end}*/)); /* Saf4+, Chrome */
	background-image: -webkit-linear-gradient(top, #F33038 /*{f-bhover-background-start}*/, #C6272D /*{f-bhover-background-end}*/); /* Chrome 10+, Saf5.1+ */
	background-image:    -moz-linear-gradient(top, #F33038 /*{f-bhover-background-start}*/, #C6272D /*{f-bhover-background-end}*/); /* FF3.6 */
	background-image:     -ms-linear-gradient(top, #F33038 /*{f-bhover-background-start}*/, #C6272D /*{f-bhover-background-end}*/); /* IE10 */
	background-image:      -o-linear-gradient(top, #F33038 /*{f-bhover-background-start}*/, #C6272D /*{f-bhover-background-end}*/); /* Opera 11.10+ */
	background-image:         linear-gradient(top, #F33038 /*{f-bhover-background-start}*/, #C6272D /*{f-bhover-background-end}*/);
}
.ui-btn-hover-f a.ui-link-inherit {
	color: #ffffff /*{f-bhover-color}*/;
}
.ui-btn-down-f {
	border: 1px solid #DD2C33 /*{f-bdown-border}*/;
	background: #DD2C33 /*{f-bdown-background-color}*/;
	font-weight: bold;
	color: #ffffff /*{f-bdown-color}*/;
	text-shadow:  0  /*{f-bdown-shadow-x}*/  1px  /*{f-bdown-shadow-y}*/  1px  /*{f-bdown-shadow-radius}*/ #444444 /*{f-bdown-shadow-color}*/;
	background-image: -webkit-gradient(linear, left top, left bottom, from( #C6272D /*{f-bdown-background-start}*/), to( #F33038 /*{f-bdown-background-end}*/)); /* Saf4+, Chrome */
	background-image: -webkit-linear-gradient(top, #C6272D /*{f-bdown-background-start}*/, #F33038 /*{f-bdown-background-end}*/); /* Chrome 10+, Saf5.1+ */
	background-image:    -moz-linear-gradient(top, #C6272D /*{f-bdown-background-start}*/, #F33038 /*{f-bdown-background-end}*/); /* FF3.6 */
	background-image:     -ms-linear-gradient(top, #C6272D /*{f-bdown-background-start}*/, #F33038 /*{f-bdown-background-end}*/); /* IE10 */
	background-image:      -o-linear-gradient(top, #C6272D /*{f-bdown-background-start}*/, #F33038 /*{f-bdown-background-end}*/); /* Opera 11.10+ */
	background-image:         linear-gradient(top, #C6272D /*{f-bdown-background-start}*/, #F33038 /*{f-bdown-background-end}*/);
}
.ui-btn-down-f a.ui-link-inherit {
	color: #ffffff /*{f-bdown-color}*/;
}

After adding these classes to the app.css file, we can check the dialog’s look. The Yes button should now render with the new F swatch’s properties:

Summary

At this point, we have built a fully functional jQuery Mobile application that people can use to create, edit and delete notes.

In this series we started with a short introduction to the jQuery Mobile framework, learned how to create a modular application that saves information to the user’s device, created an attractive user interface, and designed behavior tests for the business logic.

I hope you use the experience gained in this and previous chapters to create great applications. Don’t forget to let me know how it goes!

Downloads

Download the source code for this article: Building a jQuery Mobile App Part 4 Sr.c.zip

The Entire Series

Sencha Touch or jQuery Mobile? – Read This Before You Make a Decision

Jorge — Tue, 27 Dec 2011 18:28:26 +0000

If you ever need to choose between jQuery Mobile and Sencha Touch, you need to consider these factors before making your decision:

About jQuery Mobile

It’s a UI-only library, which relies on jQuery and jQuery UI for DOM manipulation, Ajax and other utilities
To create UI widgets, you generally need to hand-code their html, and the library enhances their look and feel
As it works by enhancing the html you create, it allows you to re-use or re-purpose existing html
Some simple applications can be created using only html, without having to write JavaScript code
It has a relatively small object model, which makes it faster and easier to learn, specially if you are familiar with jQuery
It does not impose a coding discipline or structure, which gives you flexibility, but can lead to applications that are difficult to maintain
Easier to integrate with other frameworks
Targets more devices than Sencha Touch
Not tied to a particular vendor

About Sencha Touch

It’s a library that tries to do it all: UI widgets, DOM manipulation, Ajax and other utilities
Does not depend on other libraries
Follows a JavaScript-centric approach, where you are required to write little html
Has a large object model, which provides more features out of the box, but takes longer to learn
Imposes a coding structure and discipline, which generally results in well-organized code
Provides built-in server and local storage abstractions, which make it easier to perform CRUD operations on relational data
Has built-in facilities for creating iOS and Android native packages
Targets less devices than jQuery Mobile

Want To Learn More?

I have a selection of Sencha Touch and jQuery Mobile tutorials that will help you build great applications. Check them out using these links:

Building a jQuery Mobile Application, Part 3

Jorge — Tue, 20 Dec 2011 13:30:56 +0000

In this third part of my tutorial on how to create a mobile web app using jQuery Mobile we are going to focus on the following areas:

How to pass information between the Notes List page and the Note Editor page using URLs and query strings
How to load a note in the Note Editor page
How to save a new or edited note

Let’s begin with a few changes that will make the application easier to maintain and test.

Refactoring

Our data context module directly uses a reference to the jQuery library when calling the jStorage plugin. We will change our code so we pass the jQuery reference as a parameter when we invoke the dataContext module, like so:

Notes.dataContext = (function ($) {

    // Module’s implementation omitted…

} (jQuery));

In addition, we will remove the hard-coded reference to the storage key we use to cache notes in local storage:

var notesListStorageKey = "Notes.NotesList"; // No need to hard-code this value.

We will now pass this value to the dataContext module through the init function:


var init = function (storageKey) {
    notesListStorageKey = storageKey;
    loadNotesFromLocalStorage();
};

Among other things, this change will allow us to test the dataContext module with a different key than the one we use in the application itself. Let’s modify our AppSpec.js file to support this change:


describe("Data Context tests", function () {

    var notesListStorageKey = "Notes.NotesListTest";

    // Other tests omitted…

    it("Returns dummy notes saved in local storage", function () {

        Notes.testHelper.createDummyNotes();
        // Load dummy notes from local storage.
        Notes.dataContext.init(notesListStorageKey);

        var notesList = Notes.dataContext.getNotesList();

        expect(notesList.length > 0).toBeTruthy();
    });

});

Grouping Notes by Date

The next change will make it easier for our users to find a particular note in the Notes List page. We are going to group the notes by date:

We can make this helpful modification in the renderNotes function of the controller module:

var renderNotesList = function () {

    var notesList = dataContext.getNotesList();
    var view = $(notesListSelector);

    view.empty();

    if (notesList.length === 0) {

        $(noNotesCachedMsg).appendTo(view);
    } else {

        var liArray = [],
            notesCount = notesList.length,
            note,
            dateGroup,
            noteDate,
            i;

        var ul = $("").appendTo(view);

        for (i = 0; i < notesCount; i += 1) {

            note = notesList[i];

            noteDate = (new Date(note.dateCreated)).toDateString();

            if (dateGroup !== noteDate) {
                liArray.push("" + noteDate + "");
                dateGroup = noteDate;
            }

            liArray.push(""
                + ""
                + "" + note.title + ""
                + "" + note.narrative + ""
                + ""
                + "");

        }

        var listItems = liArray.join("");
        $(listItems).appendTo(ul);

        ul.listview();
    }
};

In the loop that creates the list items representing the notes, we keep track of the date the notes were taken, inserting a new list item with the attribute data-role=”list-divider” whenever the date value changes. This gives us a nice list divider: In addition, notice how the list items contain a link whose query string has a reference to the id of the note. We will use this information when we load a selected note into the Note Editor page. Let’s start working on this page now.

Creating the Note Editor Page

The Note Editor page consists of a div element with the data-role=”page” attribute. We will add this div to the index.html file like so:


    
        Cancel
        
            Edit Note
        Save
    
    
        
        
            Title:
        
        
            Narrative:
        
        
    
    
        Delete

This page has a header area with Save and Cancel buttons, a form with the elements that allow us to edit a note, and a footer that hosts the Delete button. As you can see, jQuery Mobile has taken care of nicely styling and laying out the form elements.

We will give the Save and Delete button special treatment, binding to their tap events to trigger the routines that save or delete the note loaded in the Note Editor page.

The role of the Cancel button is to take us back to the Notes List page. This is why we use a link to the #notes-list-page bookmark.

Loading a Note in the Editor

Let’s take a moment to think about what needs to happen to load a note into the editor. For existing notes, when the user taps the li element representing a note in the Notes List page, we will perform the following steps:

Look up the note in the notesList array, based on the note’s id contained in the li element’s link.
Set the values of the title and narrative form elements in the Note Editor page to those of the selected note’s title and narrative.
Make the Note Editor page active.

For new notes, when the user taps the New button in the Notes List page, we will perform these steps:

Create a new, blank note.
Set the values of the title and narrative form elements in the Note Editor page to those of the new note’s title and narrative.
Make the Note Editor page active.

These routines are similar. The only difference is that in the first case we have to look up and load an existing note, while in the second case we need to create and load a new note.

Let’s begin with the first set of steps. The first thing we need in our controller is a reference to the Note Editor. We will define a selector for it in the declarations section of the controller module:

var noteEditorPageId = "note-editor-page";

Next, we need to return to the onPageChange() function and handle the case when we are switching to the editor page:

var onPageChange = function (event, data) {

    var toPageId = data.toPage.attr("id");
    var fromPageId = null;

    if (data.options.fromPage) {
        fromPageId = data.options.fromPage.attr("id");
    }

    switch (toPageId) {

        case notesListPageId:
            resetCurrentNote();
            renderNotesList();
            break;

        case noteEditorPageId:

            if (fromPageId === notesListPageId) {
                renderSelectedNote(data);
            }
            break;
    }
};

The handler is a bit more complex now. We added the fromPageId variable, which will store the id of the page we’re navingating from. We will call this page Source page from now on. We will call the page we’re navigating to Target page.

The value of fromPageId will help us determine if we need to load a note into the editor:

if (fromPageId === notesListPageId) {
    renderSelectedNote(data);
}

If the source page is the notes list, we load the note by calling the renderSelectedNote() function, which we will implement in a minute. Note that we added the check for the fromPage parameter because the pagechange event is also triggered after the application launches, when there isn’t a source page yet. It doesn’t make sense to acquire the id of the source page when the source page itself doesn’t exist:

if (data.options.fromPage) {
    fromPageId = data.options.fromPage.attr("id");
}

Before adding the code for renderSelectedNote(), let’s jump to the top of the controller module and create identifiers for the title and narrative form elements:

var noteTitleEditorSel = "[name=note-title-editor]";
var noteNarrativeEditorSel = "[name=note-narrative-editor]";

And here’s the implementation of renderSelectedNote():

var renderSelectedNote = function (data) {

    var u = $.mobile.path.parseUrl(data.options.fromPage.context.URL);
    var re = "^#" + noteEditorPageId;

    if (u.hash.search(re) !== -1) {

        var queryStringObj = queryStringToObject(data.options.queryString);

        var titleEditor = $(noteTitleEditorSel);
        var narrativeEditor = $(noteNarrativeEditorSel);

        var noteId = queryStringObj["noteId"];

        if (typeof noteId !== "undefined") {

            // We were passed a note id => We're editing an existing note.
            var notesList = dataContext.getNotesList();
            var notesCount = notesList.length;
            var note;

            for (var i = 0; i < notesCount; i++) {

                note = notesList[i];

                if (noteId === note.id) {

                    titleEditor.val(note.title);
                    narrativeEditor.val(note.narrative);
                    currentNote = note;
                }
            }
        } else {
            // We're creating a note. Reset the fields.
            titleEditor.val("");
            narrativeEditor.val("");
        }

        titleEditor.focus();
    }
};

The renderSelectedNote() function takes advantage of the fact that we’re passing the selected note’s id in the query string of the list item’s link:

liArray.push(""
    + ""
    + "" + note.title + ""
    + "" + note.narrative + ""
    + ""
    + "");

Our first goal inside renderSelectedNote() is to inspect the hash of the source page’s URL, to make sure the source page is the Notes List page. We do this using a regular expression search:

var u = $.mobile.path.parseUrl(data.options.fromPage.context.URL);
    var re = "^#" + noteEditorPageId;

    if (u.hash.search(re) !== -1) {
	… additional code omitted
    }

To acquire the URL’s hash we use the $.mobile.path.parseUrl() function, which parses a URL into an object that facilitates accessing the URL’s components.

Once we’re certain the source page is the Notes List, we create an object containing the query string parameters passed from the source page. The queryStringToObject() helper function performs this task:

var queryStringToObject = function (queryString) {

    var queryStringObj = {};
    var e;
    var a = /\+/g;  // Replace + symbol with a space
    var r = /([^&;=]+)=?([^&;]*)/g;
    var d = function (s) { return decodeURIComponent(s.replace(a, " ")); };

    e = r.exec(queryString);
    while (e) {
        queryStringObj[d(e[1])] = d(e[2]);
        e = r.exec(queryString);

    }

    return queryStringObj;
};

The queryStringToObject() function takes the value of the data.options.queryString property as a parameter:

var queryStringObj = queryStringToObject(data.options.queryString);

The problem is that the data.options object does not have a native queryString property. However, we can create it if we find a place, or rather a time before the page transition occurs, where we can acquire the value of the query string.

It turns out that this is possible if we define a handler for jQuery Mobile’s pagebeforechange event. Let’s revisit the init() function, and add the following line:

d.bind("pagebeforechange", onPageBeforeChange);

Now we can define onPageBeforeChange() like so:

var onPageBeforeChange = function (event, data) {

    if (typeof data.toPage === "string") {

        var url = $.mobile.path.parseUrl(data.toPage);

        if ($.mobile.path.isEmbeddedPage(url)) {

            data.options.queryString = $.mobile.path.parseUrl(url.hash.replace(/^#/, "")).search.replace("?", "");
        }
    }
};

Pay attention to the following line:

data.options.queryString = $.mobile.path.parseUrl(url.hash.replace(/^#/, "")).search.replace("?", "");

Here we use $.mobile.path.parseUrl() to acquire the query string and add it to the data.options object. As the onPageBeforeChange handler is invoked before the onPageChange handler, we’ve found an approach to inject the query string defined in the source page into the events chain, and propagate it to the target pages, where it can be used.

Back in renderSelectedNote(), we can finally take care of loading the selected note, or resetting the title and narrative fields, like so:

if (typeof noteId !== "undefined") {

    // We were passed a note id => We're editing an existing note.
    var notesList = dataContext.getNotesList();
    var notesCount = notesList.length;
    var note;

    for (var i = 0; i < notesCount; i++) {

        note = notesList[i];

        if (noteId === note.id) {
            currentNote = note;
            titleEditor.val(currentNote.title);
            narrativeEditor.val(currentNote.narrative);
        }
    }
} else {
    // We're creating a note. Reset the fields.
    titleEditor.val("");
    narrativeEditor.val("");
}

Observe how we’re keeping a reference to the selected note in the currentNote variable. This will later allow us to save or delete the note without having to perform a lookup on the notesList array.

This is what it takes to load a note. Let’s make sure things are working as expected. Fire up your favorite browser and confirm that tapping a note in the Notes List page loads the note into the Note Editor page:

Similarly, tapping the New button should load a new note into the editor.

Saving a Note

As the Save Note workflow is initiated when a user taps the Save button, the controller module needs to define a handler for the button’s tap event. We will use this handler to invoke a saveNote() function that we will create in the dataContext module. Let’s work on the tap handler first.

We need an identifier for the Save button, which we can create at the top of the controller module like so:

var saveNoteButtonSel = "#save-note-button";

Next, we need to bind the tap handler in the controller’s init() function:

var init = function () {

    dataContext.init("Notes.NotesList");

    var d = $(document);
    d.bind("pagebeforechange", onPageBeforeChange);
    d.bind("pagechange", onPageChange);
    d.delegate(saveNoteButtonSel, "tap", onSaveNoteButtonTapped);
};

Now we can define the onSaveButtonTapped function like so:

var onSaveNoteButtonTapped = function () {

    // Validate note.
    var titleEditor = $(noteTitleEditorSel);
    var narrativeEditor = $(noteNarrativeEditorSel);
    var tempNote = dataContext.createBlankNote();

    tempNote.title = titleEditor.val();
    tempNote.narrative = narrativeEditor.val();

    if (tempNote.isValid()) {

        if (null !== currentNote) {

            currentNote.title = tempNote.title;
            currentNote.narrative = tempNote.narrative;
        } else {

            currentNote = tempNote;
        }

        dataContext.saveNote(currentNote);

        returnToNotesListPage();

    } else {
        // TODO: Inform the user the note is invalid.
    }
};

The first interesting thing that happens in this function is the creation of a temporary note, and the call to the NoteModel’s isValid method. This is the method that will allow us to validate a note before making it permanent.

But isValid does not exist yet. We need to create it like so:

Notes.NoteModel.prototype.isValid = function () {
    "use strict";
    if (this.title && this.title.length > 0) {
        return true;
    }
    return false;
};

A simple check on the note’s title is enough to validate the note. Nothing complicated.

Back in onSaveButtonTapped, we find out if we’re editing an existing note by observing the value of currentNote. If currentNote points to an existing note, we transfer the title and narrative of the temporary note to it. If currentNote is not poiting to an existing note, we make it point to the temporary note’s reference.

Then, we save the note by calling the dataContext module’s saveNote function. We haven’t created this function yet. Let’s define a behavior test for it in the AppSpec file:

it("Saves a note to local storage", function () {

    // Make sure LS is empty before the test.
    $.jStorage.deleteKey(notesListStorageKey);
    var notesList = $.jStorage.get(notesListStorageKey);
    expect(notesList).toBeNull();

     // Create a note.
    var dateCreated = new Date();
    var id = dateCreated.getTime().toString();
    var noteModel = new Notes.NoteModel({
        id: id,
        dateCreated: dateCreated,
        title: ""
    });

    Notes.dataContext.init(notesListStorageKey);
    Notes.dataContext.saveNote(noteModel);

    // Should retrieve the saved note.
    notesList = $.jStorage.get(notesListStorageKey);
    var expectedNote = notesList[0];

    expect(expectedNote instanceof Notes.NoteModel).toBeTruthy();

    // Clean up
    $.jStorage.deleteKey(notesListStorageKey);
});

In this spec we first empty the local storage container we will use. Then, we save a dummy note by calling saveNote on the dataContext module. Last, we retrieve the value from local storage and assert that it is in effect an instance of the NoteModel class.

As the saveNote function is missing, this test should fail:

In the dataContext module, let’s create saveNote as follows:

var saveNote = function (noteModel) {

    var found = false;
    var i;

    for (i = 0; i < notesList.length; i += 1) {
        if (notesList[i].id === noteModel.id) {
            notesList[i] = noteModel;
            found = true;
            i = notesList.length;
        }
    }

    if (!found) {
        notesList.splice(0, 0, noteModel);
    }

    saveNotesToLocalStorage();
};

This function is pretty straightforward. We start by iterating over the array of existing notes. If we find the id of the edited note, we “edit” the existing note through an in-place replacement with the passed note. If don’t find the id, we simply place the passed note at the beginning of the array.

Finally, we call the private function saveNotesToLocalStorage, which we also need to add to the dataContext module. This is where we save the modified array to local storage:

var saveNotesToLocalStorage = function () {
    $.jStorage.set(notesListStorageKey, notesList);
};

Let’s run the spec again. This time, it should pass:

Back in the onSaveButtonTapped function, we also wrote a call to the helper function returnToNotesListPage, which we will implement like so:

var returnToNotesListPage = function () {

    $.mobile.changePage("#" + notesListPageId,
        { transition: "slide", reverse: true });
};

This is a convenience function that we will call every time we need to return to the Notes List page.

There is one last step we need to take in order for the Edit Note and Save Note workflows to work correctly. We need to make sure we reset the currentNote reference after a note is saved. We can do this from the onPageChange function, within its switch statement:

var onPageChange = function (event, data) {
var toPageId = data.toPage.attr("id");
var fromPageId = null;
if (data.options.fromPage) {
fromPageId = data.options.fromPage.attr("id");
}
switch (toPageId) {
case notesListPageId:
resetCurrentNote(); // Reset reference to the note being edited.
renderNotesList();
break;
case noteEditorPageId:

if (fromPageId === notesListPageId) {
renderSelectedNote(data);
}
break;
}
};

When we’re navigating back to the Notes List page, we’re now invoking the private function resetCurrentNote, which looks like this:

var resetCurrentNote = function () {
    currentNote = null;
}

What do you think? Are you ready to test on the emulator? First go back to the mobileinit handler and either remove or comment out the call to createDummyNotes. We don’t need it anymore:

$(document).bind("mobileinit", function () {

    //Notes.testHelper.createDummyNotes();

    Notes.controller.init();

});

Now, fire up the emulator. You should be able to create and edit notes.

Nice! We just built the ability to create and edit notes into our application.

I’m sure you noticed that we still have a loose end in the onSaveNoteButtonTapped function, as we have not handled the invalid note scenario. We will leave this step for the next chapter, along with deleting notes.

Stay tuned!

Downloads

Download the source code for this article: Building a jQuery Mobile App Part 3 Src.zip

The Entire Series

Building a jQuery Mobile Application, Part 2

Jorge — Wed, 30 Nov 2011 02:04:30 +0000

This is the second part of my tutorial on how to create a mobile web app using jQuery Mobile. In this tutorial we’re building a mobile web application that offers its users the following features:

Ability to create, edit and delete notes.
Ability to store notes on the device running the application, across browser sessions.
Ability to view the entire collection of notes stored on the device.

In the first chapter of this series we started building the business logic layer of the app. We are using a simple workflow that consists of the following steps:

Use the Jasmine framework to define the business logic behavior.
Implement the behavior in the application.
Confirm that the implemented behavior adheres to its definition.

We’re now going to continue working on the business logic features that will allow us to retrieve the list of notes cached on the device. We’re also going to use the jQuery Mobile framework to present the cached notes to the user.

By the end of this article, we will have completed the first version of the Notes List screen. This screen will render the list of cached notes as depicted below.

Consolidating Test Suites and Creating a Data Context Module

Let’s get started with a bit of refactoring. As you might recall from the first part of this tutorial, we placed the tests into two Jasmine suites. The first suite looks like this:

describe("Public interface exists", function () {

    it("Should have public interface to return notes list", function () {
        expect(Notes.app.getNotesList).toBeDefined();
    });

});

And the second suite looks like this:

describe("Public interface implementation", function () {

    it("Should return notes list", function () {

        var notesList = Notes.app.getNotesList();

        expect(notesList instanceof Array).toBeTruthy();
    });
});

As I was writing the outline for this article, I realized that using two test suites this early in the project, when we have only a few specs, might be overkill. We can simplify things and use only one test suite for now. We can always add more suites if there’s a real need later.

Let’s replace the suites above with the following:

describe("Data Context tests", function () {

    it(“Exists in the app”, function () {
        expect(Notes.dataContext).toBeDefined();
    });

    it(“Returns notes Array”, function () {

        var notesList = Notes.dataContext.getNotesList();

        expect(notesList instanceof Array).toBeTruthy();
    });

});

As the first spec indicates, we’re going to rename the app instance variable to dataContext. After all, what this instance will contain is all the functions that have to do with data access – in our case, access to the notes stored on the device. In the first part of the series, the app variable looked like this:

Notes.app = (function () {

    var notesList = [];

    function getNotesList() {
        return notesList;
    }

    return {

        getNotesList: getNotesList

    }

})();

After the renaming, we end up with dataContext, like so:

Notes.dataContext = (function () {

    var notesList = [];

    function getNotesList() {
        return notesList;
    }

    return {

        getNotesList: getNotesList

    }

})();

Along with this change, we’re going to rename the App.js file to DataContext.js. After renaming, our files should now look as depicted below.

Of course, we need to run our tests to make sure the refactoring did not change the expected behavior. In the specrunner.html, we need to replace the reference to App.js with a reference to DataContext.js:

Now we can run our Jasmine suite. Let’s open the specrunner.html file in our favorite browser and check the output of the test. If we didn’t make any mistakes during our refactoring, our tests should be green: Our refactoring is done. What we did, in short, was rename the application module we created in the first part of the tutorial – it’s now called DataContext – and adjust our tests accordingly.

Creating a Blank Note

Besides retrieving the cached notes, an important function we need our data context to perform is creating a blank note. This feature is needed when users tap the New button in the UI. Tapping the New button will pass a new, blank note, to the Note Editor view: We can describe this “create blank note” behavior in our test suite as follows:

it("Returns a blank note", function () {

    var blankNote = Notes.dataContext.createBlankNote();
    expect(blankNote.title.length === 0).toBeTruthy();
    expect(blankNote.narrative.length === 0).toBeTruthy();
});

If we run this test, it will not pass. Why? Well, we need to add the createBlankNote() function to the Data Context module. This is the code we need:

Notes.dataContext = (function () {

    var notesList = [];

    function createBlankNote() {

        var dateCreated = new Date();
        var id = new String(dateCreated.getTime()) + new String(getRandomInt(0, 100));
        var noteModel = new Notes.NoteModel({
            id: id,
            dateCreated: dateCreated,
            title: "",
            narrative: ""
        });

        return noteModel;
    }

    function getNotesList() {
        return notesList;
    }

    return {
        createBlankNote: createBlankNote,
        getNotesList: getNotesList
    };

})();

If you look at createBlankNote(), you will notice that it calls a getRandomInt() helper function to create the id of the new note. As we haven’t defined getRandomInt() yet, if we run the Jasmine spec, the results should show that the helper function is missing: Let’s add getRandomInt() like so:

function getRandomInt(min, max) {
    return Math.floor(Math.random() * (max - min + 1)) + min;
}

Re-running the test again should fail with a different error. The reason for the new error is that we’re trying to create an instance of the NoteModel class, which we haven’t defined yet.

Let’s create the NoteModel.js file in the application’s folder, and add the following definition for the NoteModel class:

Notes.NoteModel = function (config) {
    this.id = config.id;
    this.dateCreated = config.dateCreated;
    this.title = config.title;
    this.narrative = config.narrative;
}

This construct should look familiar to you. The NoteModel is a class that represents a note. Every time we need to move a note’s data around, we will use an instance of this class. And what we will cache on the device is a serialized array of NoteModel instances.

We also need to include a reference to the NoteModel.js file in specrunner.html:

After adding the NoteModel, the tests should pass: Are you with me so far? This is getting interesting. Next we will begin working on retrieving cached notes from HTML5’s local storage.

Retrieving Cached Notes from Local Storage

We will use the localStorage API to store notes across browser sessions. Local storage is based on keys and values, where the keys and values are strings. As we will cache an array of NoteModel instances, we will need a serialization mechanism to convert the array of notes to a string that will be saved in local storage. Similarly, we will need a mechanism to convert the serialized notes into an array of NoteModel instances when retrieving the cached notes.

We could write the serialization/deserialization code we need. However, to simplify this tutorial, we will use an abstraction layer on top of the localStorage API. This layer will take care of the serialization and deserialization services, and it will be provided by the jStorage plugin.

The jStorage plugin allows us to cache numbers, strings, and objects in local storage. We are going to place the jStorage plugin in its own folder like so: In the data context module, we will define a private function which retrieves the cached notes from local storage like so:

function loadNotesFromLocalStorage() {

    var storedNotes = $.jStorage.get(notesListStorageKey);

    if (storedNotes !== null) {
        notesList = storedNotes;
    }

}

And let’s also define the notesListStorageKey variable, right after the notesList definition:

var notesList = [];
var notesListStorageKey = "Notes.NotesList";

The loadNotesFromLocalStorage() function simply uses the jStorage plugin to retrieve the list of cached notes from local storage. The plugin takes care of converting the list of notes from a String instance to an Array instance, exactly what we need.

When the application is run, the cached notes will be presented to the user. This means that the loadNotesFromLocalStorage() is one of the first functions that will be called in the app. To call this function when the application starts, as well as execute any other initialization code needed by the app, we will use a helper method, which we will name init().

Let’s work on the init() function by first creating a spec for it in the AppSpec.js file:

it("Has init function", function () {
    expect(Notes.dataContext.init).toBeDefined();
});

Then, we need to add the init() public function to the DataContext.js file:

function init() {
    loadNotesFromLocalStorage();
}
.
. // Other functions…
.
return {
    init: init,
    createBlankNote: createBlankNote,
    getNotesList: getNotesList
};

The test for init() should be green at this point:

Testing With Data by Retrieving a List of Dummy Notes

At this point we’ve added and tested the features we needed for this part of the tutorial. However, it would be nice if we could also test by saving a few dummy notes to local storage, and having the Data Context module retrieve them for us.

This is not difficult to do. Let’s first create a helper module, which we will place in a new TestHelper.js file, in the spec folder. This module will allow us to save a few dummy notes into local storage:

Notes.testHelper = (function () {

    function createDummyNotes() {

        var notesListStorageKey = "Notes.NotesList";
        var notesCount = 10;
        var notes = [];

        for (var i = 0; i < notesCount; i++) {

            var note = Notes.dataContext.createBlankNote();
            note.title = "Title " + i;
            note.narrative = "Narrative " + i;
            notes.push(note);
        }

        $.jStorage.set(notesListStorageKey, notes);
    };

    return {
        createDummyNotes: createDummyNotes
    }

})();

Notice that testHelper uses the same notesListStorageKey value used in the data context module, along with the data context’s createBlankNote() function, to create an array of dummy notes. These notes are saved to local storage through the jStorage plugin.

We also need a reference to TestHelper.js in our specrunner.html file:

Back in the AppSpec.js file, we can define a spec confirming that we can load the dummy notes:

it("Returns dummy notes saved in local storage", function () {

    Notes.testHelper.createDummyNotes();
    // Load dummy notes from ls.
    Notes.dataContext.init();

    var notesList = Notes.dataContext.getNotesList();

    expect(notesList.length > 0).toBeTruthy();
});

This spec first uses the testHelper’s createDummyNotes() function to place a few notes in local storage. Then, it invokes the data context’s init() function, which in turn calls the loadNotesFromLocalStorage() private function.

After the call to init(), the spec retrieves the notes list via a call to the data context’s getNotesList() function. The expectation is simply that the notes list is not empty.

Notice that we could be more thorough and compare the retrieved notes to the ones we saved, making sure that the data did not change. I will leave this exercise as homework for you.

What do you say we dive into the presentation layer?

Rendering Cached Notes

Now we’re ready to render the cached notes. If you’ve never read the jQuery Mobile overview and quick start guide, this is a good time to do it. Don’t worry, I’ll wait for you to come back.

The first thing we need to do is use jQuery Mobile’s page template to create our app’s html page. Let’s create the index.html file in our application’s folder, as depicted below: Then, add the following markup to the index.html file:

As you can see, the head section of the file has references to the jQuery and jQuery Mobile libraries, the jStorage library, and the application’s files – DataContext.js, Controller.js and NoteModel.js. So far we have created DataContext.js and NoteModel.js. If you’re wondering about Controller.js, we will create it next.

Besides the application’s JavaScript files, we have included a reference to the TestHelper.js file. This file will help us create the dummy notes that the application will render.

Notice also, in the head section, a placeholder for the mobileinit event handler, which we will add later. The mobileinit event is fired on the document object when jQuery Mobile starts to execute. We can bind to this event when we want to run initialization code in our application, or when we need to apply overrides to jQuery Mobile’s defaults.

Let’s focus on the body section of the file now. Here we’ve created a single jQuery Mobile page with a header and a content section. This will be the Notes List page, the main page of the application. The header of this page already contains the New button, which will allow our users to create a new note. We will work on this button in the next chapter of this series.

We will use the content section of the Notes List page, adorned with the data-role=”content” attribute, to render the cached notes. This section is empty now, but in a few minutes we will write the code that inserts the list of cached notes into it.

To finish with the index.html file, let’s create the mobileinit event handler like so:












$(document).bind("mobileinit", function () {

//Notes.testHelper.createDummyNotes();

Notes.controller.init();

});

Notice that the event handler is defined right before the reference to the jQuery Mobile library. As the mobileinit event’s documentation explains, this event is triggered immediately upon execution, which means that any handlers for it should be bound before jQuery Mobile is loaded.

The handler executes a couple of function calls. One is the call to the createDummyNotes() function in the Test Helper module, with which we’re already familiar. The second call is to the init() function of a controller variable that we have not created yet.

Having observed the modular approach we’re following, as well as the naming conventions for the modules, you can probably see where we’re going with this. In effect, we’ve been building our app in a Model-View-Controller fashion, where the NoteModel and Data Context modules function as the model, and the jQuery Mobile pages function as the views. We will build the controller next.

Creating the Controller

Our controller will respond to user input, and will change the models and views accordingly. The application’s controller goes in a new file that we will name Controller.js. Let’s define an empty controller module like so:

Notes.controller = (function ($, dataContext) {

})(jQuery, Notes.dataContext);

Observe how we’re passing to the controller a reference to the jQuery object, along with a reference to the app’s data context. This will give the controller the ability to respond to user input, and change the model and views as needed.

For now, all we need our controller to do is render the list of cached notes. We already established that the controller will have an initialization function, init(), which will be triggered when the document’s mobileinit event is fired. Let’s create the init() function in the controller module like so:

Notes.controller = (function ($, dataContext) {

    function init() {

        dataContext.init();
        var d = $(document);
        d.bind("pagechange", onPageChange);

    }

    return {

        init: init
    }

})(jQuery, Notes.dataContext);

The init() function in the controller first triggers the data context’s init() function. This is understandable, as we need the data context fully initialized before we can use it.

You would expect that the next step in the controller’s init() function would be to render the cached notes. That is not wrong, but it would only work for rendering the cached notes upon application initialization. Instead, we’re doing something more useful. We’re binding to jQuery Mobile’s pagechange event. We will use this event to render the cached notes not only when the application starts, but also when the user transitions from the Note Editor page, which we haven’t created yet, to the Notes List page.

Let’s add the onPageChange() handler function to the controller:

Notes.controller = (function ($, dataContext) {

    var notesListSelector = "#notes-list-content";
var noNotesCachedMsg = "

No notes cached

";
    var notesListPageId = "notes-list-page";
    var currentNote = null;

    function init() {

        dataContext.init();
        var d = $(document);
        d.bind("pagechange", onPageChange);

    }

    function onPageChange(event, data) {

        var toPageId = data.toPage.attr("id");

        switch (toPageId) {
            case notesListPageId:

                renderNotesList();
                break;
        }
    }

    return {

        init: init
    }

})(jQuery, Notes.dataContext);

This handler is relatively simple. It inspects the id attribute of the page we’re transitioning to, available through the data.toPage property, and takes action based on the value of this property. If the id matches that of the Notes List page, the handler invokes the private function renderNotesList(), which we will define next.

The renderNotesList() function will ask the app’s data context for the list of cached notes, and it will render it within the Notes List page. Let’s create this function like so:

function renderNotesList() {

var notesList = dataContext.getNotesList();
var view = $(notesListSelector);

view.empty();

if (notesList.length === 0) {

$(noNotesCachedMsg).appendTo(view);
} else {

var notesCount = notesList.length;
var note;
var ul = $("").appendTo(view);
for (var i = 0; i < notesCount; i++) {
note = notesList[i];
$(""
+ ""
+ "" + note.title + ""
+ "" + note.narrative + ""
+ ""
+ "").appendTo(ul);
}

ul.listview();
}
};

After obtaining the cached notes from the data context, the renderNotesList() function empties the content section of the Notes List page. It then proceeds to either add a “No notes cached” message to the page if the cached notes array is empty, or create an html list with a list item for each cached note.

Observe that after adding the html list to the page, we need to call the jQuery Mobile listview() method on the list. This will apply jQuery Mobile’s list enhancements to the list.

Notice as well that each list item uses the list-item-narrative css class. We will define this class in the app.cc file, which we will place in the css folder:

This is the class definition:

.list-item-narrative
{
	color: #666666;
	font-weight: normal;
}

With the index.html file and the controller module in place, we are ready to check how we did. Let’s open the index.html file in our favorite browser and see what happens. If everything went well, we should see something like this:

What do you think?

Next Steps

In the next chapter of this series we will work on the features that will allow our users to create, edit and delete notes.

Downloads

Download the source code for this article: Building a jQuery Mobile App Part 2 Src.zip

The Entire Series

Building a jQuery Mobile Application, Part 1

Jorge — Mon, 07 Nov 2011 15:20:35 +0000

This is the first part of a series of articles about how to create a mobile app using jQuery Mobile. As in my Sencha Touch tutorials, what we will do in this series is create a mobile web application that allows its users to take notes and save them in the device running the app.

We will engineer our business logic using JavaScript modules and classes, and we will use the jQuery Mobile framework to help us create our presentation layer. We will build the app following a behavior-driven approach with the help of the Jasmine framework. For each use case, we will create a specification using Jasmine, then we will implement the specification in the application.

In this first part of the tutorial, we are going to talk about the overall design of the application, and we will complete the following tasks:

Define the features of the application
Create low fidelity user interface mock-ups
Begin creating Jasmine specifications for the app’s public interface
Begin implementing the app’s public interface

Let’s get started.

Application Features

The application has a simple feature set. We want to give our customers the following abilities:

Create notes.
Edit notes.
Delete notes.
Store notes on the device that is running the application, across browser sessions.
View the entire collection of notes.

The Main Views

The first thing we need in the app is an interface for our users to create and edit notes. We can do this with a form, which we will call Note Editor. The form will look just like this mock-up, which I created using Balsamiq Mockups:

In addition, need a view that renders a list of the existing notes. The Notes List view will be the main view of the application. Our users will first see this view when they launch the app. This is how the Notes List should look:

We will connect the Notes List with the Note Editor in such a way that the Notes List will correctly reflect note additions, edits, and deletions.

OK. We defined the features and look of the app, which brings us right into the realm of specifications and testing.

Behavior-Driven Development and the Jasmine Framework

As I mentioned earlier, we will build the application in a modular fashion. This will allow us to define and test the business logic independently of the presentation layer. Our work on the business logic will start with a brief introduction to behavior-driven development with the Jasmine framework.

Jasmine is a framework that allows you to test your JavaScript code in a behavior-driven way. What this means is that you can write tests with Jasmine in a natural language that describes the purpose and benefit of the code under test. As a result, it will be easy for you as developer, and other stakeholders, to focus on the reason and purpose of the code and not the technical details.

I’m going to pause here for a quick note on testing frameworks. Some people go to war over what testing framework or method you use. I’m not one of them. And I happen to think that Jasmine is a good tool for the job at hand, as are many other tools.

This is an example of a test we will use later in this series that will help you understand how Jasmine works:

describe("Notes functions", function () {

    it("Should return a NoteModel instance", function () {

        var note = Notes.app.createNote();

        expect(note instanceof Notes.model.NoteModel).toBeTruthy();
    });
});

We are using various Jasmine features in this example. One is the function describe(), which we use to create a container for your specifications. In Jasmine, these containers are called “suites”.

The concept of a specification, or “spec”, is implemented with the function it(). When you call it(), you pass a string describing the specification, as well as a function that defines a test for the specification. In the example, we’re expressing that our code should be able to create and return a NoteModel instance.

The third feature we’re using is the expect() function, which expresses an expectation about the behavior of the application. The call to expect() will include the use of expectation matchers. In the example we use the toBeThruthy() matcher to express that our test will pass if the results are true.

Within the it() function, you will generally write the code needed to set up your test, as well as one or more calls to expect(), which will define your expectations.

Getting Ready to Use Jasmine

We need to take care of creating our application’s folders before we can use Jasmine. We will create a main folder for the application, which we will name “NotesApp”. In this folder, we will create an “app” directory where we will place the business logic and presentation files, and a “spec” directory, where we will place the Jasmine test suites. In addition, we will create a “Lib” directory, which will contain folders for the libraries our application will use.

The folders should look as depicted below:

If you’re curious about the “jqm” and “jstorage” folders, these are the containers where we will place the jQuery Mobile and JStorage frameworks. Don’t worry about them now, we will review them later.

Now we can download Jasmine, and place its files in the “jasmine” directory:

Let’s go ahead and create our first source files. One for the application, app.js, and one for the Jasmine test suites, AppSpec.js:

Finally, let’s create the specrunner.html file. This is the html file that will run our Jasmine test suites. The file is included in the Jasmine download, and we will need to change it so it has references to the libraries used by the application under test.

Here’s the source for the head and body sections of our specrunner.html file:

   
   
    css" rel="stylesheet" type="text/css" />

Note how the file has references to the Jasmine framework, as well as our application and specifications files.

Let’s place the specrunner.html file in the “NotesApp” directory, as depicted below:

OK, our main files are in place and it’s time to start building the application. Let’s do it.

Mapping Application Features to Business Logic Specifications

The first thing we want is making sure the application’s namespace exists. We can define this specification in the AppSpec.js file:

describe("Public interface exists", function () {

    it("Defines the app", function () {
        expect(Notes.app).toBeDefined();
    });

});

Note that we’ve placed this spec inside a suite named “Public interface exists”. This suite will contain all the specs that test that the public functions of the business logic exist. The spec itself is self-explanatory, asserting the expectation that the application’s namespace is defined.

Let’s run the test and see what happens. If we open the specrunner.html file in our favorite browser and check the output of the test, we should see something like this:

Our expectation of a defined application namespace just failed. This is OK because we haven’t defined the namespace yet. Let’s define it in the app.js file like so:

var Notes = Notes || {}
Notes.app = (function () {

    return {}

})();

If we run the test now, it should pass:

OK. Simple, but good enough for you to see the rhythm that we want to establish here: Define behavior, test, implement behavior, and test again. Let’s move on to more interesting behaviors.

Next, we want to define the ability to render the list of notes cached on the device. For this to occur, our business logic should be able to pass a list of notes to the presentation layer. We will define this behavior with a couple of Jasmine specifications.

The first specification looks like this:

describe("Public interface exists", function () {
    // App namespace test omitted...
    //
    //
    it("Should have public interface to return notes list", function () {
        expect(Notes.app.getNotesList).toBeDefined();
    });

});

This spec is also self-explanatory, asserting the expectation that the business logic defines a getNotesList() function.

The second specification is a little more detailed:

describe("Public interface implementation", function () {

    it("Should return notes list", function () {

        var notesList = Notes.app.getNotesList();

        expect(notesList instanceof Array).toBeTruthy();
    });
});

This spec goes in a second suite, called “Public interface implementation”, where we will place specifications related to the actual implementation of the business logic’s behavior. The spec asserts that the getNotesList() function should return an Array class instance.

If we refresh specrunner.html in the browser, the tests should fail:

The tests failed because we’re missing the implementation of the behaviors we’re defining. Let’s go ahead and add the implementation like so:

Notes.app = (function () {

    var notesList = [];

    function getNotesList() {
        return notesList;
    }

    return {

        getNotesList: getNotesList

    }

})();

Now the tests should pass:

Are you with me so far? Don’t tell me you’re not liking this.

Next Steps

In the next chapter of this series we will continue implementing the business logic of the application.

Did you notice we didn’t do anything with jQuery Mobile in this chapter? That’s OK. We want to have our business logic well implemented and separated from the presentation layer. Later we will have plenty of time to take care of the user interface.

Stay tuned!

The Entire Series

Source Code

Here’s the source code for this article:

AppSpec.js

describe("Notes public interface exists", function () {

    it("Defines the app", function () {
        expect(Notes.app).toBeDefined();
    });

    it("Has public function: getNotesList", function () {
        expect(Notes.app.getNotesList).toBeDefined();
    });

});

describe("Notes functions", function () {

    it("Returns a list of notes", function () {

        var notesList = Notes.app.getNotesList();

        expect(notesList instanceof Array).toBeTruthy();
    });
});

app.js

var Notes = Notes || {}
Notes.model = Notes.model || {}

Notes.app = (function () {

    var notesList = [];

    function getNotesList() {
        return notesList;
    }

    return {

        getNotesList: getNotesList

    }

})();

New eBook – Building a Sencha Touch Application

Jorge — Sat, 22 Oct 2011 16:10:02 +0000

I just published the Building a Sencha Touch Application eBook. The book will teach you how to create a Sencha Touch 1.1.1 application that allows its users to take notes and store them on the device running the app.

You can preview the book using this link: Preview Ebook – Building a Sencha Touch Application.

I would like to thank Ted Jenkins, Alex Blount, James Brooks and Hector Iribarne for their feedback and help creating this book. Thank you, Ted, Alex, James and Hector.

I would also like to hear what you think about the book and how I can make the next version better. Please leave a comment if you have a few minutes.

Writing a Sencha Touch MVC Application

Jorge — Wed, 10 Aug 2011 23:56:33 +0000

In this article we will explore one of the approaches we can take to create a Sencha Touch application using the MVC pattern. I will base the tutorial on the Notes Application we created in the Writing a Sencha Touch Application series. Our goal is to build a new version of the Notes Application using Sencha Touch MVC.

The Notes Application allows its users to take notes and store them on the device running the app. The features we built into the app, which we will reproduce in the MVC version, are the following:

Ability to create notes
Ability to edit existing notes
Ability to delete notes
Ability to persist notes on the device running the application, across browser sessions

In terms of user interface, the application revolves around two views, the Notes List view and the Note Editor view:

Ready? Let’s get started.

The model-view-controller pattern in Sencha Touch

As of version 1.1.0 of Sencha Touch, the framework’s implementation of the model-view-controller pattern is, in my opinion, incomplete and poorly documented. However, we can still take advantage of it to build high-quality applications.

In general, a Sencha Touch MVC application will consist of one or more views, one or more data models and stores, and one or more controllers. Views have a dual role: they render representations of the data in the models, and capture and transmit user input to the controllers. Controllers will translate the user’s input into changes in the data and/or the behavior of the application. Models represent the application’s data and state.

In Sencha Touch MVC parlance, the mechanism by which views send messages to the controllers is called dispatch, and the controller functions used to handle these messages are called actions.

Let’s apply these concepts to our Notes Application and come up with a tentative design.

The Notes App use cases, MVC style

Based on our requirements list, we can translate our use cases into the following MVC workflows:

When the application launches, the user will be presented with a list of the existing notes, or an empty list if there are no notes saved. This will happen by invoking a controller’s index action, which in turn will render the Notes List view:
When our user needs to create a new note, she will tap the New button in the Notes List view. This will invoke the newnote action in a controller, where a new note will be created and loaded into the Note Editor view:
Similarly, when our user needs to edit a note, she will tap the disclosure button for the given note. This will invoke the editnote action in a controller, causing the note to be loaded into the Note Editor view:
Tapping the Save button in the Note Editor view will invoke a controller’s savenote action, where the note will be saved in notes cache and the Notes List view will be activated:
If our user taps the Trash button in the Note Editor view, the view will invoke a controller’s deletenote action. This action will delete the note loaded in the view and activate the Notes List view:
Tapping the Home button in the Note Editor view will invoke a controller’s canceledit action, which will discard any changes made to the loaded note, and activate the Notes List view:

Notice that I have referred to “a controller” in my descriptions of the use cases. This means that we still don’t know if we will use one or many controllers in the application. We will make this decision in a few minutes.

All right. Now that we have an idea about how we’re going to build the Notes Application, MVC-style, let’s talk about files.

Distributing a Sencha Touch application across multiple files

You should consider distributing your Sencha Touch application’s source code across multiple files. A single source file might be fine for a very small application, however, as the application and the development team grow, you can cut development and maintenance costs by using a multiple-files model.

What we will do for this example is, first, create the right folder structure for the application, and then create the different source files that will contain the application’s components. The folder structure reflects the MVC pattern we will use to build the application:

We have a root folder called app, and under it, folders for the models, views, controllers and data stores. Besides being self-explanatory, it follows Sencha’s recommendation to place models, views and controllers in separate folders. Sencha’s build tools are capable of leveraging this structure to create the application’s namespaces when it’s time to build a production-ready version of the source files.

At this point we have modeled our MVC workflows and created the right folder structure. What do you say about writing some code?

The Note data model

The Note model is the data model that represents a note. Its source goes in the NoteModel.js file, which we will place in the models folder. This is the source:

Ext.regModel('NoteModel', {
    idProperty: 'id',
    fields: [
        { name: 'id', type: 'int' },
        { name: 'date', type: 'date', dateFormat: 'c' },
        { name: 'title', type: 'string' },
        { name: 'narrative', type: 'string' }
    ],
    validations: [
        { type: 'presence', field: 'id' },
        { type: 'presence', field: 'title', message: 'Please enter a title for this note.' }
    ]
});

The Notes data store

The NotesStore is our notes cache. It uses the NoteModel class as its model and it’s configured to use an instance of the Ext.data.LocalStorageProxy class as its proxy. This allows us to save notes across browser sessions. We will place the NotesStore class in the NotesStore.js file, which lives in the stores folder. This is the store’s source:

Ext.regStore('NotesStore', {
    model: 'NoteModel',
    sorters: [{
        property: 'date',
        direction: 'DESC'
    }],
    proxy: {
        type: 'localstorage',
        id: 'notes-app-store'
    },
    getGroupString: function (record) {
        if (record && record.data.date) {
            return record.get('date').toDateString();
        } else {
            return '';
        }
    }
});

NotesApp.stores.notesStore = Ext.StoreMgr.get('NotesStore');

The Main view

As in the first version of the application, the application’s main view will serve as the viewport, hosting the Notes List view and the Note Editor view. This view’s class goes in the MainView.js file, which we will place in the views folder:

NotesApp.views.MainView = Ext.extend(Ext.Panel, {
    fullscreen: true,
    layout: 'card',
    cardSwitchAnimation: 'slide',
    initComponent: function () {

        Ext.apply(NotesApp.views, {
            notesListView: new NotesApp.views.NotesListView({ notesStore: NotesApp.stores.notesStore }),
            noteEditorView: new NotesApp.views.NoteEditorView()
        });

        this.items = [
            NotesApp.views.notesListView,
            NotesApp.views.noteEditorView
        ]

        NotesApp.views.MainView.superclass.initComponent.call(this);

        this.on('render', function () {
            NotesApp.stores.notesStore.load();
        });
    }
});

The Notes List view

We will use an instance of the NotesListView class to render the list of cached notes and allow the user to start the “new note” and “edit note” workflows. Its file, NotesListView.js, goes in the views folder. This is the source:

NotesApp.views.NotesListView = Ext.extend(Ext.Panel, {

    notesStore: Ext.emptyFn,
    notesList: Ext.emptyFn,

    layout: 'fit',

    initComponent: function () {

        this.newButton = new Ext.Button({
            text: 'New',
            ui: 'action',
            handler: this.onNewNote,
            scope: this
        });

        this.topToolbar = new Ext.Toolbar({
            title: 'My Notes',
            items: [
                { xtype: 'spacer' },
                this.newButton
            ]
        });

        this.dockedItems = [this.topToolbar];

        this.notesList = new Ext.List({
            store: this.notesStore,
            grouped: true,
emptyText: '

5px;">No notes cached.

',
            onItemDisclosure: true,
itemTpl: '
{title}
' +
                            '{narrative}'

        });

        this.notesList.on('disclose', function (record, index, evt) {
            this.onEditNote(record, index);
        }, this),

        this.items = [this.notesList];

        NotesApp.views.NotesListView.superclass.initComponent.call(this);
    },

    onNewNote: function () {
        Ext.dispatch({
            controller: NotesApp.controllers.notesController,
            action: 'newnote'
        });
    },

    onEditNote: function (record, index) {
        Ext.dispatch({
            controller: NotesApp.controllers.notesController,
            action: 'editnote',
            note: record
        });
    },

    refreshList: function () {
        this.notesList.refresh();
    }
});
Let’s pause here and examine a few details.
While the initComponent() function should be very familiar to you, things become interesting when we look at the helper functions onNewNote() and onEditNote(). These functions will allow us to signal the view’s controller that the user executed either the “new note” or “edit note” commands. The newnote or editnote controller actions will be invoked in response to these commands.
How does the view send these signals to the controller? Well, it’s pretty simple. Remember what I said earlier about dispatch? Every application gets a default instance of the Dispatcher class, which you can use to send requests to specific actions in a given controller. Invoking Ext.Dispatcher.dispatch() or its shorthand, Ext.dispatch(), will find the desired controller and call the correct controller action.
You should pass the controller and action arguments to the dispatch() function. And you can also pass any other parameters that the controller might need to execute the action correctly. For example, in the onEditNote() function we also pass the record corresponding to the note the user needs to edit.
The third function, refreshList(), will allow this view’s controller to re-render the list of notes in the view after the list has been modified.
OK, we already dispatched a couple of messages to a controller that does not exist. How about we create it?
How many controllers does a Sencha Touch MVC application need?
I don’t think they make rules for this. It depends on the application. I know that the Notes App is small: three simple views and six actions. It looks like one controller is enough for this one.
Let’s create the NotesController.js file in the controllers folder, and add the following code to it:
Ext.regController('NotesController',{

    'index': function (options) {

    },

    'newnote': function (options) {

    },

    'editnote': function (options) {

    },

    'savenote': function (options) {

    },

    'deletenote': function (options) {

    },

    'canceledit': function (options) {

    }
});

NotesApp.controllers.notesController = Ext.ControllerManager.get('NotesController');
Starting to make more sense now? As you can see, the controller has the actions we have discussed. This is where we need to implement our use cases. But, before we do it, let’s work on the last view.
The Note Editor view
We will use an instance of the NoteEditorView class to give our users the ability to edit and delete notes. This class goes in the NoteEditorView.js file, in the views folder:
NotesApp.views.NoteEditorView = Ext.extend(Ext.form.FormPanel, {

    initComponent: function () {

        this.backButton = new Ext.Button({
            text: 'Home',
            ui: 'back',
            handler: this.backButtonTap,
            scope: this
        });

        this.saveButton = new Ext.Button({
            text: 'Save',
            ui: 'action',
            handler: this.saveButtonTap,
            scope: this
        });

        this.trashButton = new Ext.Button({
            iconCls: 'trash',
            iconMask: true,
            handler: this.trashButtonTap,
            scope: this
        });

        this.topToolbar = new Ext.Toolbar({
            title: 'Edit Note',
            items: [
                this.backButton,
                { xtype: 'spacer' },
                this.saveButton
            ]
        });

        this.bottomToolbar = new Ext.Toolbar({
            dock: 'bottom',
            items: [
                { xtype: 'spacer' },
                this.trashButton
            ]
        });

        this.dockedItems = [this.topToolbar, this.bottomToolbar];

        NotesApp.views.NoteEditorView.superclass.initComponent.call(this);
    },

    backButtonTap: function () {
        Ext.dispatch({
            controller: NotesApp.controllers.notesController,
            action: 'canceledit'
        });
    },

    saveButtonTap: function () {
        Ext.dispatch({
            controller: NotesApp.controllers.notesController,
            action: 'savenote'
        });
    },

    trashButtonTap: function () {
        Ext.dispatch({
            controller: NotesApp.controllers.notesController,
            action: 'deletenote'
        });
    },

    items: [{
        xtype: 'textfield',
        name: 'title',
        label: 'Title',
        required: true
    }, {
        xtype: 'textareafield',
        name: 'narrative',
        label: 'Narrative'
    }]
});
The helper functions saveButtonTap(), trashButtonTap() and backButtonTab() will allow us to signal the controller that the “save note”, “delete note” or “cancel edit” commands were executed by the user. The application will run the savenote, deletenote or canceledit controller actions in response to these commands.
Now that our views are finished, let’s implement the controller actions.
Implementing controller actions
Back in the NotesController class, as we’ve already discussed, the index action will create the Main view and activate the Notes List view:
'index': function (options) {

    if (!NotesApp.views.mainView) {
        NotesApp.views.mainView = new NotesApp.views.MainView();
    }

    NotesApp.views.mainView.setActiveItem(
        NotesApp.views.notesListView
    );
}
The index action will be invoked when the application launches. We will see how this is done when we implement the application’s launch() function.
The newnote controller action will create a new note, load it into the Note Editor view, and activate the view:
'newnote': function (options) {

    var now = new Date();
    var noteId = now.getTime();
    var note = Ext.ModelMgr.create({ id: noteId, date: now, title: '', narrative: '' },
        'NoteModel'
    );

    NotesApp.views.noteEditorView.load(note);
    NotesApp.views.mainView.setActiveItem(
        NotesApp.views.noteEditorView,
        { type: 'slide', direction: 'left' }
    );
}
We need the editnote action to load the selected note into the Note Editor view:
'editnote': function (options) {

    NotesApp.views.noteEditorView.load(options.note);
    NotesApp.views.mainView.setActiveItem(
        NotesApp.views.noteEditorView,
        { type: 'slide', direction: 'left' }
    );
}
The savenote action will save the note in the cache and activate the Notes List view:
'savenote': function (options) {

    var currentNote = NotesApp.views.noteEditorView.getRecord();

    NotesApp.views.noteEditorView.updateRecord(currentNote);

    var errors = currentNote.validate();
    if (!errors.isValid()) {
        currentNote.reject();
        Ext.Msg.alert('Wait!', errors.getByField('title')[0].message, Ext.emptyFn);
        return;
    }

    if (null == NotesApp.stores.notesStore.findRecord('id', currentNote.data.id)) {
        NotesApp.stores.notesStore.add(currentNote);
    } else {
        currentNote.setDirty();
    }

    NotesApp.stores.notesStore.sync();

    NotesApp.stores.notesStore.sort([{ property: 'date', direction: 'DESC'}]);

    NotesApp.views.notesListView.refreshList();

    NotesApp.views.mainView.setActiveItem(
        NotesApp.views.notesListView,
        { type: 'slide', direction: 'right' }
    );
}
Next comes the deletenote action. This action will delete the note loaded in the Note Editor and activate the Notes List view:
'deletenote': function (options) {

    var currentNote = NotesApp.views.noteEditorView.getRecord();

    if (NotesApp.stores.notesStore.findRecord('id', currentNote.data.id)) {
        NotesApp.stores.notesStore.remove(currentNote);
    }

    NotesApp.stores.notesStore.sync();
    NotesApp.views.notesListView.refreshList();

    NotesApp.views.mainView.setActiveItem(
        NotesApp.views.notesListView,
        { type: 'slide', direction: 'right' }
    );
}
Finally, the controller’s canceledit action will discard any changes made to the loaded note, and activate the Notes List view:
'canceledit': function (options) {

    NotesApp.views.mainView.setActiveItem(
        NotesApp.views.notesListView,
        { type: 'slide', direction: 'right' }
    );
}
You with me so far? We’re almost done.
Compared to the first version of the app, we’ve moved most of the application’s behavior out of the views, which now deal strictly with UI matters, and into a central location. I can see the MVC version being easier to understand and support.
Now that we have our data store, model, views and controller in place, we’re just missing the piece that will get this whole mechanism going.
Launching the application
We will place our app’s entry point in the app.js file, app folder, together with the index.html and app.css files. We will use app.js to create our application’s instance like so:
var App = new Ext.Application({
    name: 'NotesApp',
    useLoadMask: true,

    launch: function () {
        Ext.dispatch({
            controller: NotesApp.controllers.notesController,
            action: 'index'
        });
    }
});
And that’s it. Makes sense?
As you can imagine, this is not the only approach you can take for incorporating the MVC pattern in a Sencha Touch app. You can go from rolling out your own implementation, to taking full advantage of the framework’s built-in features, which I think are still a work in progress. Either way, you should be able to reach a satisficing solution that makes your application easier to develop and more maintainable.
What do you think?
Download this tutorial’s source: NotesApp-v1.zip

Writing a Sencha Touch Application, Part 4

Jorge — Tue, 28 Jun 2011 00:51:09 +0000

This is the last of a four-part series on how to write a Sencha Touch application. If you’re new to the series, here are the links to the previous installments:

In part 3 of this tutorial we worked on the Note Editor and added the ability to create notes. It is time now to let our users edit and delete notes. Let’s work on the edit note feature first.

Disclosure events in a Sencha Touch List

When the person using the application touches a note’s disclosure button in the Notes List view, the selected note should be displayed in the Edit Note view:

We can complete this feature by implementing the onItemDisclosure handler of the notes list. Here’s the code:

NotesApp.views.notesList = new Ext.List({
    id: 'notesList',
    store: 'NotesStore',
    onItemDisclosure: function (record) {
        var selectedNote = record;
        NotesApp.views.noteEditor.load(selectedNote);
        NotesApp.views.viewport.setActiveItem('noteEditor', { type: 'slide', direction: 'left' });
    },
    itemTpl: '
{title}' +
        '{narrative}',
    listeners: {
        'render': function (thisComponent) {
            thisComponent.getStore().load();
        }
    }
});

The handler function accepts the selected note as a parameter. What we need to do in the handler is load the note in the editor utilizing the editor’s load() method, and then, make the Note Editor view active via a call to the viewport’s setActiveItem().

Very cool. At this point we can switch over to the emulator, where we should be able to edit notes.

Removing records from a data store

Deleting notes is also very easy. The Trash button on the Note Editor view’s bottom toolbar will trigger this function. We need to change the button’ handler like so:

NotesApp.views.noteEditorBottomToolbar = new Ext.Toolbar({
    dock: 'bottom',
    items: [
        { xtype: 'spacer' },
        {
            iconCls: 'trash',
            iconMask: true,
            handler: function () {

                var currentNote = NotesApp.views.noteEditor.getRecord();
                var notesList = NotesApp.views.notesList;
                var notesStore = notesList.getStore();

                if (notesStore.findRecord('id', currentNote.data.id)) {
                    notesStore.remove(currentNote);
                }

                notesStore.sync();

                notesList.refresh();
                NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });
            }
        }
    ]
});

After acquiring references to the current note, the notes list and the notes data store, we use the store’s findRecord() function to find and remove the note loaded on the editor.

Next, we call sync() on the store to make the removal permanent, and proceed to re-render the notes list and make the Notes List view active.

This procedure is similar to the one we followed when we implemented the Save Note feature, although in this case we’re deleting the note, not saving it.

A quick check on the emulator should confirm that we can now delete notes.

Grouping items in a Sencha Touch List

One last thing we want to do is, in the Notes List view, render the notes grouped by date. This will make it easier for our users to work with their notes.

First, we need to tell our notesList Ext.List that it needs to render its items grouped. We can do this using the grouped config option like so:

NotesApp.views.notesList = new Ext.List({
    id: 'notesList',
    store: 'NotesStore',
    grouped: true,
    emptyText: 'No notes cached.',
    onItemDisclosure: function (record) {
        var selectedNote = record;
        NotesApp.views.noteEditor.load(selectedNote);
        NotesApp.views.viewport.setActiveItem('noteEditor', { type: 'slide', direction: 'left' });
    },
    itemTpl: '{title}' +
        '{narrative}',
    listeners: {
        'render': function (thisComponent) {
            thisComponent.getStore().load();
        }
    }
});

Then, we need to override the getGroupString() function of the NotesStore:

Ext.regStore('NotesStore', {
    model: 'Note',
    sorters: [{
        property: 'date',
        direction: 'DESC'
    }],
    proxy: {
        type: 'localstorage',
        id: 'notes-app-store'
    },
    getGroupString: function (record) {
        if (record && record.data.date) {
            return record.get('date').toDateString();
        } else {
            return '';
        }
    }
});

You can define the grouping behavior of the store using the groupField property and the getGoupString() function.

The getGroupString() function returns the string to group on, based on the store’s data model’s properties. By default, getGroupString() returns the value of the groupField property. In our case we want to use the value of the note’s date as the group’s header, but we want to format the value as a date.

If we check the emulator, the notes taken the same day should render under the same group header:

We made it!

This is pretty much it. A very simple Sencha Touch application and an easy way to learn some of the features of the Sencha Touch framework.

I hope you take this app to the next level as you learn more about the framework.

And don’t forget to leave a comment letting me know the Sencha Touch topics about which you would like me to write.

Download the Notes App: Notes-App-v1.0.zip

Here’s the rest of the series:

Writing a Sencha Touch Application, Part 3

Jorge — Tue, 21 Jun 2011 01:54:36 +0000

This is the third chapter of the Sencha Touch tutorial where we’ve been building a small application that allows its users to create notes and store them on their mobile devices. If you haven’t checked them out, here are the links to the previous installments:

In parts 1 and 2 of the tutorial we built the Notes List view. Now we need to create the Note Editor view; which will allow our users to create, update and delete notes. In this article we will take the idea in the mock-up and we will create a great-looking widget:

Creating a Sencha Touch Form Panel

Based on the Note Editor mockup, our view needs a couple of toolbars and a couple of form fields that will capture the Note’s title and narrative. Let’s create the form fields first:

NotesApp.views.noteEditor = new Ext.form.FormPanel({
    id: 'noteEditor',
    items: [
        {
            xtype: 'textfield',
            name: 'title',
            label: 'Title',
            required: true
        },
        {
            xtype: 'textareafield',
            name: 'narrative',
            label: 'Narrative'
        }
    ]
});

We are using the Ext.form.FormPanel class, one of the simplest ways to work with form fields in Sencha Touch, to define a note editor instance. While a TextArea field will facilitate editing the note’s narrative, the view will capture the note’s title with a Text field.

We’ve added the required: true config option to the title field to signal that we won’t allow notes without a title. When we implement the Save Note feature we will see how we can leverage the required config option of the field, and the validations config option of the Note’s data model, to alert our users that the note’s title is required.

Before we add the toolbars it is a good idea to check how the form looks. Let’s make a quick change in the viewport definition so it renders the note editor, just for testing purposes, instead of the notesListContainer instance we defined previously:

NotesApp.views.viewport = new Ext.Panel({
    fullscreen: true,
    layout: 'card',
    cardAnimation: 'slide',
    items: [NotesApp.views.noteEditor] // TODO: revert to [NotesApp.views.notesListContainer]
});

This is what we should see using the emulator:

Adding top and bottom toolbars to a Sencha Touch Panel

We are ready to take care of the toolbars. The first toolbar we will create is the one that will host the Home and Save buttons:

NotesApp.views.noteEditorTopToolbar = new Ext.Toolbar({
    title: 'Edit Note',
    items: [
        {
            text: 'Home',
            ui: 'back',
            handler: function () {
                // TODO: Transition to the notes list view.
            }
        },
        { xtype: 'spacer' },
        {
            text: 'Save',
            ui: 'action',
            handler: function () {
                // TODO: Save current note.
            }
        }
    ]
});

When defining this toolbar we’re using the ui config option to give each of our toolbar buttons a distinct look and feel based on their function. We use the ui: ‘back’ value for the Home button because this button will trigger a transition back to the main view of the app. And we use ui: ‘action’ for the Save button. This indicates to the user that the button will trigger the most important feature of the view, which in this case is saving a note.

The bottom toolbar will host the Trash button, which will allow our users to delete notes. This is how we instantiate this toolbar:

NotesApp.views.noteEditorBottomToolbar = new Ext.Toolbar({
    dock: 'bottom',
    items: [
        { xtype: 'spacer' },
        {
            iconCls: 'trash',
            iconMask: true,
            handler: function () {
                // TODO: Delete current note.
            }
        }
    ]
});

There are a couple of details to which you need to pay attention here. First, look at how we use the dock config option to dock the toolbar to the bottom of the view. And last, how we use the iconCls and iconMask config options to render the trash icon within the button:

Now we can add the toolbars:

NotesApp.views.noteEditor = new Ext.form.FormPanel({
    id: 'noteEditor',
    items: [
        {
            xtype: 'textfield',
            name: 'title',
            label: 'Title',
            required: true
        },
        {
            xtype: 'textareafield',
            name: 'narrative',
            label: 'Narrative'
        }
    ],
    dockedItems: [
            NotesApp.views.noteEditorTopToolbar,
            NotesApp.views.noteEditorBottomToolbar
        ]
});

Let’s switch over to the emulator to make sure the Note Editor’s elements are in the right place. Remember that we’ve temporarily modified the viewport so it just renders the Note Editor like so:

NotesApp.views.viewport = new Ext.Panel({
    fullscreen: true,
    layout: 'card',
    cardAnimation: 'slide',
    items: [NotesApp.views.noteEditor] // TODO: revert to [NotesApp.views.notesListContainer]
});

This is what we should see on the emulator:

Very nice, right?

All right, at this point we have built the Notes List and Note Editor views, and now we need to integrate the Note Editor with the application’s workflow. First, let’s make sure the editor becomes visible when the New button on the Notes List view is tapped.

How to change views in a Sencha Touch application

Let’s go back to the Notes List view and work on the handler for the New button. When the New button is tapped, we want to create a new note, pass it to the Note Editor and make the Note Editor visible:

NotesApp.views.notesListToolbar = new Ext.Toolbar({
    id: 'notesListToolbar',
    title: 'My Notes',
    layout: 'hbox',
    items: [
        { xtype: 'spacer' },
        {
            id: 'newNoteButton',
            text: 'New',
            ui: 'action',
            handler: function () {

                var now = new Date();
                var noteId = now.getTime();
                var note = Ext.ModelMgr.create(
                    { id: noteId, date: now, title: '', narrative: '' },
                    'Note'
                );

                NotesApp.views.noteEditor.load(note);
                NotesApp.views.viewport.setActiveItem('noteEditor', {type: 'slide', direction: 'left'});
            }
        }
    ]
});

Let’s examine this sequence one stept at a time. First, we create a new note using the ModelMgr’s class create() method:

var now = new Date();
var noteId = now.getTime();
var note = Ext.ModelMgr.create(
    { id: noteId, date: now, title: '', narrative: '' },
    'Note'
);

Then we pass the new note to the Note Editor, taking advantage of the FormPanel’s ability to load model instances with its load() method. A call to load() will populate the form’s fields with the values of the model’s fields:

NotesApp.views.noteEditor.load(note);

Finally, as our viewport uses a card layout ,we make the Note Editor visible using the viewport’s setActiveItem() method. When we call setActiveItem() we are passing the id of the card that we want to make active and an object describing the animation we want to use for the transition:

NotesApp.views.viewport.setActiveItem('noteEditor', {type: 'slide', direction: 'left'});

Before we check how the New button works on the emulator we need to fix the viewport’s items array. This is how we should configure the viewport’s items:

NotesApp.views.viewport = new Ext.Panel({
    fullscreen: true,
    layout: 'card',
    cardAnimation: 'slide',
    items: [
        NotesApp.views.notesListContainer,
        NotesApp.views.noteEditor
    ]
});

On the emulator we should see how the Note Editor becomes visible after tapping the New button on the Notes List view:

Everything OK so far?

With the New button working, we need to make sure the user can save the new note. This function will be triggered by the Save button on the Note Editor.

Validating a data model in Sencha Touch

When the Save button is tapped, we need the following things to happen:

The information in the form fields, the note’s title and narrative, is captured in a Note model instance
If the title of the note is empty, we will alert the user and abort the Save routine
If the note is new, we will add it to the notes cache; if it already exists, we will update the cache
We will then refresh the Notes List and make it the active view

Sounds complicated? It really isn’t. Let’s see how it’s done.

Before we implement the Save button’s tap handler, let’s modify the Note data model so it works better at the time of validation. What we will do is override the “message” property used by the validation function of the model’s title field. The goal here is to display a friendlier message (friendlier in my opinion ) when the field is invalid:

Ext.regModel('Note', {
    idProperty: 'id',
    fields: [
        { name: 'id', type: 'int' },
        { name: 'date', type: 'date', dateFormat: 'c' },
        { name: 'title', type: 'string' },
        { name: 'narrative', type: 'string' }
    ],
    validations: [
        { type: 'presence', field: 'id' },
        { type: 'presence', field: 'title', message: 'Please enter a title for this note.' }
    ]
});

We will use this message when we validate the note in the Note Editor view. Let’s implement the Save button’s tap handler so we can see how validation takes place:

NotesApp.views.noteEditorTopToolbar = new Ext.Toolbar({
    title: 'Edit Note',
    items: [
        {
            text: 'Home',
            ui: 'back',
            handler: function () {
                NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });
            }
        },
        { xtype: 'spacer' },
        {
            text: 'Save',
            ui: 'action',
            handler: function () {

                var noteEditor = NotesApp.views.noteEditor;

                var currentNote = noteEditor.getRecord();
                // Update the note with the values in the form fields.
                noteEditor.updateRecord(currentNote);

                var errors = currentNote.validate();
                if (!errors.isValid()) {
                    currentNote.reject();
                    Ext.Msg.alert('Wait!', errors.getByField('title')[0].message, Ext.emptyFn);
                    return;
                }

                var notesList = NotesApp.views.notesList;
                var notesStore = notesList.getStore();

                if (notesStore.findRecord('id', currentNote.data.id) === null) {
                    notesStore.add(currentNote);
                } else {
                    currentNote.setDirty();
                }

                notesStore.sync();
  notesStore.sort([{ property: 'date', direction: 'DESC'}]);

                notesList.refresh();

                NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });

            }
        }
    ]
});

In the handler function we first use the form panel’s getRecord() method to acquire a reference to the Note model loaded into the form. We then use the updateRecord() method to transfer the values from the form fields to the acquired model reference.

Validation takes place via the Errors object returned by the call to validate() on the Note data model. The call to isValid() tells us if there were errors. As only the note’s title is a required field, we can look up the message for this error, which we defined via the model’s validations config option, with the call to errors.getByField(‘title’)[0].message.

Having passed validation, we need to obtain a reference to the notes cache and add the note to the cache if it doesn’t already exist. The framework’s Store class makes this a breeze with its findRecord() method:

var notesStore = notesList.getStore();
if (notesStore.findRecord('id', currentNote.data.id) === null) {
    notesStore.add(currentNote);
}

After updating the notes data store, we use the sync() method to make the changes permanent. Then we use sort() to sort the notes by date. At this point we’re ready to render the updated notes list:

notesList.refresh();

NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });

Two interesting things about this step. Notice that this is one of the areas where the application can be optimized, as we’re re-rendering the notes list even if the list did not change. Also, as we’re navigating back to the main view, we configured the animation to use a slide transition from right to left (direction: ‘right’).

Before we finish this part of the tutorial, let’s implement the handler for the Home button. The Home button on the Note Editor will simply take us back to the Notes List. This is the code that does the trick:

{
    text: 'Home',
    ui: 'back',
    handler: function () {
        NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });'s next
    }
}

Can’t wait to see it working? Start your emulator and check it out. You should be able to create and save notes.

What’s next

We’ll leave editing and deleting notes for the next part of the tutorial. I you haven’t checked out the rest of the series, these are the links:

And here’s the application’s js source with the features we just built:

var App = new Ext.Application({
    name: 'NotesApp',
    useLoadMask: true,
    launch: function () {

        Ext.regModel('Note', {
            idProperty: 'id',
            fields: [
                { name: 'id', type: 'int' },
                { name: 'date', type: 'date', dateFormat: 'c' },
                { name: 'title', type: 'string' },
                { name: 'narrative', type: 'string' }
            ],
            validations: [
                { type: 'presence', field: 'id' },
                { type: 'presence', field: 'title', message: 'Please enter a title for this note.' }
            ]
        });

        Ext.regStore('NotesStore', {
            model: 'Note',
            sorters: [{
                property: 'date',
                direction: 'DESC'
            }],
            proxy: {
                type: 'localstorage',
                id: 'notes-app-store'
            }
        });

        NotesApp.views.noteEditorTopToolbar = new Ext.Toolbar({
            title: 'Edit Note',
            items: [
                {
                    text: 'Home',
                    ui: 'back',
                    handler: function () {
                        NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });
                    }
                },
                { xtype: 'spacer' },
                {
                    text: 'Save',
                    ui: 'action',
                    handler: function () {

                        var noteEditor = NotesApp.views.noteEditor;

                        var currentNote = noteEditor.getRecord();
                        // Update the note with the values in the form fields.
                        noteEditor.updateRecord(currentNote);

                        var errors = currentNote.validate();
                        if (!errors.isValid()) {
                            currentNote.reject();
                            Ext.Msg.alert('Wait!', errors.getByField('title')[0].message, Ext.emptyFn);
                            return;
                        }

                        var notesList = NotesApp.views.notesList;
                        var notesStore = notesList.getStore();

                        if (notesStore.findRecord('id', currentNote.data.id) === null) {
                            notesStore.add(currentNote);
                        } else {
                           currentNote.setDirty();
                        }

                        notesStore.sync();
                        notesStore.sort([{ property: 'date', direction: 'DESC'}]);

                        notesList.refresh();

                        NotesApp.views.viewport.setActiveItem('notesListContainer', { type: 'slide', direction: 'right' });

                    }
                }
            ]
        });

        NotesApp.views.noteEditorBottomToolbar = new Ext.Toolbar({
            dock: 'bottom',
            items: [
                { xtype: 'spacer' },
                {
                    iconCls: 'trash',
                    iconMask: true,
                    handler: function () {
                        // TODO: Delete current note.
                    }
                }
            ]
        });

        NotesApp.views.noteEditor = new Ext.form.FormPanel({
            id: 'noteEditor',
            items: [
                {
                    xtype: 'textfield',
                    name: 'title',
                    label: 'Title',
                    required: true
                },
                {
                    xtype: 'textareafield',
                    name: 'narrative',
                    label: 'Narrative'
                }
            ],
            dockedItems: [
                    NotesApp.views.noteEditorTopToolbar,
                    NotesApp.views.noteEditorBottomToolbar
                ]
        });

        NotesApp.views.notesList = new Ext.List({
            id: 'notesList',
            store: 'NotesStore',
            itemTpl: '
{title}
' +
                '
{narrative}
',
            onItemDisclosure: function (record) {
                // TODO: Render the selected note in the note editor.
            },
            listeners: {
                'render': function (thisComponent) {
                    thisComponent.getStore().load();
                }
            }
        });

        NotesApp.views.notesListToolbar = new Ext.Toolbar({
            id: 'notesListToolbar',
            title: 'My Notes',
            layout: 'hbox',
            items: [
                { xtype: 'spacer' },
                {
                    id: 'newNoteButton',
                    text: 'New',
                    ui: 'action',
                    handler: function () {

                        var now = new Date();
                        var noteId = now.getTime();
                        var note = Ext.ModelMgr.create(
                            { id: noteId, date: now, title: '', narrative: '' },
                            'Note'
                        );

                        NotesApp.views.noteEditor.load(note);
                        NotesApp.views.viewport.setActiveItem('noteEditor', { type: 'slide', direction: 'left' });
                    }
                }
            ]
        });

        NotesApp.views.notesListContainer = new Ext.Panel({
            id: 'notesListContainer',
            layout: 'fit',
            html: 'This is the notes list container',
            dockedItems: [NotesApp.views.notesListToolbar],
            items: [NotesApp.views.notesList]
        });

        NotesApp.views.viewport = new Ext.Panel({
            fullscreen: true,
            layout: 'card',
            cardAnimation: 'slide',
            items: [
                NotesApp.views.notesListContainer,
                NotesApp.views.noteEditor
            ]
        });
    }
});

Writing a Sencha Touch Application, Part 2

Jorge — Mon, 13 Jun 2011 12:33:12 +0000

In the first part of this Sencha Touch tutorial we started building an app that allows its user to take notes and store them on the device. Having created the foundation of the application we are in the process of building the Notes List view, which at this point looks like this:

This view is missing the Ext.list that will render the notes created by the user and the New button in the toolbar, as depicted in the mock-up we created in the first part of this tutorial:

Let’s work on the notes list.

Creating a Data Model in Sencha Touch

Before can create the list, we need to create the data model that will represent a note. We do this using the Ext.regModel() method:

Ext.regModel('Note', {
    idProperty: 'id',
    fields: [
        { name: 'id', type: 'int' },
        { name: 'date', type: 'date', dateFormat: 'c' },
        { name: 'title', type: 'string' },
        { name: 'narrative', type: 'string' }
    ],
    validations: [
        { type: 'presence', field: 'id' },
        { type: 'presence', field: 'title' }
    ]
});

Our Note model, as any data model in Sencha Touch, is defined as a set of fields and the methods and properties relevant to it. The model has built-in support for validation, which we use to assert, via the validations config option, that the id and title properties require a value. We will see how model validation takes place when we build the note editor.

Data models also support associations with other models via has-many and belongs-to relationships. Although we will not use associations in this tutorial, I urge you to check out their documentation and examples. You will likely run into associations when building Sencha Touch applications.

Configuring a Sencha Touch Data Store to use HTML5 local storage

We also need a mechanism to cache our notes. The Ext.regStore() function allows us to create a data store, our notes cache, like so:

Ext.regStore('NotesStore', {
    model: 'Note',
    sorters: [{
        property: 'date',
        direction: 'DESC'
    }],
    proxy: {
        type: 'localstorage',
        id: 'notes-app-localstore'
    }
});

Ext.regStore() creates and registers a store with the framework’s Store Manager. Just as other classes in the framework do, you can use the Store Manager to lookup and modify the data stores in your application.

Our NotesStore’s model config option is the Note model. We also use the sorters option to specify that the notes will be sorted by date in descending order.

Remember that one of our application’s features is the ability to persist notes between browser sessions? The task of loading and saving model data is delegated to the store’s proxy. We use the proxy config option to define our proxy as an instance of the Ext.data.LocalStorageProxy class. This class uses the HTML5 localStorage API to save model data locally on the client browser. I find this abstraction of the local storage API one of the nicest features of the Sencha Touch framework.

Creating a Sencha Touch list

With data model and store ready, we can create the notes list like so:

NotesApp.views.notesList = new Ext.List({
    id: 'notesList',
    store: 'NotesStore',
    itemTpl: '
{title}
' +
        '
{narrative}
'
});

Nothing complicated here. The list will use the NotesStore, passed by name through the store config option. We define the markup used to render the notes with the itemTpl config option. The markup uses the list-item-title and list-item-narrative classes, which we will add to the app.css file:

.list-item-title
{
    float:left;
    width:100%;
    font-size:90%;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}
.list-item-narrative
{
    float:left;
    width:100%;
    color:#666666;
    font-size:80%;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}
.x-item-selected .list-item-title
{
    color:#ffffff;
}
.x-item-selected .list-item-narrative
{
    color:#ffffff;
}

Now let’s add the list to the container panel using the panel’s items config option:

NotesApp.views.notesListContainer = new Ext.Panel({
    id: 'notesListContainer',
    layout: 'fit',
    html: 'This is the notes list container',
    dockedItems: [NotesApp.views.notesListToolbar],
    items: [NotesApp.views.notesList]
});

Want to do a quick run on the simulator to see how we are doing? All right, but before we do that, let’s add a dummy note to the NotesStore just so we can see how the list renders a note. We can do this using the data config option:

Ext.regStore('NotesStore', {
    model: 'Note',
    sorters: [{
        property: 'date',
        direction: 'DESC'
    }],
    proxy: {
        type: 'localstorage',
        id: 'notes-app-store'
    },
    // TODO: remove this data after testing.
    data: [
        { id: 1, date: new Date(), title: 'Test Note', narrative: 'This is simply a test note' }
    ]
});

On the device emulator the Notes List view should look like this:

At this point our Notes List view is almost ready. We’ve added the toolbar, the notes list, the data model and the store that will cache the notes. We’re just missing the two navigation aids that will allow the user to open the Note Editor view: the New button on the toolbar and the disclosure button on each list item.

Adding buttons to a Sencha Touch toolbar

This is how we add the “New” button to the toolbar:

NotesApp.views.notesListToolbar = new Ext.Toolbar({
    id: 'notesListToolbar',
    title: 'My Notes',
    layout: 'hbox',
    items: [
        { xtype: 'spacer' },
        {
            id: 'newNoteButton',
            text: 'New',
            ui: 'action',
            handler: function () {
                // TODO: Create a blank note and make the note editor visible.
            }
        }
    ]
});

Using an hbox layout and adding a spacer to the toolbar allows us to push the New button all the way to the right. We will leave the handler function alone for a while. After we create the Note Editor view we’ll add code to open the editor from this handler.

Implementing disclosure buttons in a Sencha Touch list

The disclosure button is also very easy to implement by means of the onItemDisclosure config option:

NotesApp.views.notesList = new Ext.List({
    id: 'notesList',
    store: 'NotesStore',
    itemTpl: '
{title}
' +
        '
{narrative}
',
    onItemDisclosure: function (record) {
        // TODO: Render the selected note in the note editor.
    }
});

We’re using one of the onItemDisclosure overrides to bind a listener to the tap event on any list item. All we will need to do inside this listener is grab the record that received the tap and pass it to the Note Editor view. But we will finish this handler later, after we create our Note Editor.

Where are we?

Let’s stop for another quick check on the simulator. The app should look like this:

Cool! We have completed the main view of the application, except the two event handlers that will allow our users to navigate to the Note Editor.

We are now ready to begin work on the Note Editor:

But that will happen in the next chapter of this series. For now I will leave you with the source code of the app at this stage:

var App = new Ext.Application({
    name: 'NotesApp',
    useLoadMask: true,
    launch: function () {

        Ext.regModel('Note', {
            idProperty: 'id',
            fields: [
                { name: 'id', type: 'int' },
                { name: 'date', type: 'date', dateFormat: 'c' },
                { name: 'title', type: 'string' },
                { name: 'narrative', type: 'string' }
            ],
            validations: [
                { type: 'presence', field: 'id' },
                { type: 'presence', field: 'title' }
            ]
        });

        Ext.regStore('NotesStore', {
            model: 'Note',
            sorters: [{
                property: 'date',
                direction: 'DESC'
            }],
            proxy: {
                type: 'localstorage',
                id: 'notes-app-localstore'
            },
            // TODO: remove this data after testing.
            data: [
                { id: 1, date: new Date(), title: 'Test Note', narrative: 'This is simply a test note' }
            ]
        });

        NotesApp.views.notesList = new Ext.List({
            id: 'notesList',
            store: 'NotesStore',
            itemTpl: '
{title}
' +
                '
{narrative}
',
            onItemDisclosure: function (record) {
                // TODO: Render the selected note in the note editor.
            }
        });

        NotesApp.views.notesListToolbar = new Ext.Toolbar({
            id: 'notesListToolbar',
            title: 'My Notes',
            layout: 'hbox',
            items: [
                { xtype: 'spacer' },
                {
                    id: 'newNoteButton',
                    text: 'New',
                    ui: 'action',
                    handler: function () {
                        // TODO: Create a blank note and make the note editor visible.
                    }
                }
            ]
        });

        NotesApp.views.notesListContainer = new Ext.Panel({
            id: 'notesListContainer',
            layout: 'fit',
            html: 'This is the notes list container',
            dockedItems: [NotesApp.views.notesListToolbar],
            items: [NotesApp.views.notesList]
        });

        NotesApp.views.viewport = new Ext.Panel({
            fullscreen: true,
            layout: 'card',
            cardAnimation: 'slide',
            items: [NotesApp.views.notesListContainer]
        });
    }
});

Stay tuned! And don’t forget to leave your comments or suggestions.

The rest of the series: