Integrating AngularJS app with Data Sync In this tutorial, you will learn how to integrate an existing AngularJS based application with the Data Sync module of the Appear IQ platform. The Appear IQ Data Sync module provides applications with the possibility to share data across your organization, while hiding the complexity of the synchronization process behind a collection of easy to use APIs. You take care of managing data on device and the Appear IQ Data Sync takes care of distributing them to other devices or to your existing backend systems.

AngularJS is built on top of a Model-View-Controller system, where models can be translated directly into Appear IQ's business documents with the help of a custom data adapter. Let's look at an overview of the integrated ecosystem:

The tutorial consists of six steps:

1. getting the sample AngularJS app - We have a prepared a tutorial app based on AngularJS, 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 data adapter - Adapter defined in the TODO application takes 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 AngularJS framework. If you

feel that you need to go through the basics, don't hesitate to read external tutorials like this and this. AngularJS-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.

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.

In order to synchronize data to all devices in your organization, you would normally need an integration adapter. In

order to give you a good head start, we have implemented a generic integration adapter which is deployed to your

organization by default. This integration adapter receives data from all devices and distributes them back to all

devices

in your organization.

Step 1: Getting the app

The tutorial is based on well-established application idea of a simple task management application which allows users to

create new tasks, mark them as completed and remove completed taks from the list. We have prepared a Angular version

of this app in order to illustrate the integration steps with the Appear IQ Data Sync module. You need to download this app

from Github. You will see two folders there:

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

● todo+aiq - the end result of the tutorial, integrated with AIQ

The app located in todo folder does not leverage any AIQ API, but you can still use the AIQ Mobile SDK to run it inside your

browser or publish it to your device. The app will look like this:

 You can add new tasks, mark them as read and delete them. However, the data will only be stored locally and will not be

synchronized to other devices. In the following steps, you will learn how to integrate the app to AIQ, so the data gets

synchronized to other devices automatically.

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 replace listening for the document to be ready with

listening for the aiq-ready event:

Once you implement and initialize the data adapter, 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 data adapter Now you can move on to building a data adapter, which will synchronize the data with your backend system through the

AIQ Data Sync.

Conveniently enough, the vanilla TODO application already has a data adapter which proxies the CRUD operations to the

local storage module. Let's take a look at the adapter defined in js/services/adapter.js file. It contains four interesting

methods: fetch, create, update and destroy. You have to go through all these methods and reimplement them so that they

operate on the AIQ API. In each method, start by updating the fetch method. Remove the deferred.resolve() call and replace

it with the following invocation:

 

This will fetch business documents of given type from the native container and resolve the promise, passing them as an

argument.

All remaining methods will be similar, so let's update them accordingly:

 

You can also get rid of all references (in index.html, adapter.js, and app.js) to both $storage (libs/angular-uuid2.js) and

uuid2 (ibs/storageprovider.js). They are no longer necessary.

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.

Let's see how the application looks like. To do so, start the local web server by navigating to your appliaction root folder

and 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.

Step 4: Making models compatible with AIQ

All business documents in the Appear IQ platform have a well known field called _id. It is used as their identifier, making it

possible to manage them using the AIQ API.

TODO model defined in the vanilla application uses a field called id, so let's rename it to _id, so that the data adapter can

match them with their corresponding business documents. There is only one place in the application where the id field is

designated as an identifier, an that is in the $scope.getId() method defined in the js/controllers/controller.js file. After the

update, the method should look like that:

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 js/services/adapter.js file and add the following method:

 

This function takes the old handler defined in the TodoCtrl controller and calls it when remote changes arrive. Let's call this

method in chain in the controller. Open the js/controllers/controller.js file and add the call to registerListeners method before

fetch(), so that the whole chain looks like that:

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 publish it using the AIQ tool. Go to app

root folder and run the following command:

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 3 of this tutorial.

This is how your application looks on a device:

Conclusion In this tutorial you have learned how to integrate a Angular 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.