DSS addon framework getting started » History » Version 9
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¶
- Download a copy of the dSS framework
- Write and test your addon
- 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.
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:
This is the main directory of your addon. It is named "myapp" with version number "0.1.0". Please use the same format.
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/
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)
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>"
This image is used to represent your addon in the app overview page in the digitalSTROM Server
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).
This directory is optional. If the addon provides scripts that will be running on the dSS they must be placed in this directory.
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
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' .)
- 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.
- 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.
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
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.localfrom the dss toolset or directly from the dSS shell
su - sv restart dss