innovaphone.lib1

Includes

The library has no dependencies on other Javascript files.

Static helper functions

Functionality that is often needed in apps.

innovaphone.lib1.openLink(url): Used for opening mailto-Links.

Events

innovaphone.lib1.Event defines an interface for events. Listeners can attach an detach to an event. Attached listeners are called when the event fires.

innovaphone.lib1.Event(sender)

Constructor for the event. The specified sender object will be passed to the attached listener functions.

attach(listener)

Attaches a listener function with the following parameters.

sender: The sender object specified by the constructor of the event.
value (optional): Additional information about the event, typically an object.

detach(listener)

Detaches a listener function.

notify(value)

Fires the event and notifies the attached listeners

Example

    // define event
    var oncall = new Event(this);
    
    // attach a listener
    oncall.attach(function(sender, value) {
        console.log(value.name + " calling");
    });

    // notify listeners
    oncall.notify({ name: "John Doe" });

The start object

The start object is passed to an app. It provides access to the parameters of the app itself and encapsulates the communication with the client.

Properties

url: The websocket base URL to be used by the app.
name: The name of the app.
title: The display name of the app.
args: An object containing the URI parameters that have been passed to the app.
margs: An object containing the URI parameters that have been passed to the app as arrays so that no argument is lost, if the same argument is passed multiple times.
lang: The two-letter code of the current language (e.g. "en").
scheme: The current color scheme ("light" or "dark").

Events

onargschanged: Fires when the content of the "args" property has changed.
onlangchanged: Fires when the content of the "lang" property has changed.
onschemechanged: Fires when the content of the "scheme" property has changed.
onmenustatechanged: Fires if the optional hamburger menu of the app (initialized using start.setMenuState) has been opened or closed by the user. Possible values are "open" or "closed".

Callback functions

onopenchannel(channel, opener, args): Apps can set this callback function in order to accept incoming communication channels from other apps.

Methods

show(): Tells the client to bring the app to the front.
show(applink): Opens the specified app link that might be the same app or a different app.
bringToFront(): Tells the client that the window of the app (detached app window or main window of the client) should be brought to the front and get the focus. Depending on the operating system this function might not have an effect.
close(): Tells the client to close the app.
home(): Tells the client to show the home screen without closing the app.
setArgs(args, title): Sets the app arguments that are needed to re-open the current page. Will be used by the client to create booksmarks and for the browser history. Additionally an optional title for the current page can be given.
startActivity(): Brings the app to the front for displaying an activity, like an incoming call. After the activity is finished, the app must call finishActivity().
finishActivity(): Tells the client that the app has finished the activity that was started using startActivity(). The client will go back to the last app that was displayed before the activity.
provideApi(api): Tells the client that the app is providing a specific API (e.g. "com.innovaphone.phone"). The function should be called only after the app is connected and ready to receive API messages. Returns an object that encapsulates the handling of that API.
consumeApi(api): Subscribes for a specific API (e.g. "com.innovaphone.phone"). Returns an object that encapsulates the handling of that API.
openChannel(dst, args): Opens a communication channel to another app (dst) and returns an object that encapsulates the handling of that channel.
acceptChannel(channel): Can be used inside the onopenchannel callback to accept an incoming channel. Returns an object that encapsulates the handling of that channel.
rejectChannel(channel): Can be used inside the onopenchannel callback to reject an incoming channel.
requestPrepareReload(callback): Registers a callback that is called before the app is closed and reloaded in a new iframe by the client. For example this happens when the app is attached or detached from the main window of myApps for windows. When the app has finished its preparations for reloading it should call start.prepareReloadComplete().
prepareReloadComplete(): Tells the client that the app has finished its preparations for reloading the app in a new iframe and that the current iframe can be closed now.
setMenuState(state): Tells the client if the optional hamburger menu of the app is open or closed. Possible states are "open" and "closed". The function needs to be called once to tell the client that the app provides a menu.
setBadge(value): Sets a badge at the app icon in the start bar and on home. Usually value is a number, but you can use any UTF8-Character to indicate states of the running app. Note that this function is only useful to indicate states while the app is running. If badge counts should appear also while it's not running the badge count should be set from the backend.

Example

The following example demonstrates how apps can use the initial parameters in the start object and handle parameter changes during runtime.

var innovaphone = innovaphone || {};
innovaphone.Example = innovaphone.Example || function (start) {
    var colors = {
        dark: {
            "--background": "black",
            "--foreground": "white"
        },
        light: {
            "--background": "white",
            "--foreground": "black"
        }
    };

    var translations = {
        en: {
            hello: "Hello!"
        },
        de: {
            hello: "Hallo!"
        }
    };

    var schemes = new innovaphone.ui1.CssVariables(colors, start.scheme),
        langs = new innovaphone.lib1.Languages(translations, start.lang),
        app = new innovaphone.appwebsocket.Connection(start.url, start.name);

    start.setMenuState("closed");
    showPage(start.args.page);

    start.onschemechanged.attach(function () {
        schemes.activate(start.scheme);
    });

    start.onlangchanged.attach(function () {
        langs.activate(start.lang);
    });

    start.onargschanged.attach(function () {
        showPage(start.args.page);
    });

    start.onmenustatechanged.attach(function(sender, value) {
        if (value == "open") {
            // show menu
        }
        else {
            // hide menu
        }
    });

    function showPage(id) {
        // ...
    }
};

Client APIs

Apps can communicate with other apps using APIs. Each API is identified using a string constant (e.g. "com.innovaphone.phone"). Apps can both provide APIs and consume APIs that are provided by another app.

API messages

A consumer can send requests to a provider. The provider can send back responses to the originating consumer. The framework treats the messages as opaque data and does not interpret them. The actual format is specified by the API.

API model

An API provider can publish a model object containing its current state. The model can be observed by the consumers of the API. For example a phone API provider could publish the registration state and the active calls. Phone API consumers.

Providing an API

Apps that want to provide an API, must register at the client using the start.provideApi method. The method returns an object that encapulates the interface to be used by the API provider.

The API provider interface

onmessage

Event that fires on incoming requests. The value of the event is an object with the following properties:

msg: The actual message, typically an object.
consumer: The name of the consumer that sent the request.
src: A value that should be echoed back to the consumer in every response to that request.

onconsumerclosed

Event that fires if an API consumer for the API is closed. The provider can abort pending API requests from that consumer.

consumer: The name of the consumer that sent the request.

send(msg, consumer, src)

Sends a response to a request that was received using the onmessage event.

msg: The response message, typically an object.
consumer: The name of the consumer that sent the request.
src: The src value from the corresponding request.

update(model)

Publishes an arbitrary model object, that can be observed by the consumers of the API.

isDefaultApiProvider()

Returns true, if the app is the default provider of the API.

Example

// register API
var phoneApi = start.provideApi("com.innovaphone.phone");

// process incoming messages
phoneApi.onmessage.attach(function(sender, obj) {
    if (obj.msg.mt == "StartCall") {
        startCall(obj.msg.num);
        phoneApi.send({ mt: "StartCallResult" }, obj.consumer, obj.src);
    }
});

// publish model
phoneApi.update({ calls: [] });

Consuming an API

Apps can consume an API by calling the start.consumeApi method. The method returns an object that encapsulates the interface to be used by the API consumer.

The API consumer interface

providers

An array that contains the names of all providers of the API.

model

An object, that contains all providers of the API with some additional information and their published model.

title: The displayname of API provider.
url: The URL of the API provider.
info: An object that contains static info provided by the app service of the provider. The format is defined by the API.
model: An object that contains dynamic info published by the app provider. The format is defined by the API.
defaultApiProvider: The name of the current defaultApiProvider (can be null).
restart: A counter that reflects how many times the API provider was restarted. This information can be used to detect restarts in order to renew subscriptions to that provider. Note that the initial value is undefined and changes to 0 when the provider was started the first time. So a change to 0 does not indicate a restart.

send(msg, provider, src, title)

Sends a request to an API provider.

msg: The request message, typically an object.
provider (optional): The name of the provider that should receive the request. If no provider is specified, the client lets the user select the provider. If "*" is specified, the request is broadcasted to all available providers of the API.
src (optional): An optional value that will be echoed in the responses.
title (optional): An optional title that is displayed by the client, if the user is asked which app should be used.

onmessage

Event that fires on incoming responses. The value of the event is an object with the following properties:

msg: The actual message, typically an object.
provider: The name of the provider that sent the request.
src: The value from the corresponding request.

onupdate

An event that fires on API model changes. The consumer is supposed to re-evaluate the model, if needed.

Example

    var phoneApi = start.consumeApi("com.innovaphone.phone");
    phoneApi.send({ mt: "StartCall", num: "200" });

List of app APIs

The API messages and models are transparent to the client, so every app developer can define new APIs. As of now innovaphone defined the following APIs to communicate with their apps.

Communication channels between apps

Apps or other iframes like status info displays can open a direct communication channel to another app. The programming interface of a channel is similar to a websocket connection. The channel implementation uses window messages.

Opening a channel

The start.openChannel method can be used to open a channel to another app. Additionally arguments with additional information for the app can be passed. The method returns a channel object.

Example

    var ch = start.openChannel("someapp", {arg1: 3});

Accepting channels

If an app wants to accept incoming channels, it needs to set the start.onopenchannel callback. Inside the callback the incoming channel can be accepted using start.acceptChannel or rejected using start.rejectChannel.

Example

    start.onopenchannel = function(channel, opener, args) {
        if (opener == expectedOpener) {
            var ch = start.acceptChannel(channel);
        }
        else {
            start.rejectChannel(channel);
        }
    };

The channel object

The channel object provides an interface to handle the lifetime of the communication channel and for sending and receiving messages.

Callbacks

onconnected(): Called if the connection was established.
onclosed(): Called if the connection failed or has been closed by the remote endpoint.
onmessage(msg): Called on an incoming message. The message is a javascript object.

Methods

send(msg): Sends the msg object. The remote endpoint will get it using the onmessage callback.
close(): Closes the channel. The remote endpoint will get the onclosed callback.

Example

    // source endpoint
    var ch = start.openChannel("someapp", {arg1: 4});
    ch.onconnected = function() {
        ch.send({mt: "Echo"});
    };
    ch.onclosed = function() {};
    ch.onmessage = function(msg) {
        if (msg.mt == "EchoResult") ch.close();
    };

    // destination endpoint
    start.onopenchannel = function(channel, opener, args) {
        var ch = start.acceptChannel(channel);
        ch.onconnected = function() {};
        ch.onclosed = function() {};
        ch.onmessage = function(msg) {
            if (msg.mt == "Echo") {
                ch.send({mt: "EchoResult"});
            }
        };
    };

Multi-language support

innovaphone.lib1.Languages defines a library for translating texts. Standalone it can be used to create static texts.

In conjunction with innovaphone.ui1.lib (see innovaphone.ui1.nodePrototype.addTranslation) dynamic texts can be put into UI nodes that are updated automatically, when the language changes.

innovaphone.lib1.Languages(texts, lang)

Constructor for the event. The specified sender object will be passed to the attached listener functions.

texts: An object containing the translations for all supported languages.; The texts can contain numbered placeholders ($0, $1, $2, ...) that can be substituted during translation.
lang: The two-letter code of the current language (e.g. "en").

Example:

var texts = {
    en: {
        conn: "Connected as $0",
        hello: "Hello!"
    },
    de: {
        conn: "Verbunden als $0",
        hello: "Hallo!"
    }
};

var langs = innovaphone.lib1.Languages(texts, "en");

current

Property containing the two-letter code of the current language.

activate(lang)

Switches the current language.

lang: The two-letter code of the language (e.g. "en").

Example:

langs.activate("de");

text(id, args)

Returns the translation of a text and substitues placeholders.

id: The ID of the text.
args (optional): An array containing the values for substituting the placeholders in the tranlated text.

Example:

var text1 = langs.text("hello");
var text2 = langs.text("conn", ["John Doe"]);

clear(node)

Detaches UI nodes, so that they won't receive further updates when the language is changing.

This method is needed only when the library is used by innovaphone.ui1.lib.

node (optional): If specified, the library only detaches the UI nodes that are in the subtree of the given node. Otherwise all UI nodes are detached.