DSS addon framework getting started » History » Version 9

« Previous - Version 9/12 (diff) - Next » - Current version
Roman Köhler, 08/03/2015 12:39 PM


DSS addon framework - Getting started

In this document it is descripted how to use the dSS addon framework for your UI

Three steps to a working addon using the addon-framework

  1. Download a copy of the dSS framework
  2. Write and test your addon
  3. Publish it for the dS-world

Download the package

The dss addon framework contains all necessary front end files to start the development of a new addon.
The addon framework includes (and depends on) a copy of the Sencha's ExtJS framework JavaScript framework. ExtJs is located in the /framework/js/ext/ directory on the webserver's bundled dss-addon-framework.

If, for any reason, you wish to use a custom version of the dss-addon-framework and/or ExtJs, it can also be placed directly in the scripts ui/framework
folder. This necessitates following change:

// remove prepended slash ("/") from this line in framework/js/dss/dss-datamodel.js
dss.staticDataModel.baseImagePath = "framework/images/";

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 folder to store your app's images
      • (optional) framework/ The framework may be copied here to use a custom (or not release dependent) version. See changes required above.
      • (optional) js/
        The script or heart of the website lives here. Place any javascript files in this directory and load them from index.html
        • main.js
          The main JavaScript file to build our user interface.
      • locale/
        DSApps describes how translations are used. The translation files are placed in their respective subdirectories (e.g. de_DE/dss-addon.po and de_DE/help.html or the base translation file dss-addon.pot)
      • locale/(template|de_DE|en_US|etc.)/meta.po(t)
        Please provide hier additional information about the app. the configurator will use the texts inside of this file to display information about the app for it's startside and as description on the installpage
        msgid "" 
        msgstr "" 
        
        #: name
        msgid "<name of the app>" 
        msgstr "<localized name of the app>" 
        
        #: descshort
        msgid "<short description for the configurator tooltip>" 
        msgstr "<localizated short description for the configurator tooltip>" 
        
        #: description
        msgid "<longer description, shown on the install page>" 
        msgstr "<localized longer description, shown on the install page>" 
        
        #: extradesc
        msgid "<additional node, which is shown on a second line in the descriptions>" 
        msgstr "<localized additional node, which is shown on a second line in the descriptions>" 
        
        
      • default_icon.png
        This image is used to represent your addon in the app overview page in the digitalSTROM Server
      • 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 addon, or a third party addon. It must contain a valid subscription XML file which must bear 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

Writing your addon

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

User interface

Most 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. It is, however, absolutely possible to write dSS addons without making use of the addon framework.

Translation

Background
To enable translation in your digitalSTROM addon, the framework uses jsgettext a javascript variety of the renown gettext.

Application
Surround every string that you would like to translate with the underscore function _("my string"). This function will then return the translated string. For example you can replace "hello" with _("hello"). After the translation to German the function will return "hallo".

To create a dss-addon.pot base translation file you can either generate it directly from the code or manually maintain the file.
To facilitate string matching, all translated strings should be quoted in double-quotes " and any other strings use the single-quotes '. Eg. ( return _("translate me") + 'don\'t translate me' .)

The generate a dss-addon.pot file:
  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)
  2. 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

Publish it for the dS-world

Before publish your addon, make sure to remove all unnecessary files from your addon. This includes the debug version of ExtJS and the *.pot 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 or a zipfile.

Testing

For testing on your local dSS11, use the dss addon toolset (Linux only) 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. (When running a developer feed, use root user instead of dssadmin)

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

If you're using 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 if you are using the dssadmin account):

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 -> /usr/share/dss/data/subscriptions.d/

When changing 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

dss-tools.tar.gz - Toolset for Linux (7.77 KB) Roman Köhler, 04/08/2013 05:34 PM