/ collar

2 steps to migrate your web app to native mobile app with collarjs

collarjs login mobile web


You can find the source code here: github

You can download the android app from com.collarjs.example.login.mobile.apk


In my last post (Write high quality and maintainable code with collarjs), I created a simple login web application to demonstrate how collar.js can help you write high quality code. At the end of the post, I mentioned that with collar.js it is easy to adapt your code to a different framework/library. To keep the post short, I didn't provide any example to demonstrate this feature.

In this post, we will migrate the login demo from web to native mobile app. With collarjs, this process is much easier than you think.

A brief review of the login demo

In the post Write high quality and maintainable code with collarjs, we developed a simple login web app with collar.js and jquery, which alerts 'login ok' when user signin with credential test@collarjs.com/ collarjs, and alerts 'login failed' when login with other credentials. See the following gif:

collarjs login web demo

With collar dev server and collar dev tool, you can reconstruct the login process and visualize it as following graph:

collarjs login business logic

This thought was recorded with collar.js:

var ns = collar.ns("com.collarjs.example.login"); 

var loginPipeline = ns.sensor("listen to UI event")  
  .when("user click 'signin' button")
  .do("get email and password from UI")
  .do("check email and password pair");

loginPipeline  
  .when("email and password match")
  .do("alert 'login ok'");

loginPipeline  
  .when("email and password not match")
  .do("alert 'login not ok'");

2 steps to migrate your web app from one platform/library to another

One benefit of using collar.js is that collar.js decouples your business logic from the framework you use, and this makes it easy to migrate your app from one platform/library to another.

In collar.js, only sensor and actuator interact with the environment. Take our login demo for example, sensor and actuator are the only place to interact with UI framework/library. To use a different UI framework, all we need to do is:

  1. Locate all sensors and actuators in the flow, and check if they are related to the framework/library that we need to change.
  2. reimplement them with the new framework.

Migrate to native mobile app by using collar.js + tabris.js

Tabris.js is a mobile framework that lets you develop native iOS and Android apps from a single code base written entirely in JavaScript.

Without collar.js, you probably need to take sometime to learn tabris.js, read its document, and build your login app from scratch. Event though the web app and your mobile have exactly the same business logic, the app you build will be a totally different app with totally different codebase.

In collar.js, you can keep the same business logic of the web app that we built in last post and reimplement only the UI related sensors and actuators.

Step 1. Identify the sensor and actuator that need to be modified

Let's review the login flow by calling collar.enableDevtool()

collarjs login business logic

Only 4 nodes are related to UI library:

  1. 'listen to UI event' sensor
  2. 'get email and password from UI' actuator
  3. 'alert "login ok"' actuator
  4. 'alert "login not ok"' actuator

Step 2. Reimplement them with tabris.js

Before we start implement the 4 nodes with tabris.js, we need first create the static UI. In login web app, this is simply an HTML file with <input> and <button> tags. In tabris.js, you need to build the UI page with tabris.js API. This process is straightforward, you can find the code at ui.js

The following code snippets demonstrate the implementation of the 4 nodes with both jquery and tabris.js. You can see how easy it is by comparing the two implementations. The code are almost the same.

Reimplement 'listen to UI event' sensor

// sensor impl for web with jquery
ns.sensor("listen to UI event",function(options) {
  $( "#signin-btn" ).click(() => {
    this.send({
      event : 'signin'
    });
  });
})

// code impl with tabris.js
ns.sensor("listen to UI event", function(options) {
  ui.signinButton().on('touchend', () => {
    this.send({
      event : 'signin'
    });
  })
})

Reimplement 'get email and password from UI' actuator

// 'get email and password from UI' actuator impl for web with jquery
.do("get email and password from UI", signal => {
    return {
      email : $( "#emailInput" ).val(),
      password : $( "#passwordInput" ).val()
    }
  })

// 'get email and password from UI' actuator impl with tabris.js
.do("get email and password from UI", signal => {
    return {
      email : ui.emailInput().get("text"),
      password : ui.passwordInput().get("text")
    }
  })

Reimplement 'alert' actuator

Alert dialog in tabris.js needs a cordova plugin. To make demo simple, I used a text label instead.

// 'alert' actuator with jquery
.do("alert 'login not ok'", signal => {
    alert("login failed");
  });
// 'alert' actuator with tabris.js
.do("alert 'login ok'", signal => {
    ui.messageText().set("text", "login ok!");
  });

The rest of the code are all the same as the login web app. You can find the source code at github

Now build your app with tabris.js and run it on your mobile phone :

collarjs login mobile web

Your thoughts?

collar.js is in alpha stage now (August 2016). It is currently under active development. Your ideas and suggestions are always welcome! (mail to daily.bhou@gmail.com)


collar.js : http://collarjs.com

collar.js documentation : http://www.collarjs.com/document/index.html

source code at github : https://github.com/bhou/collar.js-example-login-android