Coraline Quick Start

Running your own apps using Coraline is easy.

Since, at its core, Coraline is a webkit renderer, you can point it to any HTML page on the filesystem and it will display it:

$ coraline /path/to/index.html

Of greater interest is leveraging the power of the plugin system to boost your app’s capabilities.  Though most any web tech system or framework should work, Coraline is geared towards compatibility with Cordova and Ionic.

Absolute Simplest Example

The simplest scenario involves a single HTML page, optionally with some JS to access the plugins.  You don’t need cordova or ionic or anything to do this, as this super simple webpage (one JS function, one div):

<html>
  <head>
   <script>
    function doIt() {
      navigator.notification.confirm(
             "you sure, really sure?", 
              function(sel) {
                console.log("Selected:" + sel);
               }, 
               "Confirm It, man.", 
               ["yes", "no", "perhaps", 
                "unknowable"]);
      }
     </script>
   </head>
 <body>
   <div onclick="doIt();">Do It!</div>
 </body>
</html>

actually produces an app that lets you interact with a plugins, so with nothing but a single HTML page a javascript you could, say, connect and manage bluetooth devices.

Actual Project Example

A more realistic example is to use a framework to create the basis for a real project. If you’ve already got such a thing, built for another platform like Android or iOS, then you might start with that.

Setting up a project

Though Ionic is completely optional, in this example we’ll setup an ionic project, starting with:

$ cd /path/to/myprojects 
$ ionic start myApp tabs
... answer no to the various questions ...
$ cd myApp
$ ionic build

This will transpile a bunch of typescript to standard javascript with an index.html file, in /path/to/myprojects/myApp/www.

Now you can point Coraline to that

$ coraline /path/to/myApp/www/index.html

and what you get isn’t suuuper interesting but, still, nice to see that it basically works:

At this stage you have (up to) three jobs:

  1. Customize the app — change this from being “Coraline” to give it its own identity;
  2. Customize the code–transform this app skeleton into something useful–and tie into any required plugins; and
  3. Prepare for distribution.

Customize the Application

Coraline apps can use the cordova config.xml file to customize their identity.  If you’re building on an existing cordova project, you already have a config.xml file handy, otherwise you can create a simplified version that looks like this:

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.example.myapp" version="1.2.0" 
   xmlns="http://www.w3.org/ns/widgets" 
   xmlns:cdv="http://cordova.apache.org/ns/1.0">
 <name>My App</name>
 <description>
 My App: a sample coraline application
 </description>
 <author email="myname@example.com" href="https://psychogenic.com/">
 Pat Deegan
 </author>
 <icon src="assets/icon/myapp.png" />
 <plugin name="cordova-plugin-dialogs" />
</widget>

Save (or copy) that config.xml file in the www directory, so it sits next to index.html (i.e. in /path/to/myApp/www)

So we’ve setup an id for our app (com.example.myapp), given it a name (aptly named My App) and set an icon. We also have a plugin line, which can accept as a name either Notification or the standard cordova name, cordova-plugin-dialogs.

I spent a few hours creating a beautiful icon, which you may use if you wish, for this example.

The important things to note are that it is a 128×128 PNG file with a transparent background, and that I copied it to src/assets/icon (will get into www on next build).

Let’s try it out:

$ ionic build
$ coraline /path/to/myApp/www/index.html

Horray.  Same barebones app, but with our custom name.  And you can see the custom icon in the lower left, too.

Customize the code

Ok, now we’ll customize the code a bit, in order see a plugin in action.  The Notifications plugin comes installed with Coraline, so we’ll try that out.

First, we’ll install the typescript typings for this plugin.  Since it conforms to the same cordova API, we can use the standard ionic native stuff and do:

$ npm install --save @ionic-native/dialogs

Now, we’ll edit our home page to show a confirmation dialog.  Open up src/pages/home/home.ts and

Add an import, at the top

import { Dialogs } from '@ionic-native/dialogs';

Add a variable we’ll use for output to the class

export class HomePage {
    public confirmOutput:string = '';

Add an injected service to the constructor

constructor(public navCtrl: NavController,
 private dialogs: Dialogs) {

Add a callback for a button–here we’ll present a confirm box, and react to user input by changing our confirmOutput string.

public confirmClick() {
 // button choices
 let options = ["Yessir!", "Maybe", 
                "Nah", "No way"];
 // open native dialog
 this.dialogs.confirm("Are you absolutely certain?",
                     "Please confirm",
                      options).then(
         (selected) => {
            // handle value (0 on kill dialog)
            if (selected) {
              this.confirmOutput 
                = `You said: ${options[selected - 1]}`;
            } else {
              this.confirmOutput = 'Abort, abort!';
            }
         });
}

Now all we need is to change the display to give us access to the output and a way to trigger the callback.  Edit src/pages/home/home.html and add a button/confirmOutput placeholder:

 <p>
   Click me for good times:
  <button ion-button (click)="confirmClick()">
     Do it!</button>
  {{confirmOutput}}
 </p>

Service Injection

There’s one last thing before we can get this running with ionic.  Because we’re not actually using cordova in this example, we need to manually setup the service injection (if you have an existing project that does use other cordova platforms, this probably isn’t required).  To do this, edit and add that same import, at the top:

import { Dialogs } from '@ionic-native/dialogs';

and then add Dialogs to the list of providers, near the bottom

providers: [
 StatusBar,
 SplashScreen,
 {provide: ErrorHandler, useClass: IonicErrorHandler},
 Dialogs
]

Now we rebuild and take a look:

$ ionic build
$ coraline /path/to/myApp/www/index.html

and… success!

Using other plugins and functionality follows the same pattern:

  1. install the typescript bindings from @ionic-native
  2. use in your code
  3. add the class to the providers in app.module.ts, if required.

Once you’ve got an app working nicely, it’s time to share it with others by packing it up for deployment.