CODESYS-Offlinehilfe mit eigenen Inhalten erweitern

Das CODESYS Development System bietet die Möglichkeit, die Offlinehilfe mit eigenen Hilfeseiten zu erweitern. Die neuen Hilfeseiten können in einer beliebigen Struktur und an einer beliebigen Stelle im Inhaltsverzeichnis hinzugefügt werden.

Es ist weiterhin möglich, das gesamte Inhaltsverzeichnis auf den hinzugefügten Hilfeseiten anzuzeigen. Eine Sprachumschaltung sowie eine Suche nach Inhalten wird ebenfalls unterstützt.

Wichtig

Voraussetzung für das Einbinden von HTML-Seiten ist die Installation der CODESYS-Offlinehilfe. Die CODESYS-Offlinehilfe kann über das Hilfeportal oder den CODESYS Installer installiert werden.

. Folgende Dateien sind für die Erweiterung notwendig

Hilfeseiten im HTML-Format
Die Hilfeseiten werden im Verzeichnis C:\ProgramData\CODESYS\Offline Help\<language> abgelegt.
Konfigurationsdatei <name>-productinfo.json für die Übersicht der Produkthilfen
Die Konfigurationsdatei wird im Verzeichnis C:\ProgramData\CODESYS\Offline Help\de\js abgelegt.
Konfigurationsdatei <name>-toc.json für die Einfügeposition der neuen Seiten
Die Konfigurationsdatei wird im Verzeichnis C:\ProgramData\CODESYS\Offline Help\de\js abgelegt.
Konfigurationsdatei <name>-search.json für das Einbinden der neuen Inhalte in die Suche
Die Konfigurationsdatei wird im Verzeichnis C:\ProgramData\CODESYS\Offline Help\de\js abgelegt.
Diese Datei ist optional.

Wichtig

Das Präfix <name> der drei Konfigurationsdateien muss identisch sein.

Die Dateien fuzzydata.js, productsinfo.js und toc.js sind die Standard-Konfigurationsdateien der Offlinehilfe. Nach dem Starten von CODESYS werden die Inhalte aus den json-Dateien in die Standard-Konfigurationsdateien (*.js) integriert. Die originalen Konfigurationsdateien werden in das Verzeichnis backup gesichert.

Erstellen der Konfigurationsdateien

Konfigurationsdatei für die Übersicht der Produkthilfen `<name>-productinfo.json`

Diese Datei erzeugt Einträge auf der Übersichtsseite der Produkthilfen

`title`	Angezeigter Name des Produkts mit Version
`url`	Verlinkte Seite
`children`	Keine Bedeutung, wird nicht ausgewertet

Beispiel 1. Beispiel

[
  {
      "title": "3rd Party, V1.2.3.4",
      "url": "3rd_new_pub.html",
      "children": []
    }
]

Konfigurationsdatei für die Einfügeposition der neuen Hilfeseiten `<name>-toc.json`

In dieser Datei wird definiert, an welcher Position die neuen Seiten in die Hilfe eingebunden werden.

`url`	HTML-Name der Seite, die eingefügt wird
`text`	Name der Seite, die eingefügt wird. Dieser Name wird im Inhaltsverzeichnis angezeigt
`insert_after`	Fügt eine neues Seite auf der gleichen Ebene wie die angegebene Hilfeseite ein
`append_below`	Fügt eine neue Seite als letzte Kindseite unterhalb der angegebenen Hilfeseite ein. Wenn anstelle des HTML-Namens das Zeichen `/` zugewiesen wird, dann wird die neue Seite toplevel am Ende des Inhaltverzeichnisses hinzugefügt.
`children`	Fügt zusätzlich Kinderseiten ein
Platzhalter `*`	Die Startseiten der Produkte haben in ihrem HTML-Namen eine interne ID, die sich ändern kann. Damit diese Seiten auch nach einer Änderung gefunden werden, sollte in diesen Fällen für die ID der Platzhalter `*` eingesetzt werden.

Beispiel 2. Beispiel 1

Die Hilfeseite 3rd_new_pub.html wird als Geschwisterseite nach der Hilfeseite 1064796-311627-codesys-redundancy.html eingefügt.

[
    {   "url": "3rd_new_pub.html",
        "text": "New Publication",
        "insert_after": "1064796-311627-codesys-redundancy.html"
    }
]

Beispiel 3. Beispiel 2

Zusätzlich zu Beispiel 1 werden zwei Kindseiten unterhalb der Seite New Publication eingefügt.

[
    {   "url": "3rd_new_pub.html",
        "text": "New Publication",
        "children": [
            {
                "url": "3rd_new_pub_topic1.html",
                "text": "New Publication - Chapter 1"
            },
            {
                "url": "3rd_new_pub_topic2.html",
                "text": "New Publication - Chapter 2"
            }
        ],
        "insert_after": "1064796-311627-codesys-redundancy.html"
    }
]

Beispiel 4. Beispiel 3

Die Startseiten der Produkte haben in ihrem HTML-Namen eine interne ID, die sich ändern kann. Damit diese Seiten auch nach einer Änderung gefunden werden, sollte in diesen Fällen für die ID der Platzhalter * eingesetzt werden.

Analog zu Beispiel 2, jedoch wird für die Seite Insert_after ein Platzhalter eingesetzt.

[
    {   "url": "3rd_new_pub.html",
        "text": "New Publication",
        "children": [
            {
                "url": "3rd_new_pub_topic1.html",
                "text": "New Publication - Chapter 1"
            },
            {
                "url": "3rd_new_pub_topic2.html",
                "text": "New Publication - Chapter 2"
            }
        ],
        "insert_after": "*-codesys-redundancy.html"
    }
]

Beispiel 5. Beispiel 4

Die Hilfeseite 3rd_new_pub.html mit zwei Unterseiten wird als letzte Kindseite unterhalb der Hilfeseite *-codesys-softmotion.html eingefügt.

[
    {   "url": "3rd_new_pub.html",
        "text": "New Publication",
        "children": [
            {
                "url": "3rd_new_pub_topic1.html",
                "text": "New Publication - Chapter 1"
            },
            {
                "url": "3rd_new_pub_topic2.html",
                "text": "New Publication - Chapter 2"
            }
        ],
        "append_below": "*-codesys-softmotion.html"
    }
]

Beispiel 6. Beispiel 5

Diese Konfiguration fügt die Hilfeseite 3rd_toplevel.html toplevel am Ende des Inhaltverzeichnisses hinzu.

[
    {
        "url": "3rd_toplevel.html",
        "text": "Kapitel Toplevel",
        "append_below": "/"
    }
]

Beispiel 7. Beispiel 6

Dieses Beispiel zeigt eine Konfiguration mit verschiedenen Einfügepositionen

[
    {
        "url": "3rd_new_pub.html"
,        "text": "New Publication",
        "children": [
            {
                "url": "3rd_new_pub_topic1.html",
                "text": "New Publication - Chapter 1"
            },
            {
                "url": "3rd_new_pub_topic2.html",
                "text": "New Publication - Chapter 2"
            }
        ],
        "insert_after": "*-codesys-git.html"
    },
    {
        "url": "3rd_add_child.html",
        "text": "Kapitel Geschwister",
        "insert_after": "_pbdp_cmd_scan_devices.html"
    },
    {
        "url": "3rd_toplevel.html",
        "text": "Chapter Toplevel",
        "append_below": "/"
    }
]

Konfigurationsdatei für die Suche `<name>-search.json`

Diese Konfiguration beinhaltet den vollständigen Hilfetext einer Seite.

`title`	Titel des Kapitels, wird als Suchtreffer angezeigt
`url`	HTML-Name der gefundenen Seite
`breadcrumbs`	Breadcrumb der gefundenen Seite. Wird im Suchtreffer angezeigt
`snippet`	Kurzer Inhaltstext der gefundenen Seite. Wird im Suchtreffer angezeigt
`body`	Vollständiger Text der Hilfeseite inklusive der Überschrift

[
  {
    "title": "Chapter 1,
    "url": "3rd_chapter1.html",
    "breadcrumbs": "3rdParty - Offline help / Chapter 1",
    "snippet": "Lorem ipsum dolor sit amet...",
    "body": "Chapter 1. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
    sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam 
    erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. 
    Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor 
    sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam 
    nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam 
    voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita 
    kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet"
  },
  {
    "title": "Chapter 2",
    "url": "3rd_chapter2.html",
    "breadcrumbs": "3rdParty - Offline help / Chapter 2",
    "snippet": "Lorem ipsum dolor sit amet...",
    "body": "Chapter 2. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
    sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam 
    erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. 
    Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor 
    sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam 
    nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam 
    voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita 
    kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet"
  }
]

Anpassen der HTML-Seiten

Die zusätzlichen Hilfeseiten müssen das Format HTML haben. Damit das Inhaltsverzeichnis, die Sprachumschaltung und das Suchfeld auch auf den neu hinzugefügten Seiten angezeigt wird, müssen die neuen Seiten in einen "HTML-Rahmen" eingebettet werden.

Die Vorlagedatei TemplateOfflineHelp_Simple.html ist nach der Installation der Offlinehilfe im Unterverzeichnis C:\ProgramData\CODESYS\Offline Help\Templates zu finden. Diese Vorlage dient als Rahmen für zusätzliche HTML-Seiten.

Folgende Anpassungen sind notwendig:

Einfügen des Namens der Registerkarte im Browser im Platzhalter {{TITLE}}. Dies ist üblicherweise die Überschrift der Hilfeseite
```
    <title>{{TITLE}}</title>                      
```

Einfügen des gesamten Inhalts der zusätzlichen Hilfeseite im Platzhalter {{CONTENT}}.

<!-- Place main content here -->
{{CONTENT}}

Wenn die neuen Seiten das Design der CODESYS-Hilfe erhalten sollen, müssen die Stylesheet-Klassen der bestehenden CODESYS-Offlinehilfe verwendet werden. Die Vorlage TemplateOfflineHelp_Full.html zeigt exemplarisch diese Anpassungen.

Installation der Hilfeseiten über ein Package

Üblicherweise wird eine Erweiterung der Offlinehilfe über ein Package durchgeführt.

Beispiel 8. Beispiel: Ablage der Daten im Package

Beispieleintrag in der Datei package.manifest

<Component>
    <General>
        <Id>1</Id>
        <Name>Offline Help Files</Name>
        <Description>Offline help files for 3rd party product</Description>
        <Selectable>false</Selectable>
        <SelectedByDefault>true</SelectedByDefault>
    </General>
    <Items>
        <Folder>
        <TargetFolder>%REPOSITORY_LOCATION%</TargetFolder>
        <Path>Offline Help</Path>
        </Folder>
    </Items>
</Component>

In diesem Abschnitt:

CODESYS-Offlinehilfe mit eigenen Inhalten erweitern

Wichtig

Wichtig

Erstellen der Konfigurationsdateien

Konfigurationsdatei für die Übersicht der Produkthilfen <name>-productinfo.json

Konfigurationsdatei für die Einfügeposition der neuen Hilfeseiten <name>-toc.json

Konfigurationsdatei für die Suche <name>-search.json

Anpassen der HTML-Seiten

Installation der Hilfeseiten über ein Package

Suchresultat

Konfigurationsdatei für die Übersicht der Produkthilfen `<name>-productinfo.json`

Konfigurationsdatei für die Einfügeposition der neuen Hilfeseiten `<name>-toc.json`

Konfigurationsdatei für die Suche `<name>-search.json`