The Application object and messaging

Every application in Friend has an Application object. The Application object in a Friend application is the most important part of the application. It is generated automatically by the Friend Workspace environment when your application is first executed. 

The Application object allows your program to communicate with the Workspace object as well as the application’s sub components. Because of this, it is very important to learn about the various methods available in the object.

The most important method in the Application object is run(). This function is triggered when your application assets are finished loading and it is safe to start executing your application. It takes one argument, a message structure, which gets arguments and other variables from the Workspace itself (for example command line arguments).

Friend Workspace works by using sandboxed application containers in the form of iframes (or web workers). When you are running a Friend application, it starts by creating an initial iframe where your initial Friend Javascript is executed. Once you open up new screens and view windows, they also get iframes. Each of these view or screen iframes are initialized with standard Application objects and the Friend API. These Application objects can message each other using the postMessage Javascript function. This is how a Friend Workspace application works.

Each Friend application is decentralized into multiple Application objects. This is very powerful, and allows for applications that can work concurrently across multiple clients by transparently replacing postMessage with websockets or http calls.

Methods

The application object comes with several methods that manage your application.

Application.setSingleInstance( bool )

This method should be executed at the start of your Application.run() method. It makes your application a single instance – which means that when you try to run this application multiple times, the single instance is activated. This is useful if your application has been written in such a way that running multiple instances of it for a single device session is undesireable.

Application.setApplicationName( string name )

This method should be executed at the start of your Application.run() method. It sets the name of your application, visible in the tasklist of the Friend Workspace. This method is desirable when running a .jsx file where the task name is normally reflecting the executable filename. Otherwise, it is useful if you want to localize your application name for various languages – for example if your app is called “Manage your books” – it wouldn’t make sense in a localized environment to keep this application name in English.

Application.sendMessage( message )

The sendMessage() method allows you to pass a message to the Friend Workspace, your root Application object or a parent scope in the Application hierarchy. The message is structured in the following format:

{
    type: stringtype,
    command: stringcommand,
    ...
}

Application.openMessagePort( callback )

The openMessagePort() method opens the current application’s messaging port so that the application can receive messages from other applications. The callback returns true or false on success or failure.

Application.closeMessagePort( callback )

The closeMessagePort() method closes the current application’s messaging port so that it stops receiving messages from other applications. The callback returns true or false on success or failure.

Application.sendApplicationMessage( destination, msg, callback )

The sendApplicationMessage() method sends a message to a destination application, either represented by applicationName or applicationSourceHash which is returned from a responder in the callback, or which can be obtained by Application.getApplicationsByName().

The callback returns an array of responders in this format:

[
   {
      name: 'application1',
      hash: 232d3f9e5b0f685aad1a834c0bdfefa91be2fd6a
   },
   ...
]

Application.getApplicationsByName( filter, callback )

The getApplicationsByName() method retrieves a list of target applications who have opened their message port. The list is returned in the callback like this:

[
   {
      name: 'application1',
      hash: 232d3f9e5b0f685aad1a834c0bdfefa91be2fd6a
   },
   ...
]

Events

An Application object receives messages through the Application.receiveMessage event listener. It is up to you to declare this function, and it takes one argument; message.The message is received via postMessage(), which is an object structure.

Examples

Application.run

This example shows how the run() method opens a View window and loads a template. You can find more information on both the View and the File objects in this document.

// This is the main run function for jsx files and FriendUP js apps
Application.run = function( msg )
{
    // Make a new window with some flags
    var v = new View( {
        title: 'Welcome to FriendUP!',
        width: 640,
        height: 500
    } );
    
    // Load a file from the same dir as the jsx file is located
    var f = new File( 'Progdir:Template.html' );
    f.onLoad = function( data )
    {
        // Set it as window content
        v.setContent( data );
    }
    f.load();
    
    // On closing the window, quit.
    v.onClose = function()
    {
        Application.quit();
    }
}

The example creates a new View with the title “Welcome to FriendUP!” and sets the views dimensions to 640×500 pixels. If the user’s screen is smaller in any dimension, the view will adapt to the available space, e.g. on mobile phones.

After the view is created, a new File object is instantiated. The File object gets a template as parameter. The example refers to “Progdir:” which the Friend Workspace always maps to the directory the application is executed from.  In this example, “Template.html” is also located in the same directory or folder as my_application.js, and that is the Scripts/ directory.  See the simple Template.html file below.

Next, a handler for onLoad is registered. The handler simply puts the received data as content of the View object. After the onLoad handler is registered the load() function is called to actually load the data.

The last step is to register an onClose handler on the View that quits the application once the View is closed.

File Template.html:

<div class="ContentFull Padding ScrollArea">
    <p>Hello world!</p>
    <p><button type="button" onclick="Application.quit()">Goodbye world!</button></p>
</div>

Using Application.receiveMessage

Here is an example of the receiveMessage function that handles incoming messages:

// Set up message handlers
var MessageHandlers {
    someCommand( message ){ do stuff... },
    otherCommand( message){ do stuff... }
    ...
}
// Receive an application message
Application.receiveMessage( message )
{
    if( MessageHandlers[ message.command ] )
    {
        MessageHandlers[ message.command ]( message );
    }
    else console.log( 'This message is not handled: ', message );
}
Was this page helpful?