Tutorial: Todo App with Onsen UI and Azure

After having introduced how to create a Simple App for Windows Phone 8.1 using Onsen UI, it’s time to demonstrate the potentialities of our framework with a new tutorial! This time we will create a Todo App with Onsen UI, using the services provided by Azure, to host our data, and the new Onsen UI Templates for Visual Studio 2015.

For those that have never heard about it, Azure is Microsoft’s Cloud platform: a growing collection of services, storage, data and networking. Azure offers a wide range of tools, but we are just interested in suitable tools for the development of hybrid apps.

That’s why, during this tutorial, we will only implement a cloud-based backend service, using Azure Mobile Services. This will allow us to host our data in an easy and intuitive way, regardless of the mobile platform in which the app will be executed.

A full working Sample App is available on this GitHub repository, we invite you to take a look at it before starting!

Prerequisites

In order to develop Cordova Apps with Visual Studio, you need to have Windows 8.1 installed. Before starting, there are some prerequisites:

Install Apache Ant

Download Apache Ant from the official website. Once installed, test if you can run ant --version command through Windows Terminal (cmd.exe). If not, just add the Apache Ant directory into the Windows environment variables.

Install Node.js

Download Node.js from the official website. It gives you access to a program called npm, a package manager for Node.js. Once installed, test if you can run node --version command through Windows Terminal. If not, just add the Node.js directory into the Windows environment variables.

Install Cordova

Once Node.js and Apache Ant have been successfully installed, you can proceed with Cordova installation. You can download it from here.

npm install -g cordova

For more details, about how to use Cordova tool, please refer to Cordova documentation.

Install Microsoft Visual Studio 2015 RC

In this tutorial, we have used Microsoft Visual Studio 2015 RC Enterprise, which can be downloaded here. Before the installation, remember to select all the options related with Azure and Cordova Tools.

Download Onsen UI Templates for Visual Studio 2015

As announced recently, we have release Onsen UI Templates for Visual Studio 2015. As previously mentioned, we will use those templates in order to build our Todo App. You can download them at this link.

Subscribe Azure Free Trial

In order to be able to use Azure Services, you need an active subscription. In case you don’t have it, you can register for free and join the trial program, which lasts 30 days, at this link. Once the trial period has expired, you will not lose your data, but you will not be able to insert new data into the cloud storage.

Development

After all the prerequisites have been satisfied, it’s time to start the app development!

First of all, open Visual Studio 2015 and create a new project. After opening the new project menu, on the top right side, you can find a search box to find the desired template. Write Onsen and selecti the Onsen Tab Bar template. This template will be the base of our Todo App: it will quickly be expanded with new elements and functionalities.

In order to better understand what we are trying to build, you can try this sample, linked directly with the project’s GitHub repository.

Onsen UI Azure App

At this point, we need to link an Azure mobile service to our app. To do that, open the Server Explorer Menu (View->Server Explorer), select Azure and connect with your account. It should load the services that are available for your subscription. Right click on Mobile Services and create a new service. A new window will appear and you’ll be asked configure your mobile service. We called it TodoOnsenUI so, from now on, we’ll refer to it when we talk about the mobile service that we are using.

After the mobile service is created, a reference to the Mobile Services client library is added to the project and your project source code is updated. More specifically, a new folder called services will be created and, in one of its subfolders, a file called todoOnsen.js will be generated. It will contain the information needed to connect to the mobile service, like URL and app key. Now it’s time to create a table where to host our data. Right click on TodoOnsenUI and select Create Table、I called it TodoItem.

Now we have a table where to host our data, but we still need to customize it, adding new attributes. Unfortunately, it’s not possible to do it directly from Visual Studio, so we need to access the Azure portal. We can do it in two ways:

• Browser: navigate to the portal address (http://manage.windowsazure.com/).
• Visual Studio: open the Service Explorer, right click on the mobile service name and select Open in Management Portal.

Once the portal has been opened, navigate into the TodoOnsenUI service, go in DATA and select TodoItem table. You’ll notice that it’s still empty, but some attributes have already been created. They are mainly related with the ID of the records and the creation/modification timestamp. We need to add three new attributes: the title, the content and the active status of our item. To do it, just select COLUMNS from the menu and add the first two attributes as strings and the active attribute as boolean. This operation can be also done automatically the first time that we insert the data inside the database but, to be sure about the attributes type, it’s recommended to create them manually. You can also modify the database permissions in order to increase its security. As default, the access is allowed to all the users that have the key but an authentication process can be implemented. In this app, we haven’t implemented it, but if you are interested, take a look at this link.

Let’s start with the HTML and AngularJS controller!

HTML

To realize this Todo App, we have hosted all the HTML content inside a single HTML page: index.html. But you should notice that, inside it, we have hosted different pages by using the ons-template element. We chose this approach because the content of our app is very limited but, in case you want to expand it, we suggest you to create different HTML files.

Once the DOM has been fully loaded, an ons.ready() function, inside the controller, will load the view content. First of all we need to modify the default ons-tabbar element, linking it to the main pages of our app:

list.html

It contains all the Todo items. All its content is included inside ons-navigator element, which offers a more intuitive page navigation than ons-tabbar. From the ons-toolbar element, we can open addMemo.html, which will allow to add a new memo to the Todo list.

The list content is displayed in an ons-list element. With ng-repeat="stuff in items track by $index" we are able to get the content from the $scope.items array declared inside the AngularJS controller, which will be analyzed soon. We’ll use ng-class="{completed: stuff.completed}" to change dynamically the appereance of the ons-list-item: if stuff.completed is true, then the .completed class will be applied.

The content of the list has been saved inside a template HTML page, called template.html, because of its use in different HTML pages. To add it inside our list element, we have used ng-include="'template.html'"

template.html

As previously mentioned, this page contains the content of the ons-list-item element. More specifically, it contains a checkbox, two attributes of the $scope.items array and a button.

The checkbox element is used to mark a specific Todo item as completed. It’s bound with $scope.items.completed variable by using ng-model="stuff.completed". That means that every time one of the two elements will be modified, also the other one will automatically get modified in the same way.

Once the checkbox status changes, the toggleCompleted($index) will be executed. It will modify the status of the item in active or completed, and update its record inside the cloud storage.

The two attributes of the $scope.items array, that will be displayed, are the title and the content of the Todo item. To conclude, there is an ons-button element which, when clicked, will delete the list element from the cloud storage and from the local object array.

addMemo.html

This page contains two input fields where the user can insert the Todo item title and content. These two fields are bound with two different variables inside the controller, by using ng-model directive. For space reasons, in this sample app we have limited their size respectively to 10 and 20 characters.

Once the form has been compiled, it can be submitted by pressing an ons-button, which will call a function that will save the Todo item inside the cloud storage and the local object array. Using ng-disable directive, we can keep the submit button disabled until the form content is considered valid.

active.html — completed.html

These two pages contain, respectively, the Todo items that are marked as completed and still active. The HTML content is almost the same as list.html, the only difference are the ng-show and ng-hide directives which, while bound with stuff.completed, will display the completed or the hidden items.

CSS

In addition to the standard Onsen UI template, there are a couple of new classes that have been added to the CSS, in order to display some elements.

The .completed class will be applied dynamically, using ng-class to an ons-list-item element which contains the relative Todo item, in case the completed value of that item is true. It will just add a line-through effect to the text and change its color, to make the Todo item appears like completed.

The .destroy class is applied to the ons-button which, once clicked, will delete the memo from the cloud storage.

Mobile Service Javascript file

This file has been automatically generated once the Azure mobile service has been linked with the app, using Visual Studio. It can be found inside www/services/... folder and contains the connection URL of the mobile service and the key needed to authenticate. The content should be like this:

In case it differs, because of the default platform choose during the mobile service creation, we invite you to edit the file in this way.

Controller

The controller contains all the business logic of our app and it’s linked directly with the index.html page. We will now analyze some of the functions that characterize the app behavior.

ons.ready()

As mentioned inside the Onsen UI documentation, this function is called when Onsen UI initialization is done. If the app is running under Cordova or PhoneGap, it will also wait for its initialization (ondeviceready event).

Once the function is executed, the data are retrieved from the TodoItem table, hosted inside Azure cloud storage. If the operation succeeds, the content will be saved in a local object array. Because this array will contain the element that will be displayed inside the ons-list, we need to execute $scope.$apply to update the view content.

$scope.addMemo()

The purpose of this function is to add a new element inside the cloud storage and the local object array. This function is executed when the save memo button is pressed.

First of all, the save button is disabled, to avoid undesired user behavior, and a new memo object is created, based on the values of the two fields compiled by the user, inside addMemo.html page. Afterward, the new item will be sent to the cloud storage. The callback function will return the information about the item that was previously saved. The most important information is the id, which has been automatically created by the backend service and which is necessary for saving the element once it’ll be edited. In case the operation succeeds, the information will be added inside the local object array, the input fields will be clean, the list content view will be updated and the user will be redirected to the main Todo list page. In case of failure, the save button will be enabled, to allow another try, and an error message will be displayed.

$scope.deleteMemo()

This function’s purpose is to delete a Todo element from the cloud storage and the local object array. This function is executed when the delete button is pressed, inside the ons-list-item element. It takes as input the index of the element that the user wants to delete.

Once the delete button is pressed, an ons-notification-confirm elements appears and asks for a confirmation. Once the user approves the operation, the desired item will be removed from the cloud storage. If the operation succeeds, the item will be also removed from the local object array, and the list content view will be updated. Furthermore, the user will be informed about the success of the procedure by an ons-notification-alert element. In case of failure, an error log will be displayed.

$scope.toggleCompleted()

Once a checkbox element state changes, the relative Todo item is marked as completed or active. Every time this event happens, we need to save it in a permanent way inside the cloud storage and reflect the changes on the view.

The function that updates the values, inside the cloud storage, will take as input the ID of the element that we want to modify, and the modified attribute, in this case completed. If the operation succeeds, no instruction will be executed because the changes are already reflected on the view. Otherwise, if the operation fails the completed attribute will be restored to its previous status and the view will be updated.

Deployment

Once our application is ready, we can deploy it on our device (or emulator) in two ways:

Using Microsoft Visual Studio

This is the easiest solution. We just need to select the platform, the target device and to switch the Debug option to Release. We can also, optionally, choose the CPU for wich your app will be compatible. At this point, just by launching the procedure, the app will be automatically installed on the target device.

Using command line

Open the terminal and navigate in the root directory of the Cordova project, then execute:

cordova platform add 'platform name'

In case you have executed the app, with Visual Studio, on a platform, you can skip this step. That’s because the platform has already been added the first time the app has been executed.

In case you’ll experience crashes at the app’s startup or errors, we suggest you to install Cordova 4.3.0 (we had problems with Cordova 5.0.0), remove the platform and add it by command line. That’s because not always Visual Studio Apache Tools for Cordova is updated to the last version.

To change Cordova platform and remove the platform from the project just execute:

npm install cordova@4.3.0 
cordova platform rm 'platform name'

Also take a look at Azure Mobile Service plugin for Cordova at this GitHub repository, for new updates. We have used this version of the library, instead of the one autogenerated during the mobile service initialization.

To deploy the app we can use, depending by the platform and the target, these commands (you can find a full list of them on Cordova documentation).

cordova run android --device 
cordova run ios --device 
cordova run windows --device -- --phone

Conclusion

Another tutorial is over, we hope that you have enjoyed it learned about Onsen UI and Azure mobile service. Now you are ready to expand your app with new functionalities, maybe using the other features available from Azure, which offers a huge set of development tools able to satisfy even the most exigent developers.

We would invite you to let us know your experience with Onsen UI and how can we improve it, from your point of view. Moreover, let us know if there is any other tutorial that you would like to see on our blog, we would make the possible to satisfy your requests.

Continue to follow us and don’t forget to star our GitHub repository!

Originally published at onsen.io on May 23, 2015.