WebApps:Hilfe

Einführung

Die neue Online-Hilfe bietet etliche Gestaltungsmöglichkeiten:

Aufruf

Ein Online-Hilfe-Artikel unter Verwendung eines Makros oder über einen Eintrag in einer Tabellenspalte des Typs "Link" über zwei verschiedene URLs aufgerufen werden:

• Unter Verwendung des Keys: @Session_WebAppUrl@/onlinehelp/#/help/<Key>
• Unter Verwendung der internen ID: @Session_WebAppUrl@/onlinehelp/#/help/[<COPSYS_ID>]

Bitte beachten Sie die eckigen Klammern, wenn die ID verwendet wird. Neben den Standard-URLs stehen folgende Zusatzparameter zur Verfügung:

• EnableEdit=True: In Kombination mit der gleichzeitig aktivierten Option HLP_ReadOnlyByDefault (Anwendungseigenschaft) kann ein Editieren ermöglicht werden (siehe „Optionen“).
• NoteMode=True: Bei Einzelartikeln/Single Topics wird nur der Editor angezeigt (Notizfunktion, siehe „Was sind Einzelartikel/Single Topics?“).
• Collapsed=True: Die Hierarchie der Hilfethemen wird standardmäßig zusammengeklappt dargestellt.

Zusatzparameter müssen an die URL angefügt werden. Handelt es sich um den ersten Parameter mit einem Fragezeichen, ansonsten mit einem Kaufmanns-Und (&): @Session_WebAppUrl@/onlinehelp/#/help/<Key>?NoteMode=True bzw. @Session_WebAppUrl@/onlinehelp/#/help/<Key>?NoteMode=True&EnableEdit=True

  Es gibt mehrere Wege, wie man einen Artikel über eine der URLs aufrufen kann:

• Makro (CoPlanner-integrierter Browser): NavAction, BrowserWindow, eine der o.a. URLs anpassen und verwenden.
• Makro (System-Browser): Programm, Browser, eine der o.a. URLs anpassen und verwenden.
• Link (Würfel/Matrixmaske): Im Würfel sollte ein berechnetes Feld mit einer Formel ähnlich der Folgenden erzeugt werden: @Session_WebAppUrl@/onlineHelp/#/help/<Key> oder [<ID>]. <Key> oder [<ID>] müssen durch einen festen Key eines Eintrags oder einen Textwert aus einem anderen Measure ersetzt werden (<ID>: Bei Verwendung der ID die interne COPSYS_ID eines Online-Hilfe-Artikels).
• Link (Tabelle/Zeilenmaske): Wenn eine Link-Spalte für eine Webmaske verwendet werden soll, sollte eine Formel genutzt werden, um den Link zu erzeugen - damit die URL automatisch aktualisiert werden kann, z.B. wenn sich die Serverbezeichnung oder -Port ändert.

Verwenden Sie eine "Typed Calculation"-Formel und geben Sie "@Session_WebAppUrl@/onlinehelp/#/help/" + <Key> oder "@Session_WebAppUrl@/onlineHelp/#/help/[" + <ID> + "]" an.

(Die Angabe @Session_WebAppUrl@ sollte sich innerhalb der Anführungszeichen befinden - sie werden später bei Aufruf automatisch ersetzt).

Alternativ, d.h. im CoPlanner-Client, kann ein indirekter Ansatz über einen so genannten "cop-Link" verwendet werden (angegeben ist die Syntax für eine "Typed Calculation"-Formel): 'cop://&name=Help&aktion=Sonstige&p1=Browserwindow&p2=@Session_WebAppUrl@/onlinehelp/#/help/' + <Key> oder [<ID>] + '&p3=Details&p4=Work&frmlocation=Work'

• Web/Navigation Tiles: Die o.a. URLs können direkt als NavigationAction-Eintrag verwendet werden.

Wie verwalte ich Online-Hilfe-Artikel?

Standardmäßig erzeugt, verschiebt oder löscht man Hilfe-Artikel durch Adaption der "Help Topics" (HLPTopics)-Dimension. Wurde die "HLP_AllowAdd"-Option aktiviert (siehe "Optionen"), kann man auch aus dem Online Editor (während man einen Artikel editiert) einen neuen Artikel anlegen. Siehe "Neuen Artikel während der Bearbeitung anlegen" für weitere Informationen.

Help Topics Dimension (HLPTopics)

Öffnen Sie die HLPTopics-Dimension (diese kann Ihnen im Menü als "Help Topics" zur Verfügung stehen) und ergänzen, ändern oder löschen Sie wie gewünscht Hilfe-Artikel. Bitte beachten Sie, dass beim Löschen von Einträgen auch die existierenden Texte zu diesem Eintrag nach dem Speichern gelöscht sind.

• Name (Pflichtfeld): Der Dimensionseintrag selbst (erste Spalte) wird nur genutzt, um die Artikel geeignet zu bezeichnen und zu gliedern - der Name ist in den späteren Hilfeeinträgen nicht sichtbar. Die Bezeichnung ist völlig Ihnen überlassen.
• Key (Pflichtfeld): Geben Sie jedem Eintrag einen eineindeutigen Schlüssel (über alle Einträge) - dieser Schlüssel kann später genutzt werden, um einen Hilfeeintrag zu öffnen. Verwenden Sie nur alphanumerische Zeichen (A-Z, 0-9) und vermeiden Sie Sonder- sowie Leerzeichen.
• Titel/Title (Pflichtfeld): Der Titel wird später als Überschrift im Artikel, in der Übersicht der Artikel auf der linken Seite und - wenn man die Online-Hilfe im Internet-Browser öffnet - als Fensterbezeichnung/Tabulatorbezeichnung angezeigt.
• Inhalt kopieren/Copy Content From: Wenn Sie einen neuen Eintrag ergänzt haben, können Sie sich entscheiden, den Inhalt aus einem bestehenden Eintrag zu kopieren. Wählen Sie dazu den anderen Eintrag aus - beim Speichern wird der Artikeltext aus dem anderen Eintrag in den neuen Eintrag übertragen. Haben Sie bisher auch noch keinen Key und/oder keinen Titel festgelegt, werden diese ebenfalls übernommen.

Bitte beachten Sie, dass der bestehende Text überschrieben wird, wenn Sie die Funktion nutzen. Bitte beachten Sie auch, dass der Key über alle Einträge eindeutig sein und evtl. adaptiert werden muss.

• Einzelartikel/Single Topic: Wurde für einen Artikel die Option "Single Topic" aktiviert, wird bei Anzeige des Artikels links nur der Artikel selbst angezeigt - keine Hierarchie. Es erscheint, als gäbe es keinen anderen Artikel. Die Funktion kann genutzt werden, um weiterführende Informationen zu einem bestimmten Element anzubieten.

• IsValid/Valid Comment: Die eingegebenen Daten werden in geringem Umfang überprüft, z.B. ob ein eindeutiger Key und ein Titel angegeben wurde und ob der Key bestimmte, kritische Sonderzeichen enthält. Sollte der Eintrag als ungültig erkannt werden, enthält die Spalte "Is Valid" keinen Haken und die Spalte "Valid Comment" zeigt einen erläuternden Text.
• Link (by Key)/Link (by ID): Die beiden Spalten zeigen Beispiellinks auf Basis des angegeben Keys oder der internen ID.

 

Wie kann ich Online-Hilfe-Artikel editieren

Wenn Sie über die Berechtigung zur Änderung von Hilfeeinträgen verfügen (siehe Berechtigungen), wird neben der Überschrift ein Stift dargestellt (rechts):

Klicken Sie auf den Stift, um den Editier-Modus zu aktivieren. Im Editor-Modus kann sowohl der Titel (oben), als auch der Inhalt im Editor bearbeitet werden. Der Editier-Modus kann durch Klick auf das "X"-Symbol rechts vom Titel (oben) beendet werden.

Die meisten Schaltflächen des Editors sollten selbsterklärend sein - oder durch Ausprobieren leicht verständlich sein. Daneben gibt es spezielle Schaltflächen:

• Diskettensymbol (erstes Icon): Haben Sie Änderungen im Text vorgenommen, wird das Symbol rot dargestellt, um darauf hinzuweisen, dass Änderungen gespeichert werden sollten. Bitte klicken Sie auf das Icon, um die Änderungen zu speichern und bevor Sie den Editiermodus beenden.
• AutoSave-Symbol (zweites Icon): Wenn Sie vermeiden möchten, dass Änderungen aus Versehen oder aufgrund einer Fehlfunktion nicht gespeichert werden, klicken Sie einmal auf das Icon, um die "AutoSave"-Funktion zu aktivieren. Ist sie aktiviert, wird das Symbol grün dargestellt und Änderungen werden alle 10 Sekunden automatisch gespeichert. Es kann über eine Option bestimmt werden, ob dieses Feature standardmäßig aktiviert ist (siehe Optionen).
• Verknüpfungssymbol (Kettenicon): Markieren Sie zunächst Text und klicken Sie dann auf das Icon, um den Text in einen Link umzuwandeln und eine URL zu einer Webseite einzugeben. Bitte geben Sie immer am Anfang http:// bzw. https:// mit an, da der Link sonst nicht funktionieren wird. Wird die Online-Hilfe innerhalb des CoPlanner-Clients aufgerufen, öffnet sich ein angeklickter Link in einem neuen Reiter. Wird die Online-Hilfe im CoPlanner Web-Client aufgerufen, öffnet sich ein angeklickter Link in einem neuen Fenster oder Reiter.
• Tabelle (letzte Icon(s)): Die Schaltfläche erzeugt eine Tabelle. Durch Verwendung der zwei zusätzlich erscheinenden Icons können weitere Spalten oder Zeilen ergänzt oder – wenn die <Strg>-Taste gedrückt gehalten wird – gelöscht werden.
• Link hinzufügen (auf der linken Seite, oben): Wird ein "normaler" Online-Hilfe-Artikel angesehen (d.h. Einzelartikel/"Single Topic" ist für den Eintrag nicht aktiviert), wird auf der linken Seite die Hierarchie der Artikel angezeigt, in der sich der Artikel befindet. Haben Sie weitere Artikel-"Bäume" (Ordner) unterhalb des Wurzeleintrags angelegt, werden Sie nur die aktuelle Hierarchie sehen. Über die "Link hinzufügen"-Funktion können Sie manuelle Links zu anderen Hilfeartikeln erzeugen (normalerweise außerhalb der aktuellen Hierarchie), damit Sie zu anderen Bereichen "springen" können (z.B. um von einer Hierarchie mit deutschen Hilfetexten zur Hierarchie mit englischen Hilfetexten zu wechseln).

Weitere Hinweise:

• Zusätzliche Leerzeilen werden leider beim Speichern entfernt. Es ist nicht möglich, viel Platz zwischen Absätzen oder anderen Elementen durch viele Leerzeilen zu erzeugen. Probieren Sie es aus, wie ihr Text nach dem Speichern und dem Beenden des Editier-Modus dargestellt wird.
• Um Aufzählungs- oder Listenelemente auf tiefere Ebenen ein- oder auszurücken, verwenden Sie die <Tabulator>-Taste und die Kombination aus <Shift>+<Tabulator>-Taste, wenn Sie sich ein einer Aufzählung befinden.
• Bilder werden immer auf einer neuen Zeile dargestellt (sie können nicht Bestandteil des Textes von Aufzählungen und Listen sein). Sie werden aber zentriert dargestellt und passend zum verfügbaren Platz skaliert.

 

Neue Artikel im Editier-Modus anlegen

Wurde die "HLP_AllowAdd"-Option aktiviert (siehe "Optionen"), können neue Artikel direkt aus dem Online-Hilfe-Editor angelegt werden. In diesem Fall erscheint ein "Plus"-Symbol rechts vom Titel. Um einen neuen Artikel anzulegen, klicken Sie auf das "Plus"-Symbol, spezifizieren Sie die folgenden Felder und klicken Sie auf "Speichern":

• Titel: Der sichtbare Titel des Online-Hilfe-Artikels.
• Topic Key: Jeder Artikel muss einen global eindeutigen Schlüssel aufweisen, um den Artikel aufrufen zu können. Während der Titel eingegeben wird, wird der Schlüssel automatisch auf Basis des Titels und Entfernen von Sonderzeichen (z.B. Leerzeichen und Klammern) erzeugt. Man kann ihn aber anschließend adaptieren.
• Eine Ebene darunter anlegen?: Neue Artikel werden standardmäßig parallel zum aktuellen Artikel angelegt. Soll der neue Artikel hierarchisch unterhalb des aktuellen Artikels angelegt werden, bitte die Option aktivieren.
• Einzelartikel?: Wie in "Was sind Einzelartikel/Single Topics?" beschrieben, kann man Artikel entsprechend kennzeichnen. Damit erscheinen sie wie einzelne Artikel und zeigen keine Hierarchie (links). Um einen Einzelartikel anzulegen, die Option aktivieren.

 

Was sind Einzelartikel/Single Topics

Standardmäßig wird für Online-Hilfe-Artikel auf der linken Seite die Hierarchie der Artikel angezeigt, in der sich der Artikel befindet.

Innerhalb der HLPTopics-Dimension können Sie weitere Artikel-"Bäume" (Ordner) unterhalb des Wurzeleintrags anlegen, um damit mehrere Hierarchien zu bilden. In manchen Fällen möchte man aber vielleicht nur einen erklärenden Text bereitstellen, ohne, dass die Nutzer in die reguläre Hilfe-Hierarchie umgeleitet werden. Für diesen Zweck steht in der HLPTopics-Dimension die Eigenschaft Einzelartikel/Single Topic zur Verfügung. Ist die Option aktiviert, wird bei Aufruf des Artikels auf der linken Seite nur der Artikel selbst, aber keine Hierarchie dargestellt. Es kann dabei sinnvoll sein, manuell dennoch einen Link, z.B. zur regulären Online-Hilfe zu ergänzen, damit Nutzer weitere Informationen erhalten können. Das ist aber nicht zwingend erforderlich. Generell wird empfohlen, Einzelartikel dennoch in einem separaten “Baum” bzw. Hierarchie anzulegen. Damit wird es möglich, dass der Bearbeiter (nicht die Nutzer) über einen separaten Link auf das „Elternelement“ springen kann und alle Einzelartikel bequem im Überblick zu haben.

NoteMode:

Einzelartikel/Single Topics bieten ein zusätzliches Feature: Wird "NoteMode" an die URL bei Aufruf angefügt (z.B. @Session_WebAppUrl@/coplanner/onlineHelp/#/help/ENEX2?NoteMode=True), ist automatisch der Editor aktiv, man kann keine zusätzlichen Artikel anlegen (kein "Plus"-Icon rechts oben) und es werden auf der linken Seite keine Verknüpfungen angeboten - die Seite ist also einfach bereit, als eine Art "Notizblock" Ihre Inhalte aufzunehmen.  

Makro beim Speichern ausführen

Es ist möglich, ein Makro in der HLPTopics-Dimension in der Spalte "MacroOnSave" zu hinterlegen. Jedes Mal, wenn der Inhalt geändert und gespeichert wird, wird dieses im Hintergrund ausgeführt. Haben Sie die Hilfe-Beispiele importiert steht ein Beispielartikel unter „Einzelartikel?“ zur Verfügung, mit dem dieses Feature getestet werden kann. Im Beispielartikel wird beim Speichern das Makro "HLP_Example_MacroOnSave_MCR" mit dem Import "HLP_Example_MacroOnSave_IMP" ausgeführt. Der Import erzeugt die Tabelle „HelpMacroOnSaveDemo“, wenn sie noch nicht existiert in der Datenbank und speichert bei jeder Ausführung die interne ID des geänderten Artikels und einen Zeitstempel in der Tabelle.

Hinweise:

• Wurde ein "MacroOnSave" für einen Artikel in der HLPTopics-Dimension hinterlegt, werden für diesen Artikel alle "AutoSave"-Einstellungen ignoriert. Es ist erforderlich, alle Änderungen in dem Artikel manuell zu speichern.
• Das Makro wird im Hintergrund asynchron ausgeführt (d.h. der Inhalte des Artikels muss noch nicht in der Datenbank gespeichert worden sein, wenn das Makro bereits ausgeführt wird)
• Im Makro können nur Befehle genutzt werden, die keine Nutzerinteraktion beinhalten. D.h. es ist z.B. nicht möglich, im Makro einen "Message"-Befehl zu verwenden, um ein Dialogfenster mit einer Nachricht auf dieser Seite anzuzeigen.

 

Berechtigungen

Der Zugriff auf Online-Hilfe-Artikel und die Möglichkeit, Artikel zu überarbeiten, werden über die Berechtigung auf die HLPTopics-Dimensionselemente und/oder über die aktivierten Optionen (HLP_AllowAdd, HLP_ReadOnlyByDefault und HLP_UseDimSecurity) gesteuert - siehe Optionen:

• Benutzer müssen über eine Lese-Berechtigung auf die Dimensionselemente verfügen, damit sie Online-Hilfe-Artikel sehen/lesen können.
• Option HLP_UseDimSecurity ist deaktiviert: Ein Nutzer muss als "PowerUser" angemeldet sein, um editieren zu können.
• Option HLP_UseDimSecurity ist aktiviert: Benutzer müssen über eine Editier-Berechtigung auf die relevanten Dimensionselemente verfügen, die sie ändern können sollen. Dies gilt sowohl für den Hilfetext (diesen Text) als auch das Dimensionselement selbst.

Zusätzlich kann es sein, dass der Zugriff auf die HLPTopics-Dimension im Menü über die Benutzerverwaltung limitiert wurde (sie kann z.B. als "Help Topics" bereitgestellt worden sein).

Achtung: Verfügt ein Nutzer nicht über das Zugriffsrecht auf die Dimension über das Menü, kann er/sie aber dennoch weiterhin über Lese- und Änderungsrechte auf den Dimensionselementen selbst verfügen - und damit den Text über den Online-Hilfe-Editor ändern. Daher sollten immer auch die Dimensionsberechtigungen überprüft werden!

• Option HLP_ReadOnlyByDefault ist aktiviert: Obwohl ein Nutzer grundsätzlich die Berechtigung für Änderungen hat (weil er z.B. als PowerUser angemeldet ist oder für die HLPTopics-Dimensionseinträge Schreibberechtigung hat) steht der Editier-Modus nicht zur Verfügung - bis die Online-Hilfe mit der zusätzlichen Angabe "&EnableEdit=True" in der URL aufgerufen wird.

Die Idee dahinter ist, dass ein Nutzer nicht "versehentlich" Inhalte ändern kann, sondern erst, wenn bewusst die Möglichkeit zum Editieren aktiviert wurde.

• Option HLP_AllowAdd ist aktiviert: Verfügt der Nutzer grundsätzlich über die Berechtigung für Änderungen in der Online-Hilfe, dann können direkt aus dem Online-Hilfe-Editor heraus über das "Plus"-Symbol neben dem Titel neue Artikel angelegt werden (siehe Neue Artikel im Editier-Modus anlegen).

 

Optionen

Die Online-Hilfe berücksichtigt folgende Optionen (in den Anwendungseigenschaften/Application Properties definiert):

• HLP_AutoSaveOn (Boolean): Standard: Aktiviert. Ist die Option aktiviert, ist die AutoSave-Funktion standardmäßig beim Wechsel in den Editier-Modus aktiviert.
• HLP_UseDimSecurity (Boolean): Standard: Deaktiviert. Ist die Option aktiviert, ergibt sich die Berechtigung für Änderungen in der Online-Hilfe aus der Schreibberechtigung auf den HLPTopics-Dimensionselementen. Ist die Option deaktiviert, muss sich der Nutzer als PowerUser anmelden, um Hilfeeinträge ändern zu können.
• HLP_ReadOnlyByDefault (Boolean): Standard: Deaktiviert. Ist die Option aktiviert, können Inhalte nicht editiert werden, auch wenn der Nutzer grundsätzlich durch PowerUser-Status oder Dimensionsberechtigung berechtigt wäre. Um Editier-Modus aufrufen zu können, muss stattdessen die Hilfe mit dem Parameter "&EnableEdit=True" in der URL aufgerufen werden.

Die Idee dahinter ist, dass ein Nutzer nicht "versehentlich" Inhalte ändern kann, sondern erst, wenn bewusst die Möglichkeit zum Editieren aktiviert wurde.

• HLP_AllowAdd (Boolean): Standard: Deaktiviert. Ist die Option aktiviert, können Nutzer über das "Plus"-Symbol neben dem Titel im Editier-Modus neue Artikel anlegen.
• HLP_AutoSaveInterval (Text): Standard: 10000. Legt die Zeit für das AutoSave-Intervall in Millisekunden fest.