Automate mobile apps with Cloudant on Bluemix


Web technologies — HTML5, CSS3, and JavaScript — have long promised a code-once, deploy-across-multiple-mobile platforms solution to app development. However, until recently, this promise fell short of delivery. Web-based mobile apps are associated with laggy performance, strange-looking UIs, and network-connection stalls and hangups. Scaling the server side of a web application to many access devices is also a thorny, expensive problem.

Happily, recent advances in web-based technologies that support mobile application development have changed this landscape:

  • On the UI front: is a high-performance and flexible web UI layout and animation library that you can use to create a native-code-level user experience for your mobile apps.
  • On the data-access front: The web application model of client/server data access — based on an always-available Internet connection — is unsuitable for mobile applications. A mobile device can be disconnected from network access for a sustained period. Endless retries can cause app stalls and user frustration. Cloudant, with mobile support currently through the JavaScript PouchDB library, solves this problem.

Using PouchDB, apps that run in a browser can read and write to an always-available, rapid-access, local database via familiar JSON-based CouchDB APIs. PouchDB then talks to Cloudant and keeps synchronized copies of that data across multiple servers through managed replication. Synchronization occurs only when the device is connected to the Internet and can be disrupted without interrupting the user. The scalability problem can be solved cost-effectively by adding replicated copies closer to the user during provisioning of Cloudant services.

You can modify both the content that the UI displays (on all devices), and the UI's appearance and styling details, by modifying a master JSON document on Cloudant.

The final example in my developerWorks article "Create high-performance mobile UIs with" details the construction of a typical mobile UI with thumb-scrollable lists for selecting and displaying items. components are highly composable by design. I developed that example app's UI further into a reusable application template (a widget) that can be fully customized. In this article, I'll show you how to reuse the application template in a mobile app and deploy it to IBM Bluemix™. The UI customization is data-driven via a replicated JSON document that is stored in Cloudant.

Various aspects of the UI can be customized:

Screen capture of UI for the sample app
Screen capture of UI for the sample app
  • The title.
  • The look of the UI. I make it possible to change the theme color easily. With further work, you can customize all of the CSS styling.
  • The tab button labels that describe the content.
  • The lists that are displayed for selection.

In the code, the customization is controlled by a JSON document that is stored in a Cloudant database and replicated to the mobile device via PouchDB in the browser. You can modify both the content that the UI displays (on all devices), and the UI's appearance and styling details, by modifying a master JSON document on Cloudant:

Diagram of replicating a JSON document to control the customized                     UI
Diagram of replicating a JSON document to control the customized UI

What you need to get started

Run the app in phone browserGet the code

Step 1: Explore the app

Open this article in your phone's browser and tap the Run the app in phone browser button under What you need to get started. (Safari users: To enable PouchDB to write to the local database, do not use private browsing mode.) When you start the app, be aware that it synchronizes the browser-local JSON database with Cloudant and then, in real time, builds the customized UI. Try interacting with the application:

  1. Thumb-scroll the list and select an article to view it.
  2. Tap the Video button. Select a video to view it.
  3. Try the app on multiple mobile devices if you have them.

Step 2: Fork and explore the project code

Click this article's Get the code button under What you need to get started and fork the project on IBM DevOps Services: Click the EDIT CODE button (enter your DevOps Services credentials if you're not already logged in) and click the FORK button on the menu to create a new project.

Examine the project directory structure and key files:

  • CouchDBdoc.txt — A copy of the JSON document that customizes the UI. (You'll add this file's contents later to your Cloudant database.)
  • Gruntfile.js — With files that are included in the grunt subdirectory, forms the build instructions for this project.
  • package.json —npm descriptor to install, via Node.js, the community-contributed grunt support modules that are required by your build script.
  • — A cURL script that you use to configure Cross Origin Resource Sharing (CORS) for your Cloudant instance.
  • app — Directory that contains the mobile app source code.
  • app/src/widgets/MobileListApp.js — Source code of the application template (a reusable widget).
  • app/src/main.js — Main app code.
  • app/lib/* — Libraries that are used by the mobile app, including PouchDB.
  • app/style/* — CSS stylesheets that are used by the mobile app. You can add customized UI styles here.
  • dist/* — Support for the Bluemix deployment pipeline in DevOps Services.
  • dist/public — Directory created by the build process to contain the built artifacts ready for archiving and deployment to Bluemix.
  • dist/manifest.yml — Manifest used in deploying the application to Bluemix.

How UI customization is controlled by the JSON document

Examine the CouchDBdoc.txt file to see how the app's UI is synthesized from JSON data via the application template. You can see the correspondence between the keys (articles, videos, tablabels, and color) in the JSON document and customizable options of the app/src/widgets/MobileListApp.js UI template.

The code that reads and parses the JSON document, creates the MobileListApp instance, and then customizes the widget is in app/main.js. The customization code (shown in lines 2 though 6 in this portion of main.js) is passed in as an options object into the widget during instantiation:

     pd.get('449291021476f91c50e0177ccdaa0311', function(err, res) {
          var myApp = new MobileListApp({ title: res.title,
             tablabels: res.tablabels,
             contentlists: [ res.articles,  res.videos],
             color: res.color

Step 3: Create Cloudant NoSQL DB document

Create a new app on Bluemix using SDK for Node.js. This app will host the Cloudant NoSQL DB instance. Add an instance of an Cloudant NoSQL DB service to the app. Launch the Cloudant instance, then create a database and name it dwfamous. In its Permissions page, click the Generate API key button.

Make a note of the generated key and password. (They can't be recovered if you lose them, but you can always create a new API key and delete the old one.)

In the array of permissions check boxes, select Reader for Everybody Else and both Reader and Writer for your API key. Leave the Share Database dialog as is.

Add a new document to the dwfamous database. In the document, add a comma before the closing brace (}) and paste the contents of the CouchDBdoc.txt file after the comma. Click Save and make a note of the document ID that Cloudant generates.

Step 4: Configure your Cloudant NoSQL DB instance for CORS

For your in-browser app to access the database on the Cloudant server, you must enable CORS on your Cloudant instance.

You can use the cURL script to configure CORS for your instance. (On Windows, you must install cURL.) In, replace the two sli instances with your Cloudant username. Run the script and supply your Cloudant password when prompted.

Return to the Bluemix dashboard. Click on your app to see its dashboard. Find the Cloudant NoSQL DB instance and click Show Credentials. Note your Cloudant username and password in the credentials; you will need them next.

Step 5: Update main.js with your Cloudant information

Edit the app/src/main.js file in the DevOps Services IDE to use your Cloudant API key, API password, and user name, and the document ID of your Cloudant JSON document, as indicated by the placeholders in this portion of main.js:

          '').on('complete', function(info) {

     pd.get('cloudant-document-id', function(err, res) {

Save your changes.

Step 6: Configure grunt build for DevOps Services pipeline

Click the BUILD & DEPLOY button on the upper right of the project's DevOps overview page.

Select ADVANCED from the tab bar at the top.

Select CONFIG, then click Builder. In the Configure Builder dialog box, select Grunt for the Builder field and master for the Branch field, and enter dist in the Build archive directory field:

Screen capture of the Configure Builder dialog box
Screen capture of the Configure Builder dialog box

Click Save.

Step 7: Configure a Bluemix deployer and update the deployment manifest

Click the Deployer button on the left. Deployer configuration is activated only if you already have a valid Builder that is configured in the pipeline.

Enter a unique name for the app (leaving the contents of the other fields as is) and click Save. (The app name must be unique because all Bluemix apps share the namespace.)

The deployer configuration that you completed uses the dist/manifest.yml file to deploy the app to Bluemix. Open dist/maniftest.yml in the IDE and change the host and name entries to the unique name that you entered in the deployer.

- disk_quota: 1024M
  host: myuniqueappname
  name: myuniqueappname
  command: node app.js
  path: .
  instances: 1
  memory: 128M

Be sure to save your changes.

Step 8: Commit changes and start the build-and-deploy cycle

You must commit the changes in manifest.yml and main.js to your git repository: From the IDE, go to the Git Status page of your project, stage the changes in each of the files, then commit the staged changes. Add a commit comment, click SUBMIT, and then click PUSH to trigger the build-and-deploy cycle.

Go the BUILD & DEPLOY page to see the status of the build and deploy processes.

If the build-and-deploy cycle succeeds, you can see the status of the Bluemix app and the associated build number:

Screen capture of the status information for the famousapp on Bluemix
Screen capture of the status information for the famousapp on Bluemix

Access your own instance of the customized application via its Bluemix URL.

Step 9: Modify the Cloudant document and view results

Try modifying the Cloudant document. For instance, change the color key to:

"color" : ["redcolor", "lightredcolor"]

When you access the app again, you can see that the theme color changed to red (redcolor and lightredcolor and are two CSS 3 classes in the app/styles/app.css file). You can repurpose the app for other uses altogether — for example, Italian cooking recipes — by changing the title, contentlists data, and tablabels.

If you wish, you can unbind the Cloudant instance from its hosting app and bind it to your successfully deployed app.

Conclusion widgets, which are built from composable components, can encapsulate the complex behaviors of mobile apps into reusable application templates. The replication-centric architecture of Cloudant naturally lends itself to the handling of intermittently disconnected mobile devices while it enables massive device scalability. By combining the strengths of and Cloudant, you can create data-driven, high-performance mobile apps with UIs and content that can be dynamically customized from a single Cloudant NoSQL DB source.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Cloud computing, Web development, Mobile development
ArticleTitle=Automate mobile apps with Cloudant on Bluemix