how to build integrated, professional enterprise-grade cross-platform mobile apps
DESCRIPTION
Build a simple enterprise mobility application with data sync using AngularJS, Backbone or Sencha Touch using our simple step by step tutorials. Our tutorials demonstrate how to develop a basic “train times” viewing application using the AppearIQ API. This includes generation of a boilerplate HTML5 hybrid cross-platform app (capable of running on either iOS or Android devices), introduction to data formats, application logic, how to synchronize data, testing in browsers and on devices. The tutorials assume that you already have basic knowledge of HTML and JavaScript. If you feel that you need to go through the basics, check out some excellent external tutorials like W3Schools HTML tutorials or W3Schools Javascript tutorials. Use of the AppearIQ cloud developer platform is free of charge. To access the tutorials click here (links to AppearIQ.com developer site)TRANSCRIPT
How to build integrated, professional enterprise-grade cross-platform mobile apps
Build a simple enterprise mobility application with data sync using AngularJS, Backbone or Sencha Touch
using our simple step by step tutorials.
Our tutorials demonstrate how to develop a basic “train times” viewing
application using the AppearIQ API. This includes generation of a boilerplate
HTML5 hybrid cross-platform app (capable of running on either iOS or
Android devices), introduction to data formats, application logic, how to
synchronize data, testing in browsers and on devices.
The tutorials assume that you already have basic knowledge of HTML and JavaScript. If you feel that you
need to go through the basics, check out some excellent external tutorials like W3Schools HTML tutorials
or W3Schools Javascript tutorials.
Use of the AppearIQ cloud developer platform is free of charge. To access the tutorials click here (links to
AppearIQ.com developer site).
The tutorial examples provided here are shared with the Slideshare audience. Readers are encouraged to visit www.appeariq.com for access to the full AppearIQ documentation and to review more up to date tutorials (including any modifications to this one) as they become available.
Develop Your First App
Introduction
In this tutorial, you will learn how to develop a basic single view AIQ application using the AIQ API. This application will
display a simple read-only list of trains using the AIQ DataSync module. Remember to consult the API documentation in
case you get lost or you are not sure what the API being used does.
This tutorial assumes that you already have basic knowledge of HTML and JavaScript. If you feel that you need to go
through the basics, don't hesitate to read external tutorials like this and this.
If you need to see the final application source code at any point, it's available on Github in the Mobile samples repository.
Just follow the Getting Started guide to deploy it to your device.
Generate Boilerplate App
Navigate to a folder in which you want to have your AIQ applications and execute the aiq generate command:
$ aiq generate -n hello-world
This will create a new folder called hello-world and will put the app content inside this folder.
Your folder structure will look like this:
Note: The API implementation stored in the aiq folder is only for testing purposes in order to use it in the local
web browser and will be replaced by the proper implementation when your application is deployed to a device.
Keeping this folder in your application structure is not obligatory, though we strongly encourage you to use it and
test your applications in browser before publishing them to device.
Note: In this tutorial we skip editing the stylesheet. If you want to know the details on how to apply css styles to the
application, go to this page.
Entry Point
Just like the regular web browser, AIQ client launches the index.html file which comes with the application. This file takes
responsibility of loading and initializing the AIQ API.
This is how your Hello World's index file should look like:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0"> <meta name="MobileOptimized" content="320"> <meta name="HandheldFriendly" content="True"> <title>Hello world</title> <script type="text/javascript" src="/aiq/aiq-api.js"></script> <script type="text/javascript" src="/js/app.js"></script> <link type="text/css" rel="stylesheet" href="/css/app.css">
</head>
<body> <h1>Hello world</h1> <div id="error"></div> <ul id="list"></ul> <script> document.addEventListener("aiq-ready", HW.aiqReady, false); </script> </body> </html>
Let's go through the most important parts of it one by one.
<meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0"> <meta name="MobileOptimized" content="320"> <meta name="HandheldFriendly" content="True"> Web pages display differently on desktop and mobile browsers. In order to make sure that your application is recognized
as mobile and display all graphical elements correctly, you should use the viewport property and set it to device width.
Unfortunately not all devices recognize this property, therefore you must use dedicated fallbacks (MobileOptimized for
Windows based devices and HandheldFriendly for other proprietary operating systems).
<script type="text/javascript" src="/aiq/aiq-api.js"></script> This declaration imports and initializes the AIQ API. The path remains the same no matter if you run the application in the
browser or in the AIQ client. After the AIQ APIs are initialized and ready to use, aiq-ready document event is generated.
<div id="error"></div> This DIV tag is a placeholder for errors which might occur while retrieving the documents, like connectivity issues or
unresponsive backend. It will be referred to by its id, which is safe in this case because it is the only element in the
application with this identifier.
<ul id="list"></ul> This UL tag is a placeholder for the list of trains. It will be referred to by its id, which is safe in this case because it is the only
element in the application with this identifier.
<script> document.addEventListener("aiq-ready", HW.aiqReady, false); </script> AIQ API initialization is not instantaneous because it takes a bit time to initialize all of its components. In order not to
perform any operation before the API is ready, your must subscribe to aiq-ready event generated when everything is in
place and safe to use. The aiqReady function is defined in HW namespace in the application logic and will be described in
the next section of this tutorial.
Note: Placing this SCRIPT tag right before the closing BODY tag will ensure that the contained code will be
executed only after the DOM tree is parsed and ready to be worked on.
At this point you have an empty view with a Hello World header on top.
Data Format
The next step is to define the data structure on which your application will base. Since this applicaiton will show a train list,
so each document will represent a single train. Let's create adatasync.json file in mock-data folder as described here
with the following contents:
{ "documents":[ { "_type": "TD.Train", "number": "9001" }, { "_type": "TD.Train", "number": "9002" }, { "_type": "TD.Train", "number": "9003" }, { "_type": "TD.Train", "number": "9004" }, { "_type": "TD.Train", "number": "9005" }, { "_type": "TD.Train", "number": "9006" }, { "_type": "TD.Train", "number": "9007" }, { "_type": "TD.Train", "number": "9008" } ] }
The _type field is used throughout the whole AIQ system and specifies the type of the document. Document types are
arbitrary but we encourage you to use prefixes implying an application to which these documents belong (the overall
namespace in this example is HW. Note however that we're using TD in the data format, which stands for Train Damage.
The reason for this is that the business data is shared between different sample applications). This reduces the possibility
of naming conflicts.
Application Logic
After the AIQ API is ready to use, you can start populating the initially empty view with some data. This is the example
app.js file which you will be using in this tutorial:
/* global AIQ:false, HW:true */ var HW = HW || {}; (function() { "use strict";
HW.aiqReady = function() { aiq.datasync.getDocuments("TD.Train", { success: function(docs) { if (docs.length === 0) { this.error({ message: "No documents to display" }); } else { var fragment = document.createDocumentFragment(); var list = document.getElementById("list"); docs.forEach(function(doc) { var entry = document.createElement("li"); entry.innerHTML = doc.number; fragment.appendChild(entry); }); list.appendChild(fragment); } }, error: function(arg) { var error = document.getElementById("error"); error.innerHTML = arg.message; } }); }; }()); Let's try to understand what's going on in this piece of code.
Retrieving Documents
In order to retrieve a list of our TD.Train documents, we use getDocuments method of theData Synchronization module.
aiq.datasync.getDocuments("TD.Train", { success: function(docs) { ... }, error: function(arg) { ... } });
Handling Empty List
To simplify things, we use the error handler to display an information when the document list is empty.
if (docs.length === 0) { this.error({ message: "No documents to display" }); } else { ... }
Note: Note that we can use "this" in this context because it will point to the object containing both "success" and
"error" methods.
Populating the List
In this line, we retrieve the list element declared in the entry point. We can do this easily thanks to the id we assigned to it.
var list = document.getElementById("list"); Then, we need to populate the list with the names of our trains. We know that all documents of TD.Train type have a field
called number, so we go through the available documents, create a new LI element for every train number and append
them to our list.
docs.forEach(function(doc) { var entry = document.createElement("li"); entry.innerHTML = doc.number; fragment.appendChild(entry); });
Error Proofing
While it is not obligatory, we advise to use code quality tools like JSHint to make sure that your very liberal by default
JavaScript code doesn't contain common and easy to overlook mistakes, like using undeclared variables. The "global"
section
declares static objects used in the file (their boolean values tell whether they can be changed from within the file). For a
comprehensive list of available options, visit this page). Note that there is no space after the opening comment.
/*global AIQ:false, HW:true */ Using strict modeis is another way of making the code more error proof. Some browsers implement the strict mode which
makes the JavaScript parser much less liberal and thus making it easy to spot mistakes. If a browser doesn't support this
mode, this declaration is treated as a regular string, not causing any problems.
"use strict";
Testing in Browser
Now your application is ready for the initial testing. The simplest is to test it in Google Chrome to start with. After having
setup your environment following those guidelines, you should see the following view:
You can see that the list has been populated with eight trains included in the test data.
Testing on Device
Testing on a device is explained here. After uploading the application, launch the mobile client and click on the new Hello
World application that appeared on the home screen. You should see the familiar view containing eight trains:
This is it. Now you have a working example on how to create a simple application and integrate it with the AIQ API.
Conclusion
In this tutorial you have learned how to design the business data, create an AIQ enabled application and test it in both local
browser and on a real device. If you want to learn about more advanced functions like editing documents, using camera or
performing direct calls, visit our Development Home.