Appear IQ - Tutorials Backbone.js

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.

Appear IQ - Tutorials Backbone.js

Recommended

More Related Content

What's hot (20)

Similar to Appear IQ - Tutorials Backbone.js (20)

More from Appear (13)

Recently uploaded (20)

Appear IQ - Tutorials Backbone.js