History

DSS addon framework introduction

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

The dSS addon framework is available from gitorious

Table of Contents

The bare bones

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

 1 /**
 2  * @class DSS.addon.Example
 3  * Example class to explain the dss addon framework
 4  */
 5 Ext.define('DSS.addon.Example', {
 6   extend: 'DSS.addon.Framework',
 7 
 8   config: {
 9     appName: _("Example"),
10     appVersion: '0.1',
11     appId: 'example'
12   },
13 
14   /**
15    * The content generation function
16    * @return {Object} The instantiated content object
17    */
18   getContent: function() {
19     /* TODO: return instantiated content object of type Ext.Component */
20     return null;
21   },
22 
23   /**
24    * The help content generation function
25    * @return {Object} The instantiated help content object
26    */
27   getHelp:function() {
28     /* TODO: return instantiated help content object of type Ext.Component */
29     return null;
30   }
31 });
32 
33 Ext.onReady(function() {
34   // Create an instance of the _DSS.adddon.Example_ class above
35   // as soon as the ext framework has been loaded
36   var example = Ext.create('DSS.addon.Example');
37   // Call _initPage_ to kick off page rendering
38   // this will initialize the page layout and call _getContent()_
39   example.initPage();
40 });

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)

Property tree operations

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

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

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

Writing is done with

1 this.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

1 this.dssProperty.setBoolean('bar', true, {
2   success: function() { … },
3   failure: function(response, opts) { … }
4 });

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

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

1 // create the 'myapp.testevent' event
2 var evt = Ext.create('DSS.json.Event', { name: 'myapp.testevent' });
3 // raise it on the server
4 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

 1 // create the 'myapp.testevent' event
 2 var evt = Ext.create('DSS.json.Event', { name: 'myapp.testevent' }),
 3     params = {
 4         foo: 'MyParam',
 5         bar: 2,
 6         baz: false
 7     },
 8     handler = function() { Ext.Msg.alert("raised"); };
 9 // raise it on the server
10 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

 1 // create the 'myapp.testevent' event
 2 var evt = Ext.create('DSS.json.Event', {
 3     name: 'myapp.testevent'
 4     baseParams: {
 5         userId: 'fooUser'
 6     }
 7 });
 8 // raise first 'myapp.testevent' on the server with userId 'fooUser' from baseParams and action 'add'
 9 evt.raise({ action: 'add' });
10 
11 // raise a second 'myapp.testevent' on the server with userId 'fooUser' from baseParams and action 'delete'
12 evt.raise({ action: 'delete' });

Subscribing to events

 1 // create an event listener group
 2 var evt = Ext.create('DSS.json.EventSubscription');
 3 // subscribe to event and start listening (register handler with get), events between subscribe and get calls will also be reported to the handler
 4 evt.subscribe('myapp.uievent');
 5 // register the handler for the subscribed event(s)
 6 evt.get(function(events) {
 7   // handle all events from the array of object
 8 });
 9 // Unsubscribe the event (optionally takes a callback that's executed on success)
10 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. 
1 // unsubscribe all events from this listener group
2 evt.unsubscribeAll()