Integrating Sencha app with Data Sync

In this tutorial, you will learn how to integrate an existing Sencha Touch 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. Sencha 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 Sencha Touch sample app - We have a prepared a tutorial app based on Sencha Touch, 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. 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.

4. defining a proxy - Sencha Proxies take care of synchronizing application data with external data sources. In case

of Appear IQ, the proxy must take care of translating CRUD operations coming from a store into DataSync API

calls.

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 Sencha Touch. If you feel

that you need to go through the basics, don't hesitate to read external tutorials like this and this. Sencha Touch resources

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

you are not sure what the API being used does.

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

● AIQ Mobile HTML5 SDK tool, version at least 1.1.0 ● Sencha Cmd, (version either 4.x or 5.0.2 beta)

Note Make sure not to use Sencha Cmd 5.0.1, because it has a bug preventing the application from being correctly built. 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 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 the case of the TODO application, which loads the data in the launch method of the Main controller, you must wrap the load call into a listener. In the Main.js file in the app/controller folder, update the launch method as per the below:

 

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: Making models compatible with AIQ The TODO application has only one model, which you can find in the app/model 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 idProperty, so that Sencha uses it as a primary identifier ● the identifier generator must be set to uuid, to ensure that generated identifiers are globally unique (by default,

Sencha generates simple identifiers which are prone to conflicts) The final version of the TODO model should look like that:

There are also other fields you can integrate, like _status or _type, which are described in the documentation, but the _id is a bare minimum required for the integration to work.

Step 4: Defining a proxy Now you can move on to building a Sencha Touch proxy, which will synchronize the data with your backend system through the AIQ Data Sync. Create a file called DataSyncProxy.js in the app/proxy folder (you have to create the folder as well, it does not exist by default) and define a basic structure:

 

This is an empty skeleton of a Sencha Touch proxy. You have to go through its methods (read, create, update and destroy) and implement them so that they operate on the AIQ API. The createFailureHandler and handleSuccess methods are your custom success and failure handlers which will be used throughout the code, and create, update, destroy and read functions are the part of the Proxy protocol exposed by Sencha Touch. The proxy must be referenced by either a model or a store. Open the app/store/Store.js file, add a dependency to the proxy in the top level of the store object…

…and add the proxy element to the config object:

 

The type datasync is the alias you declared in your proxy. 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 proxy. It is called when you call the load method on a store instance (which you already do in the launch method of the controller). It will retrieve the business documents from the AIQ container using the aiq.datasync.getDocuments() call:

 

This method works with mock data, as well as live data sent by your backend system.

The code may at first look intimidating, but the general idea is really easy:

● start the operation ● do something with the data ● set exception if the data manipulation failed ● mark the operation as completed if the data manipulation succeeded ● execute the callback

The same scheme will repeat in every other operation. Let's see how the application looks like. To do so, start the local web server by issuing either

or

Now open http://localhost:1841 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 proxy. 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 Sencha Touch proxy are create, update and destroy. This will allow your app to create documents which will be synchronized through AIQ, as well as update and delete them.

This will only take effect when using live data on your device - not mock data. In other words, you will not see any change when testing the app in your browser, but your app will be ready to integrate fully with your backend.

 

 

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 store. Open the app/store/Stor.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 see 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 Sencha 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.