Automate Famo.us mobile apps with Cloudant on Bluemix

01 July 2014
PDF (366 KB)
 

Sign up for IBM Bluemix
This cloud platform is stocked with free services, runtimes, and infrastructure to help you quickly build and deploy your next mobile or web application.

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: Famo.us 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 Famo.us" details the construction of a typical mobile UI with thumb-scrollable lists for selecting and displaying items. Famo.us components are highly composable by design. I developed that example app's UI further into a reusable application template (a Famo.us 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 dwfamo.us sample app

Click to see larger image

  • 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

Click to see larger image

READ:Create high-performance mobile UIs with Famo.us

READ:Overview of Cloudant for Developers

READ:PouchDB, the In-Browser Database That Replicates

READ:Getting Started with IBM Bluemix and IBM DevOps Services using Node.js

What you need to get started

 

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 Famo.us 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.
  • setcors.sh — A cURL script that you use to configure Cross Origin Resource Sharing (CORS) for your Cloudant instance.
  • app — Directory that contains the Famo.us mobile app source code.
  • app/src/widgets/MobileListApp.js — Source code of the Famo.us application template (a reusable Famo.us widget).
  • app/src/main.js — Main app code.
  • app/lib/* — Libraries that are used by the Famo.us mobile app, including PouchDB.
  • app/style/* — CSS stylesheets that are used by the Famo.us 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 Famo.us 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
         });
          mainContext.add(myApp.layout);
    });
});

Step 3: Create JSON DB (Cloudant) document

 

Log in to your Cloudant account. Create a database and name it dwfamous. Select Docs > Permissions and 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.

Return to the dashboard for the dwfamous database and create a new document (New > Document). 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 JSON 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.

setcors.sh includes origins: *. In production, restrict the origins to domains that you know will access the database.

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

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:

          'https://api-key:api-password@user-name.cloudant.com/dwfamous').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

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.

applications:
- disk_quota: 1024M
  host: myuniqueappname
  name: myuniqueappname
  command: node app.js
  path: .
  domain: mybluemix.net
  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.

Known issue: Known issue: Builds for the app sometimes fail because of a potential npm race-condition bug. If that happens, you see a "Guru Meditation" error in your build log. Try the build-and-deploy cycle again by clicking the REQUEST BUILD button.

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

Access your own instance of the customized Famo.us 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.

Conclusion

 

Famo.us widgets, which are built from composable Famo.us 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 Famo.us and Cloudant, you can create data-driven, high-performance mobile apps with UIs and content that can be dynamically customized from a single JSON DB source.


RELATED TOPICS:CloudantNode.jsJavaScript

Add a comment

Note: HTML elements are not supported within comments.


1000 characters left

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing, Web development, Mobile development
ArticleID=975916
ArticleTitle=Automate Famo.us mobile apps with Cloudant on Bluemix
publish-date=07012014