Onlinehilfe-Tool für Microsoft Dynamics 365 Business Central Extensions. Aktuelle Version: 3.0.2.
Handbuch
Erstellungsdatum: 2024/04/29 Die aktuelle Version dieses Handbuchs finden Sie unter:
☰ Inhaltsverzeichnis
Allgemein
NAVAX Help Builder NAVAX Help Builder wurde in erster Linie dazu entwickelt, um Onlinehilfen für Microsoft Dynamics 365 Business Central Extensions zu erstellen. Es können aber auch Onlinehilfen erstellt werden, welche nicht mit Business Central in Verbindung stehen. Ein Beispiel dafür ist die Hilfe, die Sie gerade lesen...
Vorbereitungen
So funktioniert der Help Builder Jedes Hilfeprojekt besteht im Grunde aus einer Ansammlung aus ganz normalen Textdateien, in denen der Hilfetext für die verschiedenen Hilfethemen gespeichert ist. Diese Dateien werden am Server des Help Builders (also auf navax.app) abgelegt bzw. hochgeladen. Wird dann die Onlinehilfe für ein Hilfethema aufgerufen, bereitet der Help Builder das Hilfethema entsprechend auf und das Ergebnis wird im Browser angezeigt...
AL-Extension einrichten Damit die Onlinehilfe vom Benutzer einer Business Central Extension aufgerufen werden kann, müssen in der app.json der Extension die Links zur Onlinehilfe angegeben werden...
Visual Studio Code einrichten Die Hilfe sollte in Visual Studio Code geschrieben werden. Es ist zwar auch möglich, die Hilfe mit einem anderen Tool zu schreiben, allerdings stehen dann keine unterstützenden Funktionen bereit...
Hilfe schreiben
Basics
Themen erstellen Der Help Builder setzt voraus, dass die einzelnen Hilfedateien pro Sprache in einem Ordner (2 Zeichen, Kleinbuchstaben) zusammengefasst werden...
Inhaltsverzeichnis erstellen Jedes Hilfeprojekt benötigt ein Inhaltsverzeichnis welches in einer eigenen Datei mit dem Namen index.nchb erstellt wird...
Themenverknüpfungen & Externe Links
Indexgesteuerter Ansatz Bis jetzt wurde der Text, der bei Themenüberschriften und Themenverknüpfungen angezeigt werden soll, immer direkt im Hilfethema angegeben...
Themenumleitungen Umleitungen von Hilfethemen können realisiert werden, indem man in der ersten Zeile einer Hilfedatei eine andere Hilfedatei angibt. Damit der Help Builder die Umleitung erkennt, muss die Dateiendung .nchb mitangegeben werden...
Versionshinweise erstellen Versionshinweise können über die _ReleaseNotes-Snippets hinzugefügt werden...
Rechtschreibprüfung Für die Überprüfung der Rechtschreibung ist die Visual Studio Code Extension Code Spell Checker zu empfehlen...
Hilfetext vorschlagen
Hilfetext aus AL-Datei vorschlagen Über das Suggest Help Text from AL File Command kann aus einem AL-Objekt (page, pageextension, report oder xmlport) ein Hilfethema generiert werden. Dabei wird auf Grundlage des Objekt-Aufbaus und den Tooltips ein Hilfetext vorgeschlagen, der dann als Ausgangsbasis für das Hilfethema verwendet werden kann...
Ghostwriter Mit dem NCHB Ghostwriter kann innerhalb kürzester Zeit ein Vorschlag für eine komplette Onlinehilfe oder für neu hinzugefügte AL-Objekte erstellt werden...
Erweitert
Hinweise Hinweise können über die _Note-Snippets hinzugefügt werden...
Listen Punktelisten können über das Snippet _List hinzugefügt werden...
Tabellen Tabellen können über die _Table-Snippets hinzugefügt werden...
Bilder Bilder können über das Snippet _Image hinzugefügt werden...
Animierte Bilder (GIF) Werden animierte Bilder eingefügt (Dateiendung .gif) sind grundsätzlich die selben Dinge zu beachten wie für normale ...
Videos Videos können entweder indirekt über navax.app oder direkt (nicht empfohlen) verlinkt werden...
Seitenumbrüche Grundsätzlich wird beim Drucken der Hilfe bzw. bei der Erstellung eines PDFs für jedes Hilfethema ein Seitenumbruch eingefügt...
Anzeige Bildschirm/Druck Mit <span class=hideonprint> bzw. <span class=hideonscreen> können Elemente entweder nur am Bildschirm oder nur beim Drucken angezeigt werden...
Quelltext Quelltext kann über die _SourceCode-Snippets hinzugefügt werden...
Hilfe hochladen
Hilfe auf navax.app hochladen Damit die Hilfe Online verfügbar ist, muss das Hilfeprojekt auf navax.app hochgeladen werden...
Anhang
Versionshinweise
Docs / NAVAX Help Builder / Allgemein NAVAX Help Builder
NAVAX Help Builder wurde in erster Linie dazu entwickelt, um Onlinehilfen für Microsoft Dynamics 365 Business Central Extensions zu erstellen. Es können aber auch Onlinehilfen erstellt werden, welche nicht mit Business Central in Verbindung stehen. Ein Beispiel dafür ist die Hilfe, die Sie gerade lesen.
Die nachfolgende Anleitung geht allerdings davon aus, dass Sie eine Onlinehilfe für eine Business Central Extension erstellen wollen. Alle notwendigen Schritte werden anhand der Beispiel-Erweiterung Abracadabra erklärt.
Hinweis
NAVAX Help Builder wurde mit dem Kürzel "NCHB" entwickelt.
NCHB steht für NAVAX Consulting Help Builder.
Beispiele
Hier finden Sie einige Beispiele von Onlinehilfen, welche mit dem NAVAX Help Builder erstellt wurden:
Docs / NAVAX Help Builder / Vorbereitungen So funktioniert der Help Builder
Jedes Hilfeprojekt besteht im Grunde aus einer Ansammlung aus ganz normalen Textdateien, in denen der Hilfetext für die verschiedenen Hilfethemen gespeichert ist. Diese Dateien werden am Server des Help Builders (also auf navax.app) abgelegt bzw. hochgeladen. Wird dann die Onlinehilfe für ein Hilfethema aufgerufen, bereitet der Help Builder das Hilfethema entsprechend auf und das Ergebnis wird im Browser angezeigt.
Beispiel eines Onlinehilfe-Aufrufs:
https://www.navax.app/contextSensitiveHelpUrl.php?AppID=NVXYZ&L=de&ObjID=HelloWorld
AppID
Damit der Onlinehilfe-Aufruf einem Hilfeprojekt zugeordnet werden kann, muss im Aufruf der Parameter AppID angegeben werden. Diese AppID wird vom NAVAX App Team vergeben bzw. muss mit dem NAVAX App Team abgestimmt und am Server eingerichtet werden. NVXYZ ist z.B. der Abracadabra Beispiel-Erweiterung zugeordnet.
ObjID
Über den Parameter ObjID wird das Hilfethema bzw. genauer gesagt der Dateiname des Hilfethemas angegeben.
Ordnerstruktur und Sprachen
Jedes Hilfeprojekt auf navax.app hat folgende Ordnerstruktur:
AppID\help\Language
Pro Sprache sind die einzelnen Hilfedateien in einem Ordner (2 Zeichen, Kleinbuchstaben) zusammengefasst.
Beispiel:
Beim Aufruf der Onlinehilfe (z.B. aus Business Central) wird das entsprechende Hilfethema zuerst im Ordner der angeforderten Sprache (Parameter L) gesucht.
Wenn keine Sprache im Aufruf angegeben ist, wird mit der im Browser eingestellten Sprachen gesucht.
Ist das Hilfethema in der Sprache nicht verfügbar, wird, falls vorhanden, in den Ordnern der anderen Sprachen gesucht.
Wird das Hilfethema auch hier nicht gefunden, wird das Inhaltsverzeichnis des Hilfeprojekts angezeigt.
Beispiel für den Aufruf https://www.navax.app/contextSensitiveHelpUrl.php?AppID=NVXYZ&L=de&ObjID=HelloWorld:
Jede Seite wird vom Help Builder vor der Anzeige aufbereitet. Dabei werden der Seite unter anderem auch Aktionen wie z.B. Feedback und Druck hinzugefügt.
Einstellungen wie die Feedback E-Mail-Adresse werden am Server vom NAVAX App Team für das Hilfeprojekt eingerichtet.
Darüber hinaus fügt der Help Builder dem Inhaltsverzeichnis automatisch eine Aktion für das Handbuch hinzu. Dies ermöglicht es dem Benutzer, die gesamte Hilfe auszudrucken oder als PDF zu speichern.
Docs / NAVAX Help Builder / Vorbereitungen AL-Extension einrichten
Damit die Onlinehilfe vom Benutzer einer Business Central Extension aufgerufen werden kann, müssen in der app.json der Extension die Links zur Onlinehilfe angegeben werden.
Für die Zuordnung der Extension-Aufrufe zu einem Hilfeprojekt muss in allen Links der Parameter AppID angegeben werden. Diese AppID wird vom NAVAX App Team vergeben bzw. muss mit dem NAVAX App Team abgestimmt und am Server eingerichtet werden. NVXYZ ist z.B. der Abracadabra Beispiel-Erweiterung zugeordnet.
Sobald eine AppID vergeben und eingerichtet wurde, ist ein Aufruf mit der GUID der Extension ebenfalls möglich. Diese Methode sollte aber nur für spezielle interne Calls verwendet werden.
app.json
Folgende Angaben müssen auf App-Ebene in der app.json hinzugefügt werden:
Über supportedLocales wird festgelegt, für welche Sprachen die Hilfe grundsätzlich geplant ist bzw. welche Sprachen Business Central im Onlinehilfe-Aufruf explizit mitsenden soll.
Die erste angegebene Sprache (hier en-US) wird als default-Wert verwendet und sollte fix auf en-US gesetzt werden, auch wenn keine englische Hilfe geplant ist. Alle weiteren Sprachen müssen danach angegeben werden, damit Business Central die entsprechende Sprache auch im Onlinehilfe-Aufruf mitsendet.
Hinweis
Ob die Hilfe in der angeforderten Sprache später auch tatsächlich verfügbar ist, spielt hier noch keine Rolle. Hier geht es nur darum, welche Sprachen Business Central generell beim Aufruf der Onlinehilfe berücksichtigen soll.
In der hier verwendeten Einstellung sind z.B. zusätzlich alle deutschen Sprachen definiert. Daraus ergibt sich folgendes:
Hat der Benutzer die Sprache German (Austria) eingestellt, wird die Onlinehilfe mit dem Parameter de-AT aufgerufen.
Hat der Benutzer die Sprache Danish (Denmark) eingestellt, wird der Aufruf zur Onlinehilfe mit en-US erfolgen, da da-DK nicht Teil der supportedLocales ist.
Page-Ebene
Folgende Angaben müssen auf Page-Ebene hinzugefügt werden:
ContextSensitiveHelpPage = 'TODO';
Über das ContextSensitiveHelpPage Property in den page bzw. requestpage Objekten wird die Verbindung zu den einzelnen Hilfethemen hergestellt.
TODO muss durch den Dateinamen vom Hilfethema ersetzt werden und wird beim Aufruf der Onlinehilfe als ObjID Parameter mitgegeben.
Es wird empfohlen für ContextSensitiveHelpPage (und damit für den Dateinamen des Hilfethemas) den Namen der Page (bzw. den Objektnamen) zu verwenden.
Beispiel:
Für den Fall, dass das selbe Hilfethema aus verschiedenen Pages aufgerufen werden soll, sollten Themenumleitungen verwendet werden. Es ist zwar möglich, den selben Namen im ContextSensitiveHelpPage Property in allen Pages anzugeben, es wird aber nicht empfohlen.
Der Vorteil der Themenumleitungen besteht darin, dass diese erst am Server und somit unabhängig von der Extension aufgelöst werden. Sollte es sich später herausstellen, dass für die Pages doch verschiedene Hilfen notwendig sind, kann das (ohne Änderungen an der Extension) später jederzeit geändert werden und alle Kunden haben sofort Zugriff auf die geänderte/erweiterte Hilfe.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Themenumleitungen.
Docs / NAVAX Help Builder / Vorbereitungen Visual Studio Code einrichten
Die Hilfe sollte in Visual Studio Code geschrieben werden. Es ist zwar auch möglich, die Hilfe mit einem anderen Tool zu schreiben, allerdings stehen dann keine unterstützenden Funktionen bereit.
NAVAX Help Builder Extension
Für die Erstellung von Hilfethemen in Visual Studio Code wurde eine eigene Visual Studio Code Extension bzw. der NAVAX Help Builder entwickelt. Diese Extension stellt verschiedene Commands und Snippets für das Erstellen bzw. das Schreiben der Hilfethemen zur Verfügung.
Über eine Vorschau kann das spätere Ergebnis eines Hilfethemas direkt in Visual Studio Code angezeigt werden.
Zusätzlich werden Tags und spezielle Parameter innerhalb der Hilfethemadateien farblich gekennzeichnet.
Hinweis
NAVAX Help Builder wurde mit dem Kürzel "NCHB" entwickelt.
NCHB steht für NAVAX Consulting Help Builder.
Installation
Die aktuellste Version kann hier heruntergeladen werden:
nchb-3.0.2.vsix
Die Installation wird in Visual Studio Code im Extension Bereich über die Aktion Install from VSIX durchgeführt.
Nach der Installation muss Visual Studio Code entweder neu gestartet, oder ein Reload Window durchgeführt werden.
Snippets
Die Extension stellt Snippets für folgende Bereiche zur Verfügung:
NCHB
Diese Snippets erleichtern das Schreiben der Hilfetexte.
Auf die genauere Funktionsweise der einzelnen Snippets wird später noch eingegangen.
Commands
Zusätzlich zu den Snippets werden durch die Help Builder Extension Commands bereitgestellt. Diese können über Ctrl+Shift+P bzw. über F1 ausgeführt werden.
Help
Über dieses Command kann die Hilfe zum Help Builder geöffnet werden.
Preview
Über dieses Command kann eine Vorschau für ein Hilfethema aufgerufen werden.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Themen erstellen.
Suggest Help Text from AL File
Über dieses Command kann aus einem AL-Objekt (page, pageextension, report oder xmlport) ein Hilfethema generiert werden. Dabei wird auf Grundlage des Objekt-Aufbaus und den Tooltips ein Hilfetext vorgeschlagen, der dann als Ausgangsbasis für das Hilfethema verwendet werden kann.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Hilfetext vorschlagen, Hilfetext aus AL-Datei vorschlagen.
Check for missing Topics
Dieses Command prüft, ob für alle AL-Objekte eines Ordners entsprechende nchb-Dateien in einem Hilfe-Ordner existieren.
Create missing Topics
Dieses Command erstellt für alle AL-Objekte eines Ordners entsprechende nchb-Dateien in einem Hilfe-Ordner falls diese dort noch nicht existieren.
Auf die genauere Funktionsweise der einzelnen Commands wird später noch eingegangen.
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Themen erstellen
Der Help Builder setzt voraus, dass die einzelnen Hilfedateien pro Sprache in einem Ordner (2 Zeichen, Kleinbuchstaben) zusammengefasst werden.
Weitere Informationen dazu finden Sie unter Vorbereitungen, So funktioniert der Help Builder.
Es wird empfohlen die dafür notwendige Ordnerstruktur direkt im Verzeichnis der AL-Extension anzulegen. Dadurch ist die Onlinehilfe auch gleich in den Source Control Prozesses miteingebunden.
Die Hilfe selbst sollte in Visual Studio Code geschrieben werden. Es ist zwar auch möglich die Hilfe mit einem anderen Tool zu schreiben, allerdings stehen dann keine unterstützenden Funktionen bereit.
Weitere Informationen dazu finden Sie unter Vorbereitungen, Visual Studio Code einrichten.
Jedes Hilfethema ist in einer eigenen Datei mit der Dateiendung .nchb gespeichert. Bei der Datei handelt es sich im Prinzip um eine ganz normale Textdatei.
Wichtig ist, dass die Datei als UTF-8 Datei (mit oder ohne BOM) angelegt wird, damit später Sonderzeichen richtig dargestellt werden. Die Standardcodierung von Visual Studio Code ist UTF-8 ohne BOM. In der Status Bar rechts unten sehen Sie die Bezeichnung UTF-8. Wenn nicht, klicken Sie darauf, um die Aktionsleiste zu öffnen, und wählen Sie Save with Encoding. Sie können nun eine neue Codierung für die Datei auswählen.
Aufbau des Hilfethemas
Jedes Hilfethema beginnt mit einem sogenannten Topic Header. Der Topic Header wird mit dem <h1> Tag angegeben. Ist kein <h1> Tag angegeben, wird automatisch eine indexgesteuerte Themenüberschrift hinzugefügt. Im Anschluss daran kann beliebiger Text geschrieben werden. Ein Zeilenumbruch wird später auch als solcher dargestellt.
Über das Command NCHB: Preview des Help Builders kann das spätere Ergebnis des Hilfethemas direkt in Visual Studio Code angezeigt werden:
Hinweis
Preview zeigt eine Vorschau an, bei der die sprachabhängigen Texte abhängig vom Ordner auf Englisch oder auf Deutsch umgewandelt werden.
Sprachabhängige Texte werden vom Help Builder zum Zeitpunkt der Anzeige der Hilfe eingefügt bzw. konvertiert.
Ein Beispiel eines sprachabhängigen Textes ist der Text für eine Themenverknüpfung, der automatisch je nach Sprache der Text "Weitere Informationen dazu finden Sie unter" oder "For more information, see" hinzugefügt wird.
Formatierung des Hilfethemas
Für die Formatierung des Textes werden HTML Tags verwendet. Zusätzlich stehen spezielle Tags zur Verfügung, welche vom Help Builder später bei der Anzeige des Themas automatisch umgewandelt werden.
Für eine schnellere Erstellung der Onlinehilfe stellt der Help Builder Snippets für die häufigsten Anforderungen zur Verfügung.
Wichtig
Das <h1> Tag wird vom Help Builder speziell behandelt und sollte nur für den Topic Header verwendet werden.
Jedes <h2> Tag wird automatisch zur "In diesem Thema" Liste hinzugefügt.
<h3> Tags werden zur "In diesem Thema" Liste hinzugefügt, wenn sie am Anfang einer neuen Zeile stehen. Steht also in der Zeile vor dem Tag ein anderes Tag (z.B. <li><h3>) wird es nicht hinzugefügt. Falls ein Tag nicht hinzugefügt werden soll, kann auch folgendes angegeben werden: <h3 class="dummy">.
Snippets
Folgende Snippets stehen zur Verfügung:
Snippet
Code/Ergebnis
_NewTopic
Erstellt ein Beispiel welches als Ausgangsbasis verwendet werden kann.
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Inhaltsverzeichnis erstellen
Jedes Hilfeprojekt benötigt ein Inhaltsverzeichnis welches in einer eigenen Datei mit dem Namen index.nchb erstellt wird.
Im Gegensatz zu normalen Hilfethemen beginnt das Inhaltsverzeichnis nicht mit einem Topic Header. Es gibt also keine <h1> Angabe. Der Topic Header wird später vom Help Builder automatisch hinzugefügt.
Darüber hinaus fügt der Help Builder dem Inhaltsverzeichnis automatisch diverse Texte und eine Aktion für das Handbuch hinzu. Dies ermöglicht es dem Benutzer, die gesamte Hilfe auszudrucken oder als PDF zu speichern.
Das Inhaltsverzeichnis selbst besteht aus einer Ansammlung an Themenverknüpfungen, die über das Snippet _IndexLink hinzugefügt werden.
Beispiel:
<li><link "HelloWorld">Hallo Welt</link></li>
Ergebnis:
Hinweis
Es sollte für jedes Thema eine Verknüpfung im Index vorhanden sein.
Gruppierung
Themenverknüpfungen können im Inhaltsverzeichnis auch gruppiert werden.
Beispiel:
Jede Gruppe (egal ob Hauptgruppe oder untergeordnete Gruppe) startet mit einer neuen Zeile und wird folgendermaßen angegeben:
<group>Gruppenüberschrift</group><ul>
Jede Gruppe muss am Ende mit einer neuen Zeile folgendermaßen wieder geschlossen werden:
</ul>
Beispiel:
<group>Hauptgruppe 1</group><ul>
<li><link "CreateIndex">TopicLinkText1</link></li>
<li><link "CreateIndex">TopicLinkText2</link></li>
</ul>
<group>Hauptgruppe 2</group><ul>
<group>Untergeordnete Gruppe 2.1</group><ul>
<group>Untergeordnete Gruppe 2.1.1</group><ul>
<li><link "CreateIndex">TopicLinkText1</link></li>
<li><link "CreateIndex">TopicLinkText2</link></li>
<li><link "CreateIndex">TopicLinkText3</link></li>
</ul>
<group>Untergeordnete Gruppe 2.1.2</group><ul>
<li><link "CreateIndex">TopicLinkText</link></li>
</ul>
</ul>
</ul>
Tipp
Im Index können Leerzeilen verwendet werden, um die Gruppierung optisch übersichtlicher zu gestalten. Leerzeilen im Index werden später vom Help Builder ignoriert.
Zusatztexte
Der Help Builder fügt dem Inhaltsverzeichnis automatisch diverse Texte und eine Aktion für das Handbuch hinzu.
Werden zusätzlich eigene Texte benötigt, können diese in einer Datei mit dem Namen indexNotes.nchb hinterlegt werden.
Der Help Builder fügt dann den Inhalt der Datei ebenfalls dem Inhaltsverzeichnis hinzu.
Snippets
Folgende Snippets stehen zur Verfügung:
Snippet
Code/Ergebnis
_NewIndex
Erstellt ein Beispiel welches als Ausgangsbasis verwendet werden kann.
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Themenverknüpfungen & Externe Links
Themenverknüpfungen
Hinweis
Die nachfolgende Vorgehensweise wird für Themenverknüpfungen wird nicht mehr empfohlen. Verwenden Sie stattdessen den indexgesteuerten Ansatz.
Zum besseren Verständnis des indexgesteuerten Ansatzes empfehlen wir, dieses Thema trotzdem zu lesen.
Verknüpfungen zwischen den Hilfethemen können über das Snippet _TopicLink hinzugefügt werden.
Über das Snippet _TopicLinkMoreInfo können Verknüpfungen hinzugefügt werden, denen später der sprachabhängige Text "Weitere Informationen dazu finden Sie unter" vorangestellt wird.
In beiden Fällen muss der Name der Hilfedatei in Anführungszeichen und ohne die Dateiendung .nchb angegeben werden.
Beispiel:
Es ist auch möglich, Hilfethemen aus anderen Hilfeprojekten so zu verlinken, als ob Sie Teil des aktuellen Hilfeprojekts wären.
Dafür muss vor dem Dateinamen der verlinkten Hilfedatei die AppID des verlinkten Hilfeprojekts in eckigen Klammern angegeben werden.
Beispiel:
<link "[NCEX]ReleaseNotes">Anhang, Versionshinweise aus der NAVAX Extension Base</link>
Externe Links
Verknüpfungen zu externen Quellen können über die _ExternalLink-Snippets hinzugefügt werden.
Es ist auch möglich externe Quellen über standard HTML zu verlinken.
Damit die Formatierung mit der restlichen Hilfe übereinstimmt, sollte aber class="HELP" im Link angegeben sein.
Ergebnis:
Weitere Informationen dazu finden Sie unter www.navax.com
Hinweis
</moreexternal> fügt automatisch einen Punkt am Ende des Links hinzu.
Das kann durch die Verwendung von </moreexternal+> verhindert werden.
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Indexgesteuerter Ansatz
Bis jetzt wurde der Text, der bei Themenüberschriften und Themenverknüpfungen angezeigt werden soll, immer direkt im Hilfethema angegeben.
Also z.B.:
<h1>Hello World</h1>
oder:
<more "HowNCHBWorks">Vorbereitungen, So funktioniert der Help Builder</more>
Der Nachteil bei dieser Form der Angabe ist, dass bei Veränderungen in der Struktur oder der Anordnung und Gruppierung der Hilfethemen im Inhaltsverzeichnis auch alle davon betroffenen Überschriften und Verknüpfungen aktualisiert werden müssen. Vor allem bei größeren Onlinehilfen führt dieser Ansatz schnell zu Fehlern und ist zeitaufwendig.
Mit dem indexgesteuerten Ansatz können diese Probleme vermieden werden, da hier der angezeigte Text durch das Inhaltsverzeichnis bestimmt wird. Wenn die Struktur oder die Anordnung und Gruppierung der Hilfethemen im Inhaltsverzeichnis später geändert wird, müssen die Themenüberschriften und Themenverknüpfungen nicht mehr zusätzlich geändert werden.
Indexgesteuerte Themenüberschriften
Für Themenüberschriften steht das Snippet _iTopicHeader zu Verfügung.
Anstatt den Text wie bisher direkt im Thema anzugeben:
<h1>Hello World</h1>
kann einfach der Platzhalter <iheader> angegeben werden:
<h1><iheader></h1>
Die Onlinehilfe zeigt später den im Inhaltsverzeichnis angegebenen Text anstelle des Platzhalters an.
Hinweis
In der Vorschau wird nur der Text <Indexgesteuerter Header> angezeigt.
Indexgesteuerte Themenverknüpfungen
Für Themenverknüpfungen stehen die Snippets _iTopicLink, _iTopicLinkMoreInfo, _iTopicLinkShort und _iTopicLinkShortMoreInfo zu Verfügung.
Anstatt den Text wie bisher direkt beim Link anzugeben:
<more "HowNCHBWorks">Vorbereitungen, So funktioniert der Help Builder</more>
braucht die i-Variante keinen Text mehr:
<imore "HowNCHBWorks">
Die Onlinehilfe zeigt später den im Inhaltsverzeichnis angegebenen Text an.
Hinweis
In der Vorschau wird nur der Text <Indexgesteuerter Link> angezeigt.
<imore fügt automatisch einen Punkt am Ende des Links hinzu.
Das kann durch die Verwendung von <imore+ verhindert werden.
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Themenumleitungen
Umleitungen von Hilfethemen können realisiert werden, indem man in der ersten Zeile einer Hilfedatei eine andere Hilfedatei angibt. Damit der Help Builder die Umleitung erkennt, muss die Dateiendung .nchb mitangegeben werden.
Hier wird die Hilfe der Zauberspruchkarte (ContextSensitiveHelpPage = 'MagicSpellCard') zur allgemeinen Hilfe der Zaubersprüche (ContextSensitiveHelpPage = 'MagicSpells') umgeleitet. In diesem Fall soll es also für die Karte selbst keine eigene Hilfe geben, sondern es soll die Zaubersprüche Hilfe angezeigt werden.
Sollte es sich später herausstellen, dass für die Karte doch eine eigene Hilfe notwendig ist, kann das (ohne Änderungen an der Extension) später jederzeit geändert werden und alle Kunden haben sofort Zugriff auf die geänderte/erweiterte Hilfe.
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Versionshinweise erstellen
Versionshinweise können über die _ReleaseNotes-Snippets hinzugefügt werden.
Bei Dateien mit dem Namen ReleaseNote fügt der Help Builder beim Anzeigen der Seite automatisch Versionsdetails zu den einzelnen Versionen hinzu. Versionsdetails werden nur hinzugefügt, wenn die Version in einem <h2> Tag nach dem Text Version durch ein Leerzeichen getrennt angegeben ist. Alternativ kann auch die AppID statt dem Text "Version" angegeben werden.
Beispiel:
Version 22.1.2.0
ab Business Central 22Wichtiges Update 2024/01/01
Die Versionsdetails werden in einer Datenbank auf navax.app hinterlegt. Weitere Details (Zugangsdaten usw.) müssen mit dem NAVAX App Team abgestimmt werden.
Sind für eine Version Downgrade-Versionen vorhanden, wird automatisch ein Hinweis hinzugefügt.
Beispiel:
Hinweis
Diese Version ist auch als Downgrade-Version für Business Central 22, 21 und 20 verfügbar.
Snippets
Folgende Snippets stehen zur Verfügung:
Snippet
Informationen/Ergebnis
_NewReleaseNotes
Erstellt ein Beispiel welches als Ausgangsbasis verwendet werden kann.
Hinweis
<releasenotestext>, <upcomingupdates>, <upcomingupdatestext>, <downgradeinfo> und <initialversion> werden automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Versionshinweise
Möchten Sie wissen, was sich in der Erweiterung geändert hat? Nachfolgend finden Sie eine Übersicht über die neuen Funktionen und Änderungen, die in den Updates vorgenommen wurden.
Version TODO
Ursprungsversion
_ReleaseNotesAdd
Fügt eine neue Version hinzu.
Hinweis
<improvements>, <modifications> und <corrections> werden automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Version TODO
Erweiterungen
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
Änderungen
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
Fehlerbehebungen
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
_ReleaseNotesAddUpcoming
Hinweis
<upcomingupdatestext> wird automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Kommende Updates
Bitte beachten Sie
Die Funktionen befinden sich in unterschiedlichen Stadien der Entwicklung. Sie sind nicht endgültig und können sich daher noch ändern. Diese Liste ist nicht erschöpfend und enthält nicht alles, was in Erwägung gezogen wird oder sich in der Entwicklung befindet.
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
_ReleaseNotesAddDowngradeInfo
Hinweis
<downgradeinfo> wird automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Downgrade-Informationen
TODO_Text
TODO_Text
TODO_Text
_ReleaseNotesAddImprovements
Hinweis
<improvements> wird automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Erweiterungen
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
_ReleaseNotesAddModifications
Hinweis
<modifications> wird automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Änderungen
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
_ReleaseNotesAddCorrections
Hinweis
<corrections> wird automatisch durch Text ersetzt und dem Benutzer auf Deutsch oder Englisch angezeigt.
Ergebnis:
Fehlerbehebungen
TODO_ListEntry
TODO_ListEntry
TODO_ListEntry
_ReleaseNotesAddRow
Ergebnis:
TODO_ListEntry
Docs / NAVAX Help Builder / Hilfe schreiben / Basics Rechtschreibprüfung
Für die Überprüfung der Rechtschreibung ist die Visual Studio Code Extension Code Spell Checker zu empfehlen.
Die benötigten Sprachen müssen in den Settings aktiviert werden.
Damit die Rechtschreibprüfung für alle Hilfethemadateien (Dateiendung .nchb) automatisch durchgeführt wird, öffnet/erstellt man zuerst eine Hilfethemadatei und klickt anschließend in der Status Bar auf Spell. Dadurch wird das Fenster Spell Checker Preferences geöffnet. Aktivieren Sie im Bereich Settings die Rechtschreibprüfung für alle nchb Dateien.
Unbekannte Wörter können zum Rechtschreibprüfungswörterbuch hinzugefügt werden.
Docs / NAVAX Help Builder / Hilfe schreiben / Hilfetext vorschlagen Hilfetext aus AL-Datei vorschlagen
Über das Suggest Help Text from AL File Command kann aus einem AL-Objekt (page, pageextension, report oder xmlport) ein Hilfethema generiert werden. Dabei wird auf Grundlage des Objekt-Aufbaus und den Tooltips ein Hilfetext vorgeschlagen, der dann als Ausgangsbasis für das Hilfethema verwendet werden kann.
Hinweis
Der Help Builder setzt voraus, dass die einzelnen Hilfedateien pro Sprache in einem Ordner (2 Zeichen, Kleinbuchstaben) zusammengefasst werden.
Suggest Help Text from AL File ermittelt den Hilfetext auf Basis des Ordners, in welchem sich die Hilfedatei befindet.
Im Ordner 'de' werden z.B. die Sprachlayer 'DEU', 'DEA' und 'DES' berücksichtigt, im Ordner 'fr' werden die Sprachlayer 'FRA', 'FRB', 'FRC' und 'FRS' berücksichtigt.
Wird kein entsprechender Sprachlayer in den Objekten gefunden, wird der Standard-Text (im Normalfall Englisch) der Captions und Tooltips vorgeschlagen.
Damit die Hilfetexte in der jeweiligen Sprache ermittelt werden können, müssen die Sprachlayer mit den übersetzten Texten als Comment in den AL-Objekten angegeben sein:
Die Angabe beginnt mit dem 3-Stelligen Sprachlayer-Code, gefolgt von einem =" Beispiel: DEU="
Danach wird der übersetzte Text angegeben. Weitere " Zeichen im Text sind erlaubt.
Am Ende wird der Text mit einem weiteren " abgeschlossen. Beispiel: DEU="Das ist ein besonders "sinnvoller" Text."
Werden mehrere Sprachlayer angegeben, werden diese mit einem Komma getrennt.
Beispiel:
Tipp
Die NAVAX Help Builder Extension stellt Snippets für AL bereit, welche die Angabe der zusätzlichen Sprachlayer als Comment in den AL-Objekten erleichtern.
Hilfetext vorschlagen
Erstellen Sie eine neue .nchb Datei oder öffnen sie eine vorhandene .nchb Datei.
Positionieren Sie den Curser im Editor an der Stelle, an der später der Text eingefügt werden soll.
Rufen Sie das Command NCHB: Suggest Help Text from AL File des Help Builders über Ctrl+Shift+P bzw. über F1 auf.
Wählen Sie die AL-Datei aus und klicken Sie auf Open damit der Hilfetext vorgeschlagen wird.
Hinweis
Bei den Feldern einer Page wird versucht, die Feld-Captions der SourceTable über die .xlf Dateien zu ermitteln.
Ausnahme: Wenn eine abweichende Caption in der Page angegeben ist.
Konnte keine Caption ermittelt werden, wird die Caption des Feldes mit TODO_ eingefügt und das Feld muss manuell überarbeitet werden.
Beispiel eines Vorschlags:
Update Translation Files (xliff, AL)
Mit diesem Command können die xliff Dateien im Translations-Ordner einer AL-Extension erstellt bzw. aktualisiert werden. Das Command ist vergleichbar mit dem Command AL: Generate Xliff files (AL Tools) der Extension AL Language Tools.
Hinweis
Die Verwendung der AL Language Tools Extension wird nicht empfohlen, da dort einige Fehler auftreten und die Formatierung nicht 100% der Microsoft-Formatierung entspricht.
Damit die xliff Dateien in der jeweiligen Sprache erstellt bzw. aktualisiert werden können, müssen die Sprachlayer mit den übersetzten Texten als Comment in den AL-Objekten angegeben sein.
Damit die aktuellen Sprachlayer auch in der Source-xliff Datei aktualisiert sind, muss vor dem Ausführen des Commands die AL Extension kompiliert werden Ctrl+Shift+B.
Wird das Command ausgeführt, werden Details zu den aktualisierten xliff Dateien im Panel unter OUTPUT in der Gruppe NCHB angezeigt:
Docs / NAVAX Help Builder / Hilfe schreiben / Hilfetext vorschlagen Ghostwriter
Mit dem NCHB Ghostwriter kann innerhalb kürzester Zeit ein Vorschlag für eine komplette Onlinehilfe oder für neu hinzugefügte AL-Objekte erstellt werden.
Für den Ghostwriter stehen 2 voneinander unabhängige Commands zur Verfügung: Check for missing Topics und Create missing Topics.
Das Verhalten des Ghostwriters kann in den Visual Studio Code Settings festgelegt werden.
Check for missing Topics
Dieses Command prüft, ob für alle AL-Objekte (page, pageextension, report oder xmlport) eines Ordners entsprechende nchb-Dateien in einem Hilfe-Ordner existieren.
Hier wird also nichts verändert oder angelegt.
Standardmäßig wird dabei im "src"-Ordner (und dessen Unterordner) der AL-Extension nach den AL-Objekten gesucht.
Ist kein "src"-Ordner vorhanden oder wenn in den Visual Studio Code Settings 'Ghostwriter: Manual Folder Selections AL' aktiviert ist, muss der Ordner manuell ausgewählt werden.
Für die Hilfedateien wird standardmäßig "help" als Ordner verwendet.
Ist kein "help"-Ordner vorhanden oder wenn in den Visual Studio Code Settings 'Ghostwriter: Manual Folder Selections Help' aktiviert ist, muss der Ordner manuell ausgewählt werden.
Hinweis
Damit die Commands des Ghostwriters Ergebnisse liefern, müssen im "help"-Ordner die Unterordner (2-Stellig, also z.B. 'de', 'en') für die gewünschten Sprachen angelegt sein.
Nachdem das Command ausgeführt wurde, wird das Ergebnis als modale Visual Studio Code Meldung angezeigt, welche auch mit Strg+C kopiert werden kann.
Zusätzlich wird das Ergebnis auch im Panel unter OUTPUT in der Gruppe NCHB angezeigt.
In diesem Beispiel wurde zuerst geprüft, ob Themen wie z.B. "Index", "Allgemein", "Arbeiten mit der App", usw. vorhanden sind. Ob und welche Themen hier berücksichtigt werden sollen ist in den Visual Studio Code Settings einstellbar.
Danach wurden 4 AL-Objekte gefunden, welche für die Hilfe relevant sein könnten. In allen Objekten ist eine ContextSensitiveHelpPage definiert, es wurden aber keine zugehörigen nchb-Dateien im Hilfe-Ordner gefunden.
Create missing Topics
Dieses Command erstellt für alle AL-Objekte eines Ordners entsprechende nchb-Dateien in einem Hilfe-Ordner falls diese dort noch nicht existieren. Es gelten dabei die selben Regeln und Einstellungen wie beim Command Check for missing Topics.
Hinweis
Auch hier gilt:
Damit die Commands des Ghostwriters Ergebnisse liefern, müssen im "help"-Ordner die Unterordner (2-Stellig, also z.B. 'de', 'en') für die gewünschten Sprachen angelegt sein. Das Command erstellt also nicht selbstständig Unterordner für die Sprachen.
Nachdem das Command ausgeführt wurde, wird das Ergebnis als modale Visual Studio Code Meldung (und zusätzlich im Panel unter OUTPUT in der Gruppe NCHB) angezeigt, welche auch mit Strg+C kopiert werden kann.
Was wird vorgeschlagen?
Ob und welche Themen zusätzlich zu den AL-Objekten berücksichtigt werden sollen ist in den Visual Studio Code Settings einstellbar.
Der Hilfetext für ein AL-Objekt wird genau so vorgeschlagen, wie es auch das Command Suggest Help Text from AL File vorschlagen würde. Ausnahme: Visual Studio Code Settings 'Ghostwriter: Only Todo And Path' ist aktiviert. In diesem Fall wird nur der Text 'TODO' gefolgt vom Pfad des AL-Objekts vorgeschlagen.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Hilfetext vorschlagen, Hilfetext aus AL-Datei vorschlagen.
Beispiel eines Vorschlags:
Visual Studio Code Settings
Das Verhalten des Ghostwriters und die vorzuschlagenden Themen können über diverse Parameter in den Visual Studio Code Settings (File > Preferences > Settings) im Bereich Extensions, NAVX Help Builder festgelegt werden.
Setting
Informationen
Manual Folder Selections AL
Gibt an, ob nach den AL-Objekten im "src"-Ordner (und dessen Unterordner) der AL-Extension gesucht werden soll, oder ob der Ordner manuell ausgewählt werden soll.
Manual Folder Selections Help
Gibt an, ob für die Hilfedateien "help" als Ordner verwendet werden soll, oder ob der Ordner manuell ausgewählt werden soll.
Only Todo And Path
Gibt an, ob der Hilfetext auf der Grundlage des Objekt-Aufbaus vorgeschlagen werden soll, oder ob nur der Text 'TODO' gefolgt vom AL-Dateipfad vorgeschlagen werden soll.
Suggest General
Gibt an, ob das Thema Allgemein (General.nchb) vorgeschlagen werden soll.
Diese Einstellung wirkt sich nicht auf den Inhaltsverzeichnis-Vorschlag aus.
Hier wird die description aus der app.json vorgeschlagen, gefolgt von einem Bereich für Navigation.
Danach wird ein Bereich für Berechtigungssätze vorgeschlagen. Sollten Berechtigungssätze als AL-Objekte vorhanden sein, werden diese hier berücksichtigt.
Ist 'Suggest Installation Notes' aktiviert, wird noch eine Themenverknüpfung auf die Installationshinweise hinzugefügt.
Suggest Index
Gibt an, ob das Thema Inhaltsverzeichnis (index.nchb) vorgeschlagen werden soll.
Hier wird, abhängig von den anderen Settings, ein Vorschlag für das Inhaltsverzeichnis vorgeschlagen.
Dabei werden verschiedene Bereiche wie z.B. 'Einrichtung', 'Aufgaben', 'Berichte und Analysen' uws. erstellt.
Am Ende des Vorschlags werden die aus den AL-Objekten vorgeschlagenen Themen im Bereich 'TODO' hinzugefügt.
Diese müssen dann manuell in die verschiedenen Bereiche verschoben werden.
Hinweis
Jedes mal, wenn über den Ghostwriter Themen aus AL-Objekten erstellt bzw. hinzugefügt werden, werden diese im Bereich 'TODO' am Ende des Inhaltsverzeichnisses hinzugefügt.
Suggest Index License Overview Link
Gibt an, ob beim Vorschlag des Inhaltsverzeichnisses eine Themenverknüpfung auf die NAVAX Lizenzverwaltung hinzugefügt werden soll.
Suggest Installation Notes
Gibt an, ob das Thema Installationshinweise (InstallationNotes.nchb) vorgeschlagen werden soll.
Diese Einstellung wirkt sich auch auf den Inhaltsverzeichnis-Vorschlag aus.
Hier werden die dependencies aus der app.json vorgeschlagen, gefolgt von einem Bereich für On-Premises.
Danach wird ein Bereich für Externe Adressen vorgeschlagen. Wird die NAVAX Extension Base als Dependency gefunden, werden die dafür notwendigen Informationen hinzugefügt.
Suggest Release Notes
Gibt an, ob das Thema Versionshinweise (ReleaseNotes.nchb) vorgeschlagen werden soll.
Diese Einstellung wirkt sich nicht auf den Inhaltsverzeichnis-Vorschlag aus.
Hier wird alles für eine Ursprungsversion vorgeschlagen. Die Versionsnr. wird aus der app.json vorgeschlagen.
Suggest Release Notes Build Overview Link
Gibt an, ob beim Vorschlag der Versionshinweise ein Link zur Build-Übersicht in DevOps hinzugefügt werden soll.
Suggest Working With The App
Gibt an, ob das Thema Arbeiten mit der App (WorkingWithTheApp.nchb) vorgeschlagen werden soll.
Diese Einstellung wirkt sich auch auf den Inhaltsverzeichnis-Vorschlag aus.
Hier wird nur der Topic Header gefolgt von dem Text 'TODO' vorgeschlagen.
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Hinweise
Hinweise können über die _Note-Snippets hinzugefügt werden.
Snippets
Folgende Snippets stehen zur Verfügung:
Snippet
Code/Ergebnis
_Note
<note>
TODO_NoteText
</note>
Ergebnis:
Hinweis
TODO_NoteText
_NoteTip
<tip>
TODO_TipText
</tip>
Ergebnis:
Tipp
TODO_TipText
_NoteImportant
<important>
TODO_ImportantText
</important>
Ergebnis:
Wichtig
TODO_ImportantText
_NoteCaution
<caution>
TODO_CautionText
</caution>
Ergebnis:
Achtung
TODO_CautionText
_NoteWarning
<warning>
TODO_WarningText
</warning>
Ergebnis:
Warnung
TODO_WarningText
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Listen
Punktelisten können über das Snippet _List hinzugefügt werden.
Nummerierte Listen können über das Snippet _ListNumbered bzw. durch die Angabe von <ol> statt <ul> erstellt werden.
Neue Listeneinträge können mit _ListAddEntry hinzugefügt werden.
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Tabellen
Tabellen können über die _Table-Snippets hinzugefügt werden.
Neue Zeilen können den Tabellen mit dem Zusatz AddRow (z.B.: _Table2AddRow) hinzugefügt werden.
Eine optionale Tabellenüberschrift und/oder ein optionaler Text kann mit _TableAddCaption hinzugefügt werden.
Hinweis
Tabellen haben grundsätzlich keine horizontale Scrollbar. Sollte eine Scrollbar erforderlich sein, kann diese durch Angabe von <tablescroller> Tags hinzugefügt werden:
<table>
<caption><h3>TODO_OptionalTableCaption</h3>
A checkmark ( <checkmark> ) in the <b>TODO_ColumnHeader</b> column indicates TODO.
Ein Häkchen ( <checkmark> ) in der Spalte <b>TODO_ColumnHeader</b> zeigt an, TODO.</caption>
<tr><th> </th><th class="mark">TODO_ColumnHeader</th><th> </th></tr>
<tr><td>TODO_Content1</td><td class="mark"><checkmark></td><td>TODO_Content2</td></tr>
<tr><td>TODO_Content1</td><td class="mark"><xmark></td><td>TODO_Content2</td></tr>
</table>
Ergebnis:
TODO_OptionalTableCaption
A checkmark ( ) in the TODO_ColumnHeader column indicates TODO.
Ein Häkchen ( ) in der Spalte TODO_ColumnHeader zeigt an, TODO.
TODO_ColumnHeader
TODO_Content1
TODO_Content2
TODO_Content1
-
TODO_Content2
_TableCheckmarkAddRow
<tr><td>TODO_Content1</td><td class="mark">TODO <checkmark> or <xmark></td><td>TODO_Content2</td></tr>
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Bilder
Bilder können über das Snippet _Image hinzugefügt werden.
<image "TODO_FileName.png?v=1.0">
Tipp
?v=1.0 nach der .png-Dateierweiterung:
Damit den Benutzern der Onlinehilfe nach einer Aktualisierung eines Bildes und dem anschließenden Hochladen nicht das alte Bild angezeigt wird, welches eventuell noch in deren Browser-Cache vorhanden ist, sollte der Wert bei einer Aktualisierung erhöht werden (z.B. auf v=1.1).
Damit die Bilder sprachbezogen angepasst werden können, sollten diese im selben Ordner wie die Hilfedatei gespeichert werden. Es wird empfohlen, für die Bilddatei den gleichen Namen wie für die Hilfedatei (gegebenenfalls mit fortlaufender Nummerierung oder zusätzlicher Bezeichnung) zu verwenden.
Empfohlene Anzeigeeinstellungen für Screenshots:
100% Skalierung und eine Auflösung von 1280x720 (AppSource-Vorgabe von Microsoft).
Tipp
Taskleiste und Favoritenleiste sollte man während der Erstellung von Screenshots ausblenden.
Browserfenster sollten maximiert sein (Standard Shortcut Key: F11).
Über das Snippet _ImageDarkMode können Bilder hinzugefügt werden, bei denen zusätzlich ein alternatives Bild für den Dark Mode des Browsers angegeben werden kann. Je nach Browsereinstellung wird entweder das normale Bild oder das Bild für den Dark Mode angezeigt.
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Animierte Bilder (GIF)
Werden animierte Bilder eingefügt (Dateiendung .gif) sind grundsätzlich die selben Dinge zu beachten wie für normale Bilder.
Animierte Bilder können über das Snippet _ImageAnimated hinzugefügt werden.
Statt der .png Datei ist die entsprechende .gif Datei anzugeben.
<image "TODO_AnimatedFileName.gif?v=1.0">
Ein empfehlenswertes Tool für die Erstellung von .gif Dateien ist z.B. ScreenToGif.
Weitere Informationen dazu finden Sie unter www.screentogif.com
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Videos
Videos können entweder indirekt über navax.app oder direkt (nicht empfohlen) verlinkt werden.
Beispiel indirekter Link:
Wenn das Video aktualisiert wird, oder wenn ein neueres Video auf youtube hochgeladen wird, muss der Link an allen Stellen aktualisiert werden.
Wird das Video im AL Code verlinkt (z.B. Assisted Setup) kann man den Link nur mit einem neuen Release verändern.
Um diese Probleme zu umgehen, sollten Videos stattdessen indirekt über navax.app mit einer sogenannten VideoID verlinkt werden.
Indirekte Videolinks können über die Snippets _Video16x9 (Format 16x9) und _Video4x3 (Format 4x3) hinzugefügt werden.
Der aktuelle Videolink ist dabei in einer Datenbank auf navax.app hinterlegt.
Zusätzlich ist dadurch sichergestellt, dass die Videos in der Anwendung (z.B. Assisted Setup) mit den Videos aus der Onlinehilfe übereinstimmen.
Weitere Details (Zugangsdaten usw.) müssen mit dem NAVAX App Team abgestimmt werden.
Tipp
Die VideoID kann ebenfalls im AL Code (z.B. im Assisted Setup) verwendet bzw. angegeben werden.
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Assisted Setup", 'OnRegister', '', true, true)]
local procedure NVXYZ_AssistedSetup_OnRegister()
var
AssistedSetup: Codeunit "Assisted Setup";
AssistedSetupGroup: Enum "Assisted Setup Group";
VideoCategory: Enum "Video Category";
AppInfo: ModuleInfo;
CurrentGlobalLanguage: Integer;
AssistantNameTxt: Label 'Abracadabra Setup', Comment = 'DEU="Abracadabra-Einrichtung"';
DescriptionTxt: Label 'Set up the general settings and defaults for Abracadabra.', Comment = 'DEU="Richten Sie die allgemeinen Einstellungen und Vorgaben für Abracadabra ein."'; LanguageTxt: Label 'en', Comment = 'DEU="de"';
LanguageTxt: Label 'en', Comment = 'DEU="de"';
begin
NavApp.GetCurrentModuleInfo(AppInfo);
CurrentGlobalLanguage := GlobalLanguage();
AssistedSetup.Add(
AppInfo.Id(),
Page::"NVXYZ Setup",
AssistantNameTxt,
AssistedSetupGroup::GettingStarted,
'https://www.navax.app/video.php?AppID=NVXYZ&VideoID=Setup&L=' + LanguageTxt,
VideoCategory::GettingStarted,
'https://www.navax.app/contextSensitiveHelpUrl.php?AppID=NVXYZ&ObjID=Setup&L=' + LanguageTxt,
DescriptionTxt);
GlobalLanguage(Language.GetDefaultApplicationLanguageId());
AssistedSetup.AddTranslation(Page::"NVXYZ Setup", Language.GetDefaultApplicationLanguageId(), AssistantNameTxt);
GlobalLanguage(CurrentGlobalLanguage);
end;
Snippets
Folgende Snippets stehen zur Verfügung:
Snippet
Code/Ergebnis
_Video16x9
<video16x9 "TODO_VideoID"></video16x9>
Ergebnis:
_Video4x3
<video4x3 "TODO_VideoID"></video4x3>
Ergebnis:
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Seitenumbrüche
Grundsätzlich wird beim Drucken der Hilfe bzw. bei der Erstellung eines PDFs für jedes Hilfethema ein Seitenumbruch eingefügt.
Wenn Seitenumbrüche innerhalb des Hilfethemas zur besseren Strukturierung benötigt werden, können diese über das Snippet _PageBreak hinzugefügt werden.
Snippets
Folgende Snippets stehen zur Verfügung:
Snippet
Code
_PageBreak
<pagebreak>
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Anzeige Bildschirm/Druck
Mit <span class="hideonprint"> bzw. <span class="hideonscreen"> können Elemente entweder nur am Bildschirm oder nur beim Drucken angezeigt werden.
Beispiel:
Docs / NAVAX Help Builder / Hilfe schreiben / Erweitert Quelltext
Quelltext kann über die _SourceCode-Snippets hinzugefügt werden.
Ein Syntax-Highlighter kann im <code>-Tag durch Angabe der Sprache mit class="language-xxx" aktiviert werden.
Der Highlighter ist für die folgenden Sprachen verfügbar:
Docs / NAVAX Help Builder / Hilfe hochladen Hilfe auf navax.app hochladen
Damit die Hilfe Online verfügbar ist, muss das Hilfeprojekt auf navax.app hochgeladen werden.
Weitere Details (Zugangsdaten usw.) müssen mit dem NAVAX App Team abgestimmt werden.
Docs / NAVAX Help Builder / Anhang Versionshinweise
Möchten Sie wissen, was sich in der Erweiterung geändert hat? Nachfolgend finden Sie eine Übersicht über die neuen Funktionen und Änderungen, die in den Updates vorgenommen wurden.
Die aktuellste Version kann hier heruntergeladen werden:
nchb-3.0.2.vsix
Version 3.0.2
2024/03/27
Fehlerbehebungen
In den Installationshinweisen wurde für die NCEX eine falsche Granule-ID vorgeschlagen.
Die Erweiterung NCHB Help Builder wurde umbenannt in NAVAX Help Builder.
Erweiterungen
Die Onlinehilfe wurde überarbeitet.
Version 2.0.8
2023/10/04
Änderungen
Da es beim Ausdruck der Versionshinweise immer wieder zu Darstellungsproblemen kam, wurden diese überarbeitet.
Die Versionshinweise ab jetzt in einer eigenen Struktur erstellt, die vom Help Builder bereitgestellt wird. Das alte Format ist weiterhin gültig, es wird jedoch empfohlen, ab jetzt das neue Format zu verwenden. Über das Command Convert old Release Notes können die alten Versionshinweise in das neue Format umgewandelt werden.
Die beiden Ghostwriter-Commands Check for missing Topics und Create missing Topics geben jetzt keine OK-Meldung mehr für bereits vorhandene Themen aus.
Das Command Suggest Help Text from AL File berücksichtigt jetzt auch das InstructionalText Property einer Group.
Für den Text Ursprungsversion wurde der Platzhalter <initialversion> hinzugefügt.
Die Links im index wurden vom Ghostwriter fälschlicherweise mit einer Dateiendung (.nchb) angelegt.
Version 2.0.7
2023/04/22
Erweiterungen
Der Onlinehilfe wurde eine Suche hinzugefügt.
Es ist jetzt möglich, Themenüberschriften und Themenverknüpfungen zu erstellen, bei denen der angezeigte Text durch das Inhaltsverzeichnis bestimmt wird. Wenn die Struktur oder die Anordnung und Gruppierung der Hilfethemen im Inhaltsverzeichnis später geändert wird, müssen die Themenüberschriften und Themenverknüpfungen nicht mehr zusätzlich geändert werden.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Indexgesteuerter Ansatz.
Tabellen können jetzt auch mit einer Häkchen-Spalte ( ) erstellt werden.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Erweitert, Tabellen.
Version 2.0.6
2023/03/23
Fehlerbehebungen
Die Texte für die Platzhalter <fields>, <factboxes>, <actions> und <options> wurden in der Vorschau nicht angezeigt.
Version 2.0.5
2023/03/16
Erweiterungen
Die Vorschau für Hinweise wurde verbessert.
Die Texte für die Platzhalter <installationnotestext>, <ncexupdateinfo> und <licupdateinfo> werden jetzt konvertiert und in der Vorschau angezeigt.
Die Berechtigungssätze werden vom Ghostwriter jetzt als Tabelle vorgeschlagen.
Version 2.0.3
2022/08/25
Änderungen
Stylesheet-Aktualisierung. Versionshinweise werden jetzt in der Vorschau ohne Tabellen-Rahmen angezeigt.
Version 2.0.2
2022/07/22
Erweiterungen
Über das Command Suggest Help Text from AL File kann jetzt ein Hilfetext für reportextensions vorgeschlagen werden.
Version 2.0.1
2022/07/14
Änderungen
Stylesheet-Aktualisierung.
Version 2.0.0
2022/07/06
Erweiterungen
Das Command Update Translation Files (xliff, AL) wurde hinzugefügt.
Mit diesem Command können die xliff Dateien im Translations-Ordner einer AL-Extension erstellt bzw. aktualisiert werden.
Das Command ist vergleichbar mit dem Command AL: Generate Xliff files (AL Tools) der Extension AL Language Tools.
Hinweis
Die Verwendung der AL Language Tools Extension wird nicht empfohlen, da dort einige Fehler auftreten und die Formatierung nicht 100% der Microsoft-Formatierung entspricht.
Das Suggest DE Help Text from AL File Command wurde entfernt.
Suggest Help Text from AL File ermittelt jetzt den Hilfetext auf Basis des Ordners, in welchem sich die Hilfedatei befindet.
Zusätzlich wurden Snippets für AL hinzugefügt, welche die Angabe der zusätzlichen Sprachlayer als Comment in den AL-Objekten erleichtern.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Hilfetext vorschlagen, Hilfetext aus AL-Datei vorschlagen.
Die Commands Check for missing Help Topics und Create missing Help Topics wurden komplett überarbeitet.
Beide Commands sind jetzt Teil des neu hinzugefügten NCHB Ghostwriters.
Mit dem NCHB Ghostwriter kann innerhalb kürzester Zeit ein Vorschlag für eine komplette Onlinehilfe oder für neu hinzugefügte AL-Objekte erstellt werden.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Hilfetext vorschlagen, Ghostwriter.
Das Preview DE Command wurde entfernt.
Preview zeigt jetzt eine Vorschau an, bei der die sprachabhängigen Texte abhängig vom Ordner auf Englisch oder auf Deutsch umgewandelt werden.
Beim Vorschlag der Feld-Captions aus den .xlf Dateien wurden die Captions unter gewissen Konstellationen nicht gefunden.
Version 1.1.1
2022/04/14
Erweiterungen
Es wurde ein neuer Hinweis "Achtung" hinzugefügt. Für den Hinweis steht auch ein Snippet zur Verfügung.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Erweitert, Hinweise.
Check for missing Help Topics
Prüft, ob für alle AL-Objekte eines ausgewählten Ordners eine entsprechende nchb-Datei in einem ausgewählten Hilfe-Ordner existieren.
Create missing Help Topics
Erstellt für alle AL-Objekte eines ausgewählten Ordners (Quelle) eine entsprechende nchb-Datei in einem ausgewählten Hilfeordner (Ziel) falls diese noch nicht vorhanden ist.
.nchb Dateien haben jetzt ein Icon. Das NCHB Icon Theme wurde entfernt.
Die Snippets für Bilder wurden geändert. Es wird jetzt ?v=1.0 nach der .png-Dateierweiterung hinzugefügt.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Erweitert, Bilder.
Der Vorschlag für das General Thema im Snippet _NewIndex wurde geändert.
Das mit NCHB 1.0.2 hinzugefügte <bcv> Tag wurde wieder entfernt und die Versionsdetails werden jetzt automatisch hinzugefügt.
Die Snippets für das Erstellen der Versionshinweise wurden überarbeitet.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Versionshinweise erstellen.
Version 1.0.5
2021/05/13
Erweiterungen
</more> und </moreexternal> fügen automatisch einen Punkt am Ende des Links hinzu.
Das kann jetzt durch die Verwendung von </more+> bzw. </moreexternal+> verhindert werden.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Themenverknüpfungen & Externe Links.
Mit dem <bcv> Tag kann jetzt in den Versionshinweisen die Business Central Version angegeben werden, ab welcher die Extension verfügbar ist.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Versionshinweise erstellen.
Version 1.0.1
2020/12/01
Erweiterungen
Snippet für Bilder hinzugefügt, bei denen zusätzlich ein alternatives Bild für den Dark Mode des Browsers angegeben werden kann.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Erweitert, Bilder.
NAVAX Help Builder
Beim Aufruf der Onlinehilfe (z.B. aus Business Central) wird das entsprechende Hilfethema zuerst im Ordner der angeforderten Sprache (Parameter L) gesucht.
Wenn keine Sprache im Aufruf angegeben ist, wird mit der im Browser eingestellten Sprachen gesucht.
Ist das Hilfethema in der Sprache nicht verfügbar, wird, falls vorhanden, in den Ordnern der anderen Sprachen gesucht.
Wird das Hilfethema auch hier nicht gefunden, wird das Inhaltsverzeichnis des Hilfeprojekts angezeigt.
Beispiel für den Aufruf https://www.navax.app/contextSensitiveHelpUrl.php?AppID=NVXYZ&L=de&ObjID=HelloWorld:
Jede Seite wird vom Help Builder vor der Anzeige aufbereitet. Dabei werden der Seite unter anderem auch Aktionen wie z.B. Feedback und Druck hinzugefügt.
Einstellungen wie die Feedback E-Mail-Adresse werden am Server vom NAVAX App Team für das Hilfeprojekt eingerichtet.
Darüber hinaus fügt der Help Builder dem Inhaltsverzeichnis automatisch eine Aktion für das Handbuch hinzu. Dies ermöglicht es dem Benutzer, die gesamte Hilfe auszudrucken oder als PDF zu speichern.
Für den Fall, dass das selbe Hilfethema aus verschiedenen Pages aufgerufen werden soll, sollten Themenumleitungen verwendet werden. Es ist zwar möglich, den selben Namen im ContextSensitiveHelpPage Property in allen Pages anzugeben, es wird aber nicht empfohlen.
Der Vorteil der Themenumleitungen besteht darin, dass diese erst am Server und somit unabhängig von der Extension aufgelöst werden. Sollte es sich später herausstellen, dass für die Pages doch verschiedene Hilfen notwendig sind, kann das (ohne Änderungen an der Extension) später jederzeit geändert werden und alle Kunden haben sofort Zugriff auf die geänderte/erweiterte Hilfe.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Basics, Themenumleitungen.
nchb-3.0.2.vsix
Die Installation wird in Visual Studio Code im Extension Bereich über die Aktion Install from VSIX durchgeführt.
Nach der Installation muss Visual Studio Code entweder neu gestartet, oder ein Reload Window durchgeführt werden.
Die Hilfe selbst sollte in Visual Studio Code geschrieben werden. Es ist zwar auch möglich die Hilfe mit einem anderen Tool zu schreiben, allerdings stehen dann keine unterstützenden Funktionen bereit.
Weitere Informationen dazu finden Sie unter Vorbereitungen, Visual Studio Code einrichten.
Jedes Hilfethema ist in einer eigenen Datei mit der Dateiendung .nchb gespeichert. Bei der Datei handelt es sich im Prinzip um eine ganz normale Textdatei.
Wichtig ist, dass die Datei als UTF-8 Datei (mit oder ohne BOM) angelegt wird, damit später Sonderzeichen richtig dargestellt werden. Die Standardcodierung von Visual Studio Code ist UTF-8 ohne BOM. In der Status Bar rechts unten sehen Sie die Bezeichnung UTF-8. Wenn nicht, klicken Sie darauf, um die Aktionsleiste zu öffnen, und wählen Sie Save with Encoding. Sie können nun eine neue Codierung für die Datei auswählen.
Über das Command NCHB: Preview des Help Builders kann das spätere Ergebnis des Hilfethemas direkt in Visual Studio Code angezeigt werden:
Hier wird die Hilfe der Zauberspruchkarte (ContextSensitiveHelpPage = 'MagicSpellCard') zur allgemeinen Hilfe der Zaubersprüche (ContextSensitiveHelpPage = 'MagicSpells') umgeleitet. In diesem Fall soll es also für die Karte selbst keine eigene Hilfe geben, sondern es soll die Zaubersprüche Hilfe angezeigt werden.
Sollte es sich später herausstellen, dass für die Karte doch eine eigene Hilfe notwendig ist, kann das (ohne Änderungen an der Extension) später jederzeit geändert werden und alle Kunden haben sofort Zugriff auf die geänderte/erweiterte Hilfe.
Die benötigten Sprachen müssen in den Settings aktiviert werden.
Damit die Rechtschreibprüfung für alle Hilfethemadateien (Dateiendung .nchb) automatisch durchgeführt wird, öffnet/erstellt man zuerst eine Hilfethemadatei und klickt anschließend in der Status Bar auf Spell. Dadurch wird das Fenster Spell Checker Preferences geöffnet. Aktivieren Sie im Bereich Settings die Rechtschreibprüfung für alle nchb Dateien.
Unbekannte Wörter können zum Rechtschreibprüfungswörterbuch hinzugefügt werden.
Zusätzlich wird das Ergebnis auch im Panel unter OUTPUT in der Gruppe NCHB angezeigt.
In diesem Beispiel wurde zuerst geprüft, ob Themen wie z.B. "Index", "Allgemein", "Arbeiten mit der App", usw. vorhanden sind. Ob und welche Themen hier berücksichtigt werden sollen ist in den Visual Studio Code Settings einstellbar.
Danach wurden 4 AL-Objekte gefunden, welche für die Hilfe relevant sein könnten. In allen Objekten ist eine ContextSensitiveHelpPage definiert, es wurden aber keine zugehörigen nchb-Dateien im Hilfe-Ordner gefunden.
Empfohlene Anzeigeeinstellungen für Screenshots:
100% Skalierung und eine Auflösung von 1280x720 (AppSource-Vorgabe von Microsoft).
) erstellt werden.
Weitere Informationen dazu finden Sie unter Hilfe schreiben, Erweitert, Tabellen.