Hello World App

In this tutorial, I will quickly introduce you to the API which you will need to create Apps for the AdoMado Apps Platform.

A few quick points to remember, before planning your App

• An App is composed of two parts - a manifest file which defines rules about how the Apps Platform should load your App and a javascript file which contains the App's codebase.
• jQuery is always available to your app as $j
• Your App exposes a set of callbacks which are called as and when a user interacts with your App
• The App is run within the scope of a self executing function, hence you are free to define any variables in your namespace.
• Your scope contains an object - config - which you can use to access the API object instance
• There are three pre-defined points of contact available to your App, which a user can invoke. An App can initiate itself the moment its loaded into the page (init callback), the user can click on your App's icon in the Apps Panel (options callback) or the user can invoke the context options & click your App's icon (contextAction callback).

Instead of making you read the API documentation, lets start straight by creating the ubiquitous Hello World App. The objective will be to quickly introduce you to the API.

(function(config) {
  
  var HelloWorld = {  // Start

    init : function() {
      config.api.log("Hello, World!");
    },

    options : function() {
      config.api.log("Options!");
    },
    
    contextAction : function() {
      config.api.log("Context action invoked");
    }

  }; // HelloWorld End

  config.api.callbacks({
    init : HelloWorld.init,
    options : HelloWorld.options,
    contextAction : HelloWorld.contextAction
  });

})({
  api : new IJAppApi.v1({appId : "__APP_ID__"})
});

As you can see, the Apps's code is just a collection of callbacks, namely - HelloWorld.init, HelloWorld.options and HelloWorld.contextAction. These callbacks are connected to the API using the config.api.callbacks function.

The App is scoped by a self executing anonymous function, which in its entirety looks like...

(function(config) {
  // your app code goes here...
})({
  api : new IJAppApi.v1({appId : "__APP_ID__"})
});

If this looks a bit too intimidating, this is just the following implementation

(function(args) {})(args);

We define an anonymous function and immediately execute it. Any arguments be passed onto your anonymous function as willed. Read more about this technique.

The config object

When your App code starts executing, an object called config is available as a parameter to the self executing function. config.api is the API instance you can use in your App.

The API instance provides a couple of useful functions (see detailed API documentation for more)

config.api.log("This is a log message");
config.api.callbacks({});

Quick introduction to the API

• config.api.log(string) - A wrapper around console.log, which ensures that its correctly implemented on browsers were console.log is not available (IE)
• config.api.callbacks(object) - Remember, I mentioned that your App is just a set of callbacks. With the config.api.callbacks function, you connect your Apps' functions to the user's interaction points. The available callbacks are...

init - called each time your App is initiated
options - called when the user clicks on your App in the Apps Panel
contextAction - called when the user clicks on your Apps's context action

• More API methods are available in API documentation

Back to the Hello World App

• Coming back to the Hello World App, when it loads into the page, its HelloWorld.init function gets executed & logs a "Hello, World!" message on the javascript console.
• A user can also click on its icon in the AppDok - effectively creating a callback to HelloWorld.options function. This creates a "Options!" message on the javascript console.
• If the user wises, he can long press on the screen to bring up AppDok's context menu & click on your App's icon - thereby creating a callback to its HelloWorld.contextAction function.

Manifest File

Every App must be accompanied by a manifest file. The manifest defines how your will be loaded by the platform. The manifest file is self explanatory.

_adomado_prefs_apps["manifests"]["__APP_ID__"] = {
  "name" : "Hello World",
  "version" : "1.0.0.1",
  "runOnDomains" : [
                      {
                        "domain" : "*"
                      }
                    ]
};

The manifest options needs to be sandwitched between the following boilerplate code

_adomado_prefs_apps["manifests"]["__APP_ID__"] = {
  // manifest options
};