DSS addon framework introduction - deprecated. Talk to us before you start development

Please read the DSApps article for a general introduction to app development

The dSS addon framework is available from git

Table of Contents

The bare bones

The starting point index.html is best taken over from one of the current apps.
It should basically be a W3C standards compliant html file including
  • The stylesheets for ExtJs, framework and possibly your app
  • All required javascript files
  • A html tag with id start (with some text indicating that the page is still loading) that will be replaced by the framework once it's set up and ready.

For a basic and empty app page copy this into your app's ui/js/main.js

/**
 * @class DSS.addon.Example
 * Example class to explain the dss addon framework
 */
Ext.define('DSS.addon.Example', {
  extend: 'DSS.addon.Framework',

  config: {
    appName: "Example", // automatically translated if the string is in your dss-addon.po
    appVersion: '0.1',
    appId: 'example'
  },

  /**
   * The content generation function
   * @return {Object} The instantiated content object
   */
  getContent: function() {
    /* TODO: return instantiated content object of type Ext.Component */
    return null;

    // Usually create the main addon class here:
    // return Ext.create("DSS.addon.Example.MainPanel", Ext.apply({ id: 'example-main-panel' }, this.config));
  },

  /**
   * The help content generation function
   * @return {Object} The instantiated help content object
   */
  getHelp:function() {
    /* TODO: return instantiated help content object of type Ext.Component */
    return null;

    /* // This is mostly used to load a help file: 
     * return Ext.create('Ext.Component', {
     *     loader: {
     *         url: 'locale/' + dss.staticDataModel.activeLanguage + '/help.html',
     *         autoLoad: true,
     *         disableCaching: false
     *     }
     * });
     */
  }
});

Ext.onReady(function() {
  // initialize translation module with your dss-addon.po supplied file
  // don't pass an argument to just initlize the framework module.
  dss.buildUpLang(['locale/{languageSuffix}/dss-addon.po']);
  // Create an instance of the _DSS.adddon.Example_ class above
  // as soon as the ext framework has been loaded
  var example = Ext.create('DSS.addon.Example');
  // Call _initPage_ to kick off page rendering
  // this will initialize the page layout and call _getContent()_
  example.initPage();
});

Config options to DSS.addon.Framework

Mandatory options
appName is displayed on the page which is why it's internationalized with the gettext function
appId is used to refer to the /scripts/${appId}/ path when using relative property queries like it's possible to do in the backend (shown later on)
appVersion Your apps version

Optional
appIcon path to the icon displayed next to the app's name (e.g. images/my_icon.png, default is used if unspecified)

Property tree operations

Attention: this part of the dss-framework is currently in review and this classes might be obsolete

The property tree can be read or written to directly from the apps page. It is often a design decision to have entries written by the frontend or the backend. The digitalstrom.org apps will usually refrain from writing directly to the property tree from the frontend, especially if the logical operation requires multiple writes. This is to avoid inconsistencies, in case the client connection is interrupted while writing.

Reading must occur from within an instance of DSS.addon.Framework

var dssProperty = Ext.create('DSS.json.Property', { appId: this.appId });

// read "/scripts/$appId/foo" from the property tree and show value in an alert box
dssProperty.getString(
    'foo',
    function(value) {
        // a handler that is called asynchronously when reading a value is finished
        Ext.Msg.alert(value);
    }
);

In this example, the string property /scripts/$appId/foo is read

Writing is done with

dssProperty.setString('foo', 'bar');

A function callback can be set as third argument. It called once the call has successfully been executed.

Alternatively one can also pass explicit success and failure handlers like shown in this example

dssProperty.setBoolean('bar', true, {
  success: function() {  },
  failure: function(response, opts) {  }
});

In this example, the boolean property /scripts/$appId/bar is written the value true

The possible property functions are:
  1. getBoolean, setBoolean,
  2. getInteger, setInteger,
  3. getString, setString,
  4. getChildren,
  5. getType,
  6. query,
  7. setReadable, setWriteable, setArchived

Events

Communication with the dSS is mainly achieved through events.
Here's a List of common dSS events.

Raising events

Attention: this part of the dss-framework is currently in review and this classes might be obsolete

An event must at least have a name and may optionally have parameters.

// create the 'myapp.testevent' event
var evt = Ext.create('DSS.json.Event', { name: 'myapp.testevent' });
// raise it on the server
evt.raise();

Raises myapp.testevent without any parameters

Parameters can be passed to the raise call, which - like the property operations - also takes an optional success handler (or success/failure object) as second parameter

// create the 'myapp.testevent' event
var evt = Ext.create('DSS.json.Event', { name: 'myapp.testevent' }),
    params = {
        foo: 'MyParam',
        bar: 2,
        baz: false
    },
    handler = function() { Ext.Msg.alert("raised"); };
// raise it on the server
evt.raise(params, success);

The event object takes an optional config option baseParams of type Object which allows to set a certain set of parameters to append to every raise call

// create the 'myapp.testevent' event
var evt = Ext.create('DSS.json.Event', {
    name: 'myapp.testevent'
    baseParams: {
        userId: 'fooUser'
    }
});
// raise first 'myapp.testevent' on the server with userId 'fooUser' from baseParams and action 'add'
evt.raise({ action: 'add' });

// raise a second 'myapp.testevent' on the server with userId 'fooUser' from baseParams and action 'delete'
evt.raise({ action: 'delete' });

Subscribing to events

Attention: this part of the dss-framework is currently in review and this classes might be obsolete

// create an event listener group
var evt = Ext.create('DSS.json.EventSubscription');
// subscribe to event and start listening (register handler with get), events between subscribe and get calls will also be reported to the handler
evt.subscribe('myapp.uievent');
// register the handler for the subscribed event(s)
evt.get(function(events) {
  // handle all events from the array of object
});
// Unsubscribe the event (optionally takes a callback that's executed on success)
evt.unsubscribe('myapp.uievent');

When multiple events are subscribed from the same instance, get will report them all. If this grouping behavior is not desired, create separate EventSubscription instances for every subscription.
get takes a timeout (in ms) as second parameter after which the request is aborted if no event made it.
// unsubscribe all events from this listener group
evt.unsubscribeAll()