Integration einer Hilfe in DSM 4.0-5.0

Aus Synology Wiki
Wechseln zu: Navigation, Suche

Einleitung

Ich zeige euch hier am Beispiel vom DDNS updater wie man leicht seine eigene Hilfe in die DSM 4.0 - 5.0 Hilfe integriert.
Als erstes überlegen wir uns den strukturellen Aufbau unserer Hilfe, welche Baumstruktur wir benötigen und was dort hinein soll.

Voraussetzungen

  • HTML-Kenntnisse

JSON Konfiguration (helptoc.conf) erstellen

Die Datei befindet sich im Anwendungsverzeichnis und enhält die Hilfekonfiguration. Der Indexer bekommt diese automatisch durch das DSM Paketmanagement bei der Installation, Aktualisierung und Deinstallation übergeben.

{
   "app": "SYNO.SDS._ThirdParty.App.ddnsupdater",
   "title": "DDNS updater",
   "stringset": "texts",
   "helpset": "help",
   "content": "DDNSupdater/ddnsupdater_desc.html",
   "toc": [{
        "title": "helptoc:ddnsupdater_use",
        "content": "DDNSupdater/ddnsupdater_use.html",
        "nodes": [{
            "title": "helptoc:ddnsupdater_add",
            "content": "DDNSupdater/ddnsupdater_add.html"
        }, {
            "title": "helptoc:ddnsupdater_edit",
            "content": "DDNSupdater/ddnsupdater_edit.html"
        }, {
            "title": "helptoc:ddnsupdater_del",
            "content": "DDNSupdater/ddnsupdater_del.html"
        }, {
            "title": "helptoc:ddnsupdater_customprovider",
            "content": "DDNSupdater/ddnsupdater_customprovider.html"
        }]
    }, {
        "title": "helptoc:ddnsupdater_options",
        "content": "DDNSupdater/ddnsupdater_options.html",
        "nodes": [{
            "title": "helptoc:ddnsupdater_interval",
            "content": "DDNSupdater/ddnsupdater_interval.html"
        }, {
            "title": "helptoc:ddnsupdater_forceupdate",
            "content": "DDNSupdater/ddnsupdater_forceupdate.html"
        }, {
            "title": "helptoc:ddnsupdater_ssl",
            "content": "DDNSupdater/ddnsupdater_ssl.html"
        }, {
            "title": "helptoc:ddnsupdater_desktop",
            "content": "DDNSupdater/ddnsupdater_desktop.html"
        }, {
            "title": "helptoc:ddnsupdater_offlineip",
            "content": "DDNSupdater/ddnsupdater_offlineip.html"
        }, {
            "title": "helptoc:ddnsupdater_offlinescript",
            "content": "DDNSupdater/ddnsupdater_offlinescript.html"
        }]
    }, {
        "title": "helptoc:ddnsupdater_provider",
        "content": "DDNSupdater/ddnsupdater_provider.html"
    }]
}

Wir erstellen uns eine Datei "helptoc.conf" im root Verzeichnis unserer Anwendung und gestalten den Inhalt entsprechend unserer zuvor überlegten Baumstruktur. Stellt euch den Hilfebaum als eine Verzeichnisstruktur vor, die nodes wären dort die Verzeichnisse. Jeder nodes Eintrag enthält title und contents Einträge und kann weitere nodes Einträge beinhalten.
Die Texte helptoc:<name> sind Abschnitt:Variablen, die der Indexer beim Erstellen/Ändern der Indizes mit den Texten der entsprechenden Sprache ersetzt (siehe #Sprachdateien (strings) erstellen).
Achtet beim Schreiben der Datei darauf, das für jede { auch eine } existiert. Das gleiche gilt für die []. Der Indexer ist da sehr empfindlich und quittiert den Aufruf dann mit einem "Failed to load".

Erklärung der Schlüsselwörter

Parameter Beschreibnung Wert/Typ/Beispiel
app Name der Applikation, bei 3rdparty Apps immer SYNO.SDS._ThirdParty.App.<Anwendungsname> (Name wie er in der Datei INFO hinter "package=" steht oder der Verzeichnisname) alphanumerisch
title* Der Titel eines Eintrags/Zweiges alphanumerisch
stringset* Bestimmt den Ort der Sprachtextdateien mit denen die Platzhalter gefüllt werden alphanumerisch
helpset Bestimmt den Ort an dem sich die erzeugten HTML Hilfedateien befinden alphanumerisch
toc Hier beginnt der Inhalt des Hilfebaumes (Table of Contents)
content* Inhalt, Pfad zur HTML-Datei, relativ zum Verzeichnis /usr/syno/synoman/webman/help/<Sprachkürzel> alphanumerisch
nodes Beginn eines Zweiges im Hilfebaum
* notwendig

Fassen wir zusammen:

  • Datei "helptoc.conf" im Anwendungsverzeichnis erstellen
  • Inhalt entsprechend unserer zuvor überlegten Baumstruktur erzeugen

Sprachdateien (strings) erstellen

Der Aufbau einer strings-Datei sieht folgendermaßen aus:

[helptoc]
ddnsupdater_use			=	"Einträge verwalten"
ddnsupdater_add			=	"Hinzufügen"
ddnsupdater_edit		=	"Bearbeiten"
ddnsupdater_del			=	"Löschen"
ddnsupdater_customprovider	=	"Selbsterstellte Anbieter"
ddnsupdater_options		=	"Einstellungen"
ddnsupdater_interval		=	"Überprüfungsintervall"
ddnsupdater_forceupdate		=	"Erzwingen der Aktualisierung"
ddnsupdater_ssl			=	"SSL-Verbindung"
ddnsupdater_desktop		=	"Desktopsymbol"
ddnsupdater_offlineip		=	"Offline IP"
ddnsupdater_offlinescript	=	"Offline Skript"
ddnsupdater_provider		=	"Unterstützte Anbieter"

Der Text [helptoc] bezeichnet einen Abschnitt. Es können beliebig viele Abschnitte innerhalb der Datei definiert werden, die Bezeichnung [helptoc] habe ich nur als Referenz zur Synology Datei beibehalten. Es kann auch jeder andere Bezeichner benutzt werden, achtet aber darauf, dass der Bezeichner dem Teil der Variablen im Baum entspricht, der vor dem : steht.
Erstellt nun ein Verzeichnis "texts", danach in diesem Ordner für jede unterstützte Sprache ein neues Verzeichnis (siehe #Sprachkürzeltabelle), in der sich dann die Datei "strings" befindet. Beispiel: texts/ger/strings
In der Datei "strings" müssen dann zu allen Platzhalter/Variablen aus dem obigen Beispiel die passenden Texte in der gewünschten Sprache enthalten sein. Findet der Indexer beim Erzeugen/Ändern keinen passenden Text, wird "null" an diese Stelle geschrieben, was dann einem nicht vorhandenen Text entspricht.

Sprachkürzeltabelle

ger = german
enu = english US
chs = chinese simplified
cht = chinese traditional
csy = czech
jpn = japanese
krn = korean
dan = danish
fre = french
ita = italian
nld = dutch
nor = norwegian
plk = polish
rus = russian
spn = spanish
sve = swedish
hun = hungarian
trk = turkish
ptg = portuguese european
ptb = portuguese brazilian

Fassen wir zusammen:

  • Verzeichnis "texts" im Anwendungsverzeichnis erstellen
  • für jede zu unterstützende Sprache ein Verzeichnis unterhalb vom Ordner "texts" erstellen (siehe #Sprachkürzeltabelle)
  • Datei "strings" mit Texten zu allen Platzhalter/Variablen, entsprechend dem definiertem Baum, in der gewünschten Sprache erzeugen

Hilfe-Seiten erstellen

Jetzt bauen wir unsere Hilfeseiten, entweder mit einem einfachen Editor oder besser grafisch mit einem HTML-Editor. Ein HTML-Editor hat den Vorteil, das wir das spätere Erscheinungsbild schon fast 100%ig beim Erstellen beurteilen können. Einen einfachen und kostenlosen HTML-Editor wäre zum Beispiel Amaya, es kann aber auch jeder andere Editor benutzt werden. Damit die Hilfeseiten im Stil der DSM Hilfe angezeigt werden, erstellen wir einen Ordner in der Freigabe "public" und mounten dort hin das Verzeichnis /usr/syno/synoman/webman/. Nun starten wir den HTML-Editor und erstellen eine neue Seite.

<!DOCTYPE html>
<html class="img-no-display">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<link href="../../help.css" type="text/css" rel="stylesheet" />
<link href="../../scrollbar/flexcroll.css" type="text/css" rel="stylesheet" />
<script type="text/javascript" src="../../scrollbar/flexcroll.js"></script>
<script type="text/javascript" src="../../scrollbar/initFlexcroll.js"></script>

<title><Anwendungsname></title>
</head>

Quelltext Kopfteil © Synology Inc.®

Jetzt kopieren wir den oben angegebenen Quelltext des neuen Kopfteils und überschreiben damit einen evtl. vorhandenen Kopfteil. Jetzt haben wir den Style der original Hilfeseiten und können unsere eigenen Hilfeseiten darauf aufbauen. Die verschiedenen Stile wie z.B. Anmerkung Links und Überschriften stehen nun zur Verfügung. Schaut in die anderen Hilfeseiten um den gewünschten Stil zu finden. Ihr könnt natürlich auch eigene Stile oder Farben benutzen.
Zum Sichern der Hilfeseiten benötigen wir nun ein weiteren Ordner - erstellt ein Verzeichnis "help" im Anwendungsverzeichnis und für jede gewünschte Sprache einen Ordner innerhalb von "help". Komplett würde das so aussehen: help/<Sprachkürzel>. In diesen Ordner sichern wir die Hilfedateien der jeweiligen Sprache.

Falls ihr Grafiken in die Hilfe einbinden möchtet, solltet ihr diese am besten im Anwendungsverzeichnis z.B. im Ordner "images" ablegen.

Fassen wir zusammen:

  • Verzeichnis in /public erstellen
  • Verzeichnis /usr/syno/synoman/webman/ in das neue Verzeichnis mounten
  • mount --bind /usr/syno/synoman/webman/ /volume(x)/public/<neues Verzeichnis> (für (x) und <neues Verzeichnis> bitte eure Daten eintragen)
  • Verzeichnis "help" anlegen und für jede zu unterstützende Sprache ein Verzeichnis unterhalb vom Ordner "help" erstellen (siehe #Sprachkürzeltabelle)
  • HTML-Editor starten, in die Quelltextansicht wechseln und den vorhandenen Kopfteil mit dem vorbereiteten Quelltext des Kopfteils ersetzen
  • HTML-Seiten erstellen und in die angelegte Verzeichnisstruktur sichern

Index-DB erzeugen

Damit wir die erstellten Hilfeseiten auch in der DSM-Hilfe sehen, muss der Indexer die Indizes in eine Index-DB schreiben und für jede gefundene Sprache ein TOC im JSON-Format anlegen. Die TOC befinden sich anschließend im Verzeichnis ".helptoc/<Wert_des_Parameters_app_der_helptoc.conf>" des Anwendungsverzeichnisses. Ab DSM 4.0 hat sich die Art der Integration ein wenig geändert, es wird nun eine anwendungsspezifische Index-DB im Verzeichnis indexdb des Anwendungsverzeichnisses erzeugt. Das Hinzufügen/Entfernen wird nun mittels zwei neuer Befehle durchgeführt (siehe #Benutzung in Installationspaketen (SPK))

ACHTUNG Wird der Aufruf ohne die Option -n benutzt, wird die Index-DB zusätzlich in die DSM Index-DB migriert!!!
Falls nicht schon geschehen, melden wir uns per telnet oder ssh als root auf der DiskStation an. Der Aufruf vom Indexer ist der folgende:
/usr/bin/php -n -d safe_mode_exec_dir=/usr/syno/bin /usr/syno/synoman/webman/modules/Indexer/indexer.php -n -p /usr/syno/synoman/webman/3rdparty/<Anwendungsverzeichnis>

Die für uns wichtigen Kommandos sind

-n = Hilfe nicht in DSM integrieren
-p = hinzufügen/aktualisieren einer Hilfe für Anwendungen <'''Pfad-zum-Anwendungsverzeichnis'''>

Die Option "safe_mode_exec_dir" ist notwendig, da es sonst "open-base-dir" Fehlermeldungen hageln würde.

Am Beispiel für den DDNS updater müßte die Zeile folgendermaßen aussehen:
/usr/bin/php -n -d safe_mode_exec_dir=/usr/syno/bin /usr/syno/synoman/webman/modules/Indexer/indexer.php -n -p /usr/syno/synoman/webman/3rdparty/ddnsupdater
Der Indexer sollte nun laufen und die entsprechenden Indizes und TOC erzeugen. Die Fehlermeldungen "No localized strings for...", "File not found:" und "Can't open file..." könnt ihr ignorieren, solange es sich nicht um eure erstellten Sprachen handelt.

Den Indexer müsst ihr nur erneut aufrufen, wenn ihr Zweige hinzugefügt/entfernt oder die Titel/Inhalte der Zweige geändert habt. Um die Änderungen dann in die Index-DB zu übernehmen, reicht ein erneuter Aufruf. Der Indexer erkennt selbstständig das Vorhandensein von Einträgen und aktualisiert diese dann nur. Erkennen kann man dies am Text "records (added, replaced, deleted)" = (0, x, 0). (x = Anzahl)

Erzeugte Verzeichnisse indexdb und .helptoc dem Paket hinzufügen, nicht benötigte Sprachordner im Verzeichnis indexdb können bedenkenlos gelöscht werden.

Test der Hilfe-Seiten

Mit dem folgenden Befehl kann die Hilfe zum Testen migrieren werden:
/usr/syno/bin/pkgindexer_add /usr/syno/synoman/webman/3rdparty/ddnsupdater/helptoc.conf /usr/syno/synoman/webman/3rdparty/ddnsupdater/indexdb/helpindexdb
Damit wird die erzeugte anwendungsspezifische Index-DB in die DSM-eigene Index-DB migriert.

Nach Aufruf des DSM-Hilfe-Browsers und Umschaltung der Quelle im Menü "Optionen - Quelle" auf "Offline" sollte ein neuer Zweig mit eurer Hilfe zu sehen sein. Prüft alle Zweige und beseitigt eventuelle Fehler in den Hilfe-Dateien.

Der Aufruf der Hilfe kann nun ebenfalls aus der Anwendung über das ? im Titel des Fensters durchgeführt werden.

Benutzung in Installationspaketen (SPK)

Die folgenden Dateien/Verzeichnisse müssen dem Paket zusätzlich mitgegeben werden:

in package.tgz

  • /.helptoc
  • /help
  • /texts
  • helptoc.conf

Sollte ihr Grafiken verwendet haben, müssen diese natürlich ebenfalls im entsprechenden Verzeichnis mitgegeben werden.

Installation/Aktualisierung

DSMBUILD=`/bin/get_key_value /etc.defaults/VERSION buildnumber`
APPHOME="/usr/syno/synoman/webman/3rdparty/<Anwendungsname>"
if [ $DSMBUILD -ge 2198 -a $DSMBUILD -le 4627 ]; then
     /usr/syno/bin/pkgindexer_add $APPHOME/helptoc.conf $APPHOME/indexdb/helpindexdb
     /bin/sed '-e /<Anwendungsname>/d' < /usr/syno/synoman/indexdb/help.catalog > /usr/syno/synoman/indexdb/help.catalog.bak
     if [ -f "/usr/syno/synoman/indexdb/help.catalog.bak" ]; then
          /bin/mv -f /usr/syno/synoman/indexdb/help.catalog.bak /usr/syno/synoman/indexdb/help.catalog
     fi
fi

Zuerst holt sich das Script die DSM Buildnummer. Ist die Buildnummer größer/gleich 2198 (DSM 4.0) und kleiner/gleich 4627 (DSM 5.0), dann wird der Befehl "pkgindexer_add" mit den nötigen Parametern aufgerufen und die anwendungsspezifische Index-DB in die DSM-eigene Index-DB migriert.

Deinstallation

DSMBUILD=`/bin/get_key_value /etc.defaults/VERSION buildnumber`
APPHOME="/usr/syno/synoman/webman/3rdparty/<Anwendungsname>"
if [ $DSMBUILD -ge 2198 -a $DSMBUILD -le 4627 ]; then
     /usr/syno/bin/pkgindexer_del $APPHOME/helptoc.conf $APPHOME/indexdb/helpindexdb
fi

Am Anfang wird wieder die aktuelle DSM Buildnummer ermittelt. Ist der Wert größer/gleich 2198 (DSM 4.0) und kleiner/gleich 4627 (DSM 5.0), dann wird der Befehl "pkgindexer_del" mit den nötigen Parametern aufgerufen und die anwendungsspezifische Index-DB aus der DSM-eigenen Index-DB demigriert.