Integrating Backbone.js app with Data Sync

In this tutorial, you will learn how to integrate an existing Backbone based application with the Data Sync module of the Appear IQ platform. The tutorial is based on a well-established application idea of a simple task management application which allows users to create new tasks, mark them as completed and remove completed tasks from the list. Backbone is built on top of a Model-View-Presenter system, where models can be translated directly into Appear IQ's business documents with the help of a custom collection implementation. Let's look at an overview of the integrated ecosystem:

The tutorial consists of six steps:

1. getting the sample Backbone app - We have a prepared a tutorial app based on Backbone, which you will

integrate with the AIQ Data Sync module.

2. initializing the AIQ API - The API generates an event called aiq-ready after it has finished loading. You have

to wait for this event before loading the data in order to have full access to the API.

3. defining a collection - Backbone Collections take care of synchronizing application data with external data

sources. In case of Appear IQ, the collection must translate CRUD operations into DataSync API calls.

4. making models compatible with AIQ - In order for your model classes to be recognized as Appear IQ's

business documents, they must be enriched with a document identifier called _id. You can also leverage other AIQ

properties.

5. registering listeners - An AIQ-enabled application not only manages business documents locally, but also

reacts to remote changes in those documents.

6. running the app on your device - To finish, you will be able to publish the app on your smartphone

This tutorial assumes that you already have basic knowledge of HTML and JavaScript, as well as Backbone.js framework. If

you feel that you need to go through the basics, don't hesitate to read external tutorials like this and this. Backbone-related

 

resources can be found here. Remember to also consult the API documentation in case you get lost or you are not sure

what the Appear IQ API being used does.does.

Prerequisites In order to follow the tutorial, you will need the following components:

● AIQ Mobile HTML5 SDK tool, version 1.1.0 or later In order to publish your application to your device, you will also need an account on the Appear IQ Mobility Platform. Please sign-up to get your credentials. Alternatively, you can also carry on and test the application in a local web browser.

Step 1: Getting the tutorial app We have prepared a simple app based on Backbone in order to illustrate the integration steps with the Appear IQ Data Sync module. First, you need to download the tutorial app from Github. You will see two folders there:

● todo - vanilla Backbone enabled application which you can use as a base for this tutorial

● todo+aiq - the end result of the tutorial, integrated with AIQ The tutorial will take place in the todo folder. However feel free to jump at anytime to the todo+aiq folder to see the intended outcome!

Step 2: Initializing the API We have implemented a mock version of the AIQ API for local development and testing. The first step is to add that mock implementation to your app, so that you can test it in your local browser. You can get the API mock implementation in the boilerplate app generated by the Mobile HTML5 SDK tool. For that, go to a temporary directory and run the following command.

The generate command will generate a boilerplate app, which is traditionally used to create an app from scratch. In the present case, you will only be copying the API mock implementation to the existing tutorial app.

From the boilerplate app, copy the aiq-api.js file located in the aiq folder into an aiq folder in your application root (you have to create the aiq folder as well). As with every essential resource, you have to reference it in the index.html file in your application root:

This will immediately start initializing the API modules. To know when they are ready to use, you have to register a listener for the event called aiq-ready. In case of this TODO application, you can delay the whole initial require statement that kickstarts the launch. In the index.html file, replace the initialization line with the following script: Once you implement and initialize the custom collection, it will immediately try to bind to AIQ events, which will fail if the AIQ API is not ready. Calling it after the aiq-ready event is triggered will prevent it.

 

 

Step 3: Defining a collection Now you can move on to building a custom collection, which will synchronize the data with your backend system through the AIQ Data Sync. Create a file called backbone.aiq-datasync.js in the libs folder (the local storage based collection which the application has been using is also located in this folder, in a file called backbone.localStorage.js) and define a basic structure:

 

This is an empty skeleton of a Backbone collection which delegates CRUD operation calls passed to the well known sync method to the private implementations starting with an underscore. You have to go through these methods (read, create, update and delete) and implement them so that they operate on the AIQ API. The _createHandler method is used to generate callbacks to the AIQ API methods. The sync method is a part of the public Collection API and is called every time a CRUD operation is performed on a collection.

Data Sync module of the AIQ API has a method called synchronize, which serves a different purpose than the sync method in the custom collection and shouldn't be mistakingly used in a similar context.

Models in Backbone framework don't carry the information about the names of their types, which your new collection will use to call the Data Sync methods. You need to create an artificial binding between the collection and its model by introducing a custom type field specified when inheriting from the base DataSyncCollection. The initialize method is a good place to enforce this binding:

As shown in the example above, you can delegate the sync method from the attached model to the sync method you implemented in your collection, so that you don't have to implement the same functionality twice.

 In order for your new collection to get used instead of the old local storage implementation,

you have to create a reference to it in the requirejs.config.js file located in the app folder:

Instead of adding a new entry, you can replace with it the old and now obsolete reference to the local storage implementation:

Once the reference is defined, you can use it as a base for the TODO collection. Open app/collections/todos.js file, replace the old dependency to the local storage extension with the new one, to your new DataSyncCollection class. Get rid of the localStorage property (it is no longer needed) and be sure to add the type property to the TodoCollection definition. The result should look like this:

 As explained in the documentation, AIQ enables you to define a set of mock data which you

can bundle with your app to simulate data sent by your backend system. In short, it helps you develop your mobile app without being tied to the backend being ready. For the sake of that tutorial, you will use mock data when working locally in your browser. To that end, let's define some mock tasks by creating a datasync.json file in the mock-data folder in the application root (you have to create it first) and filling it with the following content:

This will define three TODO documents illustrating what your backend could have sent. In order to make use of the created data, you have to implement the read operation of your collection. It is called when you initialize the collection. The _read method (as specified in the sync method of your collection) will retrieve the business documents from the AIQ container using the aiq.datasync.getDocuments() call. Add the following function before the initialize function in libs/backbone.aiq-datasync.js file:

This function is called from the sync method and receives a correct set of AIQ callbacks as the options argument.

This function is used both to populate the collection with the data and to retrieve a single model instance. This is why we have to distinguish those two cases by checking if it received an identifier in the first argument.

Let's see how the application looks like. To do so, start the local web server by issuing the following command:

 Now open http://localhost:8000 in your browser. You should immediately see the mock data:

 

Great! The only difference from the vanilla application is that now it displays a list of tasks loaded from the mock data populated through your new collection. When using live data on your smartphone, this list would display the tasks sent by your backend.

The next operations to be implemented in your Backbone collection are create, update and delete. This will allow your app to create documents which will be synchronized through AIQ, as well as update and delete them. Add the following functions before the initialize function in libs/backbone.aiq-datasync.js file:

 

Step 4: Making models compatible with AIQ The TODO application has only one model, which you can find in the app/models folder. Let's open the todo.js file and prepare it for the integration. It needs the following changes to be applied to it:

● it has to have an _id field, so that the model can be recognized as an AIQ business document ● the _id field has to be marked as idAttribute, so that Backbone uses it as a primary identifier

Add the new attribute to app/models/todo.js as shown below:

BÖRJA HÄR I FRÅN!!!!

Step 5: Registering listeners The last development step is to react to remote changes in the business documents coming from your backend. This

functionality belongs to the collection as well. Open the libs/backbone.aiq-datasync.js file and add the following method:

Once again, in order to bind, you have to wait for the aiq-ready event. Once one of these events is triggered, the load function will be invoked.

 

The load function is used as a callback to simplify the code. In real scenarios, you will want to manually wrap incoming business documents into model classes, so that the whole store doesn't need to be reloaded, because it can cause severe performance problems once your business document collection becomes big.

Step 6: Run it on your device That's it! Your application is integrated with the AIQ API and is ready to use. Let's build the application…

…and publish it using the AIQ tool:

You have to be logged in in order to be able to publish the application. Please consult the documentation to learn how to do it. The command will publish an application in live mode, which means it is configured to consume data sent by your backend. Therefore, you won't any data at this stage unless you (or anyone else in your organization) create it. The

following screenshot has been taken after adding the three todo.model.TODO documents with the same contents as defined in step 4 of this tutorial. This is how your application looks on a device:

 

Conclusion In this tutorial you have learned how to integrate a Backbone application with the AIQ Data Sync API. If you want to learn about more advanced functions like editing documents, using camera or performing direct calls, check-out our other Tutorials.