Developing an Extension Application

This article describes how to use symphony-app to generate a Symphony extension application in Node.js.

A generated Symphony extension application runs on the Sapphire framework, which is built on Express.

Note: Applications can be built using any web development technology of your choice.

App structure

Your app will need to contain:

  • CLI tool and Sapphire framework installed.
  • An HTML file for your controller, which includes the Symphony Extension API JavaScript library.
  • One or more HTML files for your views.
  • One or more JavaScript files for your own services included in your HTML files.
  • A JSON bundle file that describes your application.

Install the CLI tool

npm install -g symphony-app

Install the Sapphire framework

Create a new directory and install the Sapphire saap framework:

mkdir test
cd test

sapp install

Create a controller

The main application controller is a hidden iframe that uses the Client Extension API services to bootstrap your app, extending the Symphony user interface:

sapp controller test

Run the controller:

node server

Navigate to https://localhost:8080/test/assets/json/bundle.json and accept the insecure connection to localhost:

App bundle file

Your web application must include a file called bundle.json, which defines the properties of your application. Refer to Application Manifest Bundle File Reference for details.

Load your application

Use Developer Mode to load your application to your Symphony user interface.

Enable Developer Mode in Chrome for Local Development

If you are using Chrome and developing locally, you will first need to enable the #allow-insecure-localhost flag in Chrome. To do this, go to chrome://flags and enable the setting called "Allow invalid certificates for resources loaded from localhost."

To run your application, navigate to https://<your-pod>.symphony.com/client/index.html?bundle=https://path/to/your/bundle.json. Replace <your-pod> with the subdomain of your pod and https://path/to/your/bundle.json with the path to your bundle file.

A warning dialog will pop up, notifying you that you are about to load Symphony with one or more unauthorized applications. Check the "I have verified the app configurations" checkbox and click "Continue".

Your application is added to the list of available applications, but it does not yet run. To run it, click on the APPLICATIONS header in the left-hand navigation pane, and select Symphony Market from the loaded module. Scroll down the list of applications until you see the test application and add it. Your application now runs, but it doesn't do much yet.

Creating and Using a Service

This section describes how to create a new service that the navigation service from the web client uses to issue a callback when your item is selected. This item is added to the left-hand navigation.

  1. Go to the console and end the running server.

  2. Create the service using the sapp tool.

sapp service test left-nav "modules,applications-nav"

In this example, test is the name of the application, left-nav is the name of the new service, and the quoted list is a list of API-provided services you must import to your application.

  1. Add the service to the application.

At this point, the JavaScript service implementation has been created. To load it, add it to the controller application. In the Sapphire framework, discreet pieces of functionality are called features, and they appear in the features directory of your application. The sapp tool creates a feature called services, where it puts generated services.

Open apps/test/features/services/services.js in your editor.

The function services.addJS provides an array of all the JavaScript files that this feature needs. Add assets/js/Services/Navigation.js to this array to load the new service from the controller. Change line 8 in your code as follows:

var Q = require('q');
var Feature = require('sapphire-express').Feature;
 
module.exports = function(req, res, app)
{
    var services = new Feature(app, '/test/features/services/');
    services.addJS(['assets/js/Services/Bootstrap.js','assets/js/Services/LeftNav.js']);
    return Q(app);
}
  1. Add functionality to the new service.

Open assets/js/Services/LeftNav.js in your editor and add lines 30 and 31 to the onReady method, which is called when the application is fully loaded and registered:

Package('Test.Services', {
    Navigation : new Class({
        implements : [],
        initialize : function()
        {
            this.serviceName = 'test:navigation';
            this.importServices = 'applications-nav,modules'.split(',');
 
            SYMPHONY.services.make(this.serviceName, this, this.implements, true);
 
            SAPPHIRE.application.listen('start', this.onStart.bind(this));
            TEST.events.listen('start', this.onReady.bind(this));
        },
 
        onStart : function(done)
        {
            var bootstrap = SYMPHONY.services.subscribe('bootstrap');
 
            this.importServices.each(function(service)
            {
                bootstrap.importService(service);
            }, this);
 
            bootstrap.exportService(this.serviceName);
            done();
        },
 
        onReady : function()
        {
            this.navService = SYMPHONY.services.subscribe('applications-nav');
            this.navService.add('show-module', 'Test Module', this.serviceName);
        }
    })
});
 
new Test.Services.Navigation();
  1. Run the application again:
node server
  1. Refresh the browser. This action displays the warning dialog and loads your application as described above. Because the application is already loaded, it does not need to be added from the Symphony Market again. Under the APPLICATIONS header, you now see Test Module.

Creating a module

The steps above showed how to create a service that executes when the user clicks on the left-navigation panel item. This section shows how to use that same action to trigger your user interface to display in a module within Symphony.

Module

A module is a pinnable window that displays your conversations.

  1. Use the sapp tool to create the module:
sapp module test test-module

For this example, test is the name of the controller application, and test-module is the name of the new module application.

  1. Add the code to open the module from the left navigation:
    a. In the LeftNav.js file, change the line implements : [], to export a new method called select:
implements : ['select'],

b. In the LeftNav class, add the select method:

select : function(id)
{
    this.modulesService = SYMPHONY.services.subscribe('modules');
    this.modulesService.show('my-module', 'My Module', this.serviceName, 'https://link-to-your-app.com/', {canFloat: true});
}

In this example, My Module is the title of the module, and https://link-to-your-app.com/ is the URL of the web application you want to iframe.

Next steps

After creating the application module, you will need to create your app view which will subscribe to the Extension API services and run your business logic.
For more information regarding the Extension API services, refer to Modules Services.



Developing an Extension Application


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.