Quelltext der Seite Archiv:Integration einer Hilfe in DSM 5.1-

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

==Voraussetzungen==
* HTML-Kenntnisse
* 64-Bit Entwicklungsumgebung (DiskStation/virtual)
* git Client (z.B. per iPKG/oPKG)
* Synlogy GPL Toolkit

==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.
<pre>
{
   "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"
    }]
}
</pre>
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.<br>
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]]).<br>
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===
{| border="1" cellpadding="6" cellspacing="0" style="text-align:left"
|-
|'''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

==Ressource Spezifikation (resource) erstellen (nur DSM >= 6.0)==
Die Datei befindet sich im Verzeichnis /var/packages/<Anwendungsname>/conf und enhält die Hilfe-Konfiguration für das Paket-Zentrum. Anders als in den vorherigen Versionen, wird die Migration/Demigration der Hilfe eines Anwendungspaketes über den Start bzw. Stopp der Anwendung im Paket-Zentrum durchgeführt und nicht bei der Installation/Aktualisierung/Deinstallation.
In den meisten Fällen kann die Konfiguration direkt von hier übernommen werden; Aussnahmen sind Anwendungen bei denen die GUI in einem separaten Verzeichnis untergebracht ist (Beispiel: app oder ui). In diesem Fall müssen die Pfade den Gegebenheiten angepasst werden.
<pre>
{"indexdb":"help-index":{"conf-relpath":"helptoc.conf","db-relpath":"indexdb/helpindexdb"}}
</pre>
Quelltext Ressource Spezifikation ©2016 Synology Inc.® (Quelle: DSM Developer Guide 6.0, Seite 84 #Integrate Help Document into DSM Help)

==Sprachdateien (strings) erstellen==

Der Aufbau einer strings-Datei sieht folgendermaßen aus:
<pre>
[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"
</pre>

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.<br>
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<br>
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===
<pre>
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
</pre>

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 [http://www.wssexpert.de/amaya/ 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.

<pre>
<!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/help.css" type="text/css" rel="stylesheet" />
<link href="../../../../help/scrollbar/flexcroll.css" type="text/css" rel="stylesheet" />
<script type="text/javascript" src="../../../../help/scrollbar/flexcroll.js"></script>
<script type="text/javascript" src="../../../../help/scrollbar/initFlexcroll.js"></script>

<title><Anwendungsname></title>
</head>
</pre>
Quelltext Kopfteil ©2016 Synology Inc.® (Quelle: DSM Developer Guide 6.0, Seite 83 #Integrate Help Document into DSM Help)

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.<br>
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
* <code>mount --bind /usr/syno/synoman/webman/ /volume(x)/public/<neues Verzeichnis>  (für (x) und <neues Verzeichnis> bitte eure Daten eintragen)</code>
* 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

==Toolkit einrichten==
Ab DSM 5.1 hat Synology den Indexer erweitert und ein Tool namens [https://linux.die.net/man/1/xapian-compact xapian-compact] eingebunden. Da xapian-compact nicht im nativen DSM enthalten ist, benötigt man nun das Synology Toolkit. Ihr könnt das Toolkit auf eurer DiskStation oder in einer virtuellen Linux-Machine in einer 64-Bit Umgebung benutzen.

'''Wichtig: Das Toolkit kann nur in einer 64-Bit Umgebung benutzt werden!!!
'''

In diesem Beispiel wird /volume1/source als Ausgangsverzeichnis verwendet

Verzeichnis anlegen
<pre>>mkdir toolkit</pre>

Package Toolkit Framework herunterladen
<pre>>cd toolkit
>git clone https://github.com/SynologyOpenSource/pkgscripts-ng.git</pre>

Entwicklungsumgebung herunterladen...kann eine Weile dauern<br>
vorhandene Architekturen <arch> können mit ./EnvDeploy -v6.1 -l anzeigt werden
<pre>>cd pkgscripts-ng
>./EnvDeploy -v 6.1 -p <arch></pre>

Anzeige nach Download und Installation bereinigen
<pre>>clear</pre>

Problem mit fehlendem SymLink zu ash korrigieren
<pre>>cd ../build_env/ds.<arch>-6.1/bin
>cp -s sh ash</pre>

==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 auch [[#Benutzung in Installationspaketen (SPK)]])

Falls nicht schon geschehen, melden wir uns per telnet oder ssh als root auf der DiskStation an.

In diesem Beispiel wird wieder /volume1/source als Ausgangsverzeichnis verwendet

Konfigurationsdateien der Hilfe kopieren
... Verzeichnis help, texts und Datei helptoc.conf des Paketes nach /volume1/source/toolkit/build_env/ds.<arch>-6.1/usr/syno/bin/modules/<packagename> kopieren.

Wechsel in die Entwicklungsumgebung aus [[#Toolkit einrichten]]
<pre>>cd /volume1/source/toolkit</pre>

Verzeichnis für die Konfigurationsdateien der Anwendung erstellen
<pre>>mkdir -p usr/syno/bin/modules/<packagename></pre>

Index-DB für die Hilfe erstellen

'''ACHTUNG Wird der Aufruf ohne die Option -n benutzt, wird die Index-DB zusätzlich in die DSM Index-DB migriert!!!'''<br>
<pre>>cd build_env/ds.<arch>-6.1
>chroot .
>/usr/bin/php -n -d safe_mode_exec_dir=/usr/syno/bin /usr/syno/bin/indexer.php -n -p /usr/syno/bin/modules/<packagename>
>exit</pre>
Die für uns wichtigen Kommandos sind
<pre>
-n = Hilfe nicht in DSM integrieren
-p = hinzufügen/aktualisieren einer Hilfe für Anwendungen <Pfad_zu_Konfigurationsdateien_der_Hilfe>
</pre>
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:<br>
<code>/usr/bin/php -n -d safe_mode_exec_dir=/usr/syno/bin /usr/syno/bin/indexer.php -n -p /usr/syno/bin/modules/ddnsupdater</code><br>
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.<br>

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==
Ab DSM >= 6.0 existieren 2 Wege, um die Hilfedateien in die DSM-Hilfe zu migrieren/zu testen.

1. Mittels dem folgenden Befehl<br>
<code>/usr/syno/bin/pkgindexer_add /usr/syno/synoman/webman/3rdparty/ddnsupdater/helptoc.conf /usr/syno/synoman/webman/3rdparty/ddnsupdater/indexdb/helpindexdb</code><br>

2. Automatisch per Paket-Zentrum und vorhandener [[#Ressource Spezifikation (resource) erstellen (nur DSM >= 6.0)|Ressource Spezifikation]] (nur DSM >= 6.0)<br>
'''Hinweis:''' Für diese Methode muss die erzeugte Ressource Spezifikation (resource) zusätzlich noch als resource.own in das gleiche Verzeichnis kopiert werden. Diese Aufgabe wird bei der Installation/Aktualisierung normalerweise automatisch durch das Paket-Zentrum durchgeführt, für unseren Test mit dem bestehenden Paket muss diese Aufgabe manuell erledigt werden.<br>
Anschließend kann das Paket gestartet werden; die Hilfe wird beim Start migriert und bei einem Stopp demigriert.<br>

Mit beiden Varianten 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.<br>

'''Tip''': Ab DSM 6.0 und höher muss nicht mehr manuell auf "Offline" umgeschaltet werden, wenn die Hilfe aus der Anwendung heraus aufgerufen wird!

==Benutzung in Installationspaketen (SPK)==
Die folgenden Dateien/Verzeichnisse müssen dem Paket zusätzlich mitgegeben werden:

Root des Paketes
* /conf/resource (nicht die resource.own!)

package.tgz
* /.helptoc
* /help
* /texts
* helptoc.conf
Sollte ihr Grafiken verwendet haben, müssen diese natürlich ebenfalls im entsprechenden Verzeichnis mitgegeben werden.