dSS Addons¶

• dSS Addons
  • Three steps to a working addon
    • Download the getting started package
    • Coding your addon
      • User interface
      • Translation
    • Upload it to the digitalSTROM Addon Center
  • Testing
  • Conventions
  • Futher reading and documentation

The purpose of dSS addons is to extend the functionality of the digitalSTROM Server. Developers can upload their addons to the digitalSTROM app repository. Before end users can download them to their digitalSTROM Server, a thorough sanity check will be performed before the packaged addon is released.

Three steps to a working addon¶

1. Download a copy of the dSS framework
2. Write and test your addon
3. Upload it to the digitalSTROM addon center

Download the getting started package¶

The dss addon framework contains all necessary front end files to start the development of a new addon. Besides the ui folder, which is the only folder in the framework since it only covers the web front end, there will usually be the scripts and config directories. The addon framework also includes a copy of the Ext JS JavaScript framework. ExtJs is found in the ui/js/ext/ subfolder

The Structure of a dSS addon:

• myapp-0.1.0/
  This is the main directory of your addon. It is named "myapp" with version number "0.1.0". Please use the same format.
  • ui/
    This directory is required and must contain a valid index.html file. Even if the addon does not offer a web interface for its configuration, it must at least provide a simple description in its web page. Furthermore, if the addon offers a full featured web UI, this directory will hold all associated data, like images, JavaScript files, HTML pages, CSS, etc.
    • images/
      Use this for your images
      • dss/ The framework comes with a set of images which may of course be used. These are placed here.
    • js/
      • dss/
        The dss addon framework lives in this directory. It's wise not to change anything here (do it by inheritance if you absolutely need to) as it will make updating easier as the framework evolves.
      • ext/
        The copy of ExtJS with a custom themed dSS style.
      • main.js
        The main JavaScript file to build our user interface.
      • jsgettext/
        A JavaScript implementation of GNU gettext
    • locale/
      In the future we would like to offer internationalized addons. To simplify this all messages are initially written in english. By using a JavaScript version of GNU gettext the translation step is very simple. DSApps describes how. The translation files are placed here or given subdirectory.
    • default_icon.png
      This image is used to represent your addon in the app overview page in the digitalSTROM Server
    • ds_gui.css
      Default css file for the dss addon framework. Use this to make your addon look like the dSS Webinterface. Using the same color scheme and design makes it easier and more intuitive for users.
    • index.html
      The necessary HTML file. You may of course use the file provided by the framework which usually requires no changes (unless you add more js files to your addon than main.js).
  • scripts/
    This directory is optional, if the addon provides scripts that will be running on the dSS they must be placed in this directory.
  • config/
    This directory is only required if the add-on has to hook into events provided by the dSS, your or a third party addon. It must contain a valid subscription XML file which must have the same name as the addon: i.e. myapp.xml.

If you create an open embedded package (.ipk) you can install it to your dSS11 using the following command:

addon install myapp_0.1.0-r0.5_all.ipk

Coding your addon¶

Naturally this guide can't cover the whole process of writing and designing your digitalSTROM addon. But we'll show some useful tips and tricks detailing some extracts of the code.
Read an introduction to the framework on DSS_addon_framework_introduction

User interface¶

All existing digitalSTROM addons are written in JavaScript using the ExtJS framework. If you decide to use this framework, you should have a look at examples page and at the documentation. Note that the dss addon framework strictly depends on ExtJS but it is possible to write dSS addons without making use of the addon framework.

Translation¶

To enable translation in your digitalSTROM addon using jsgettext (a javascript variety of the renown gettext) you'll need to create a new instance of the Gettext class (skip if you're using the addon framework).
Surround every string that you would like to translate with . The function (msgid) will actually return the translated string. For example you can replace "hello" to _("hello"). After the translation to German the function will return "hallo".

1. Go to the myapp-0.1.0/ui/locale directory and execute
   

   xgettext -Lperl -d dss-addon -k_ --omit-header -o dss-addon.pot ../js/*.js
   

   
   This will create a dss-addon.pot file. This file contains the reference of all translatable strings and is not meant to be translated. This file is then copied to the specific locale folder and gets the new dss-addon.po name (notice the extension change from pot to po). This is the file that will contain the actual translations.
   (NOTE: that in some cases, not all strings will be included due to language differences and xgettext not supporting javascript)

1. The easiest way to translate this po file is to open it with a special program like poedit and create a new translation catalog. Save this catalog to myapp-0.1.0/ui/locale/de_DE/ for german. Adapt path for your language. Poedit also lets you do all the translation work. You may also use any plain text editor
2. The last step is to convert the myapp.po file to a json file. For this task the po2json program in the tools directory is used. Run from the locale directory with:
   

   echo -n 'var locale_data=' > de_DE/LC_MESSAGES/dss-addon.js; po2json -p de_DE/dss-addon.po >> de_DE/LC_MESSAGES/dss-addon.js; echo -n ';' >> de_DE/LC_MESSAGES/dss-addon.js;
   

Upload it to the digitalSTROM Addon Center¶

Before uploading your addon, make sure to remove all unnecessary files from your addon. This includes the debug version of ExtJS and the *.pot, *.po and *.mo translation files. Removing these files helps to save space on the dSS and reduces the loading times of your addon.

Currently addons can only be published by sending us a tarball.

Testing¶

For testing on your local dSS11, use the dss addon toolset and copy the files into your path (e.g. _/bin)
Since the default user does not have write permissions, prepare your dSS for upload as dssadmin user with

dss-setup dss11.local

NOTE: You can install your public key on the dSS by passing the keyfile (usually /.ssh/id_rsa.pub) as second argument

You can now install a package with

dss-reinstall-addon myapp-0.1.0 dss11.local

It's important to use dss-reinstall-addon not dss-install-addon if the directories already exist on the server. If in doubt always use dss-reinstall-addon
If required, an additional parameter specifying the ssh username can be appended. (Developer feeds use root user)

The default credentials are both user/pw dssadmin or on the developer feed root without password

If you're stuck with windows, use this mapping to place the 3 root directories of your addon into the right dSS folder (use WinSCP, after fixing the permissions of these directories with PuTTY):

myapp-0.1.0/ui/* -> /www/pages/add-ons/myapp/ (this means all files in the ui directory have to be placed in /www/pages/add-ons/myapp/
myapp-0.1.0/scripts/* -> /usr/share/dss/add-ons/myapp/
myapp-0.1.0/config/myapp.xml -> /ush/share/dss/data/subscriptions.d/

When chaning subscriptions (or after the initial copy) restart the dSS daemon. The install script does that already
It can be performed manually with

dss-restart dss11.local

from the dss toolset or directly from the dSS shell

su -
sv restart dss

Conventions¶

• Follow the guidelines in Javascript Coding Conventions to write your javascript code.
• When defining own events, prepend the event name with the name of the script, i.e. myapp.myeventname to avoid collisions with other addons
• Mailbox configuration for scripts that wish to send e-mails should be placed and read from the following place in the property tree:
  

  /config/credentials/mail/mailserver
  /config/credentials/mail/login
  /config/credentials/mail/password
  /config/credentials/mail/sender
  /config/credentials/mail/receiver
  

Futher reading and documentation¶

1. The JSON API documentation is the crucial part to an addon. You can find the latest version in this article.
2. The Scripting inside the dSS wiki page provides useful documentation to the internal JavaScript API.
3. Standard events gives you an overview of available events. Especially the running and the callScene event are very useful to load stored data from the property tree or respond to scene actions.
4. An outdated technical documentation about the design process of some existing dSS addons can be found in the attached document

Note that the design document is outdated when using the dss addon framework.