Skip to main content

Extending CODESYS Offline Help with Your Own Contents

The CODESYS Development System provides the capability of expanding the Offline Help with your own help pages. The new help pages can be added in any structure and at any position in the table of contents.

In addition, it is possible to display the entire table of contents on the added help pages. Toggling the languages and searching the contents are also supported.

Important

The requirement for the integration of HTML pages is the installation of the CODESYS Offline Help. The CODESYS Offline Help can be installed via the help portal or CODESYS Installer.

. The following files are required for the extension

  • Help pages in HTML format

    The help pages are stored in the directory C:\ProgramData\CODESYS\Offline Help\<language>.

  • Configuration file: <name>-productinfo.json for the overview of the product help

    The configuration file is stored in the directory C:\ProgramData\CODESYS\Offline Help\de\js.

  • Configuration file: <name>-toc.json for the insertion position of the new pages

    The configuration file is stored in the directory C:\ProgramData\CODESYS\Offline Help\de\js.

  • Configuration file: <name>-search.json for including the new contents into the search

    The configuration file is stored in the directory C:\ProgramData\CODESYS\Offline Help\de\js.

    This file is optional.

Important

The <name> prefix of the three configuration files must be identical.

The files fuzzydata.js, productsinfo.js, and toc.js are the standard configuration files for Offline Help. After starting CODESYS, the contents from the json files are integrated into the standard configuration files (*.js). The original configuration files are saved in the backup directory.

_cds_img_offlinehelp_files.png

Creating the configuration files

Configuration file for the product help overview <name>-productinfo.json

This file creates entries on the overview page of the product help.

_cds_img_3rd_party_help_overview.png

title

Displayed name of the product with version

url

Linked page

children

No significance; not evaluated

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


Configuration file for the insertion position of the new help pages <name>-toc.json

This file defines the position where the new pages are integrated into the help.

url

HTML name of the page to be inserted

text

Name of the page to be inserted. This name is displayed in the table of contents

insert_after

Inserts a new page on the same level as the specified help page

append_below

Inserts a new page as the last child page below the specified help page.

If the / character is assigned instead of the HTML name, the new page is added toplevel at the end of the table of contents.

children

Adds additional child pages

Placeholder: *

The start pages of the products have an internal ID in their HTML name, which can change. To make sure that these pages can also be found after a change, the placeholder * should be used for the ID in these cases.

Example 2. Example 1

The help page 3rd_new_pub.html is inserted as a sibling page after the help page 1064796-311627-codesys-redundancy.html.

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


Example 3. Example 2

In addition to Example 1, two child pages are inserted below the New Publication page.

[
    {   "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"
    }
]


Example 4. Example 3

The start pages of the products have an internal ID in their HTML name, which can change. To make sure that these pages can also be found after a change, the placeholder * should be used for the ID in these cases.

Analogous to Example 2, but a placeholder is used for the Insert_after page.

[
    {   "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"
    }
]


Example 5. Example 4

The help page 3rd_new_pub.html and two subpages are inserted as the last child page below the help page *-codesys-softmotion.html.

[
    {   "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"
    }
]


Example 6. Example 5

This configuration adds the help page 3rd_toplevel.html toplevel at the end of the table of contents.

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


Example 7. Example 6

This example shows a configuration with different insertion positions.

[
    {
        "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": "/"
    }
]


Configuration file for the search <name>-search.json

This configuration contains the complete help text for a page.

title

Title of the chapter; displayed as the search hit

url

HTML name of the page found

breadcrumbs

Breadcrumbs of the page found. Displayed in the search hit

snippet

Short text the page found. Displayed in the search hit

body

Full text of the help page including the heading

[
  {
    "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"
  }
]

Customizing the HTML pages

The additional help pages must be in HTML format. To make sure that the table of contents, the language toggling, and the search field are also displayed on the newly added pages, the new pages must be embedded in an HTML frame.

The template file TemplateOfflineHelp_Simple.html can be found in the subdirectory C:\ProgramData\CODESYS\Offline Help\Templates after installing the Offline Help. This template is used as a framework for additional HTML pages.

The following modifications are necessary:

  • Insertion of the name of the tab in the browser in the placeholder {{TITLE}}. This is usually the heading of the help page.

        <title>{{TITLE}}</title>

  • Insertion of the entire contents of the additional help page in the placeholder {{CONTENT}}.

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

If the new pages are supposed to have the design of the CODESYS Help, then the stylesheet classes of the existing CODESYS Offline Help must be used. The template TemplateOfflineHelp_Full.html shows an example of these modifications.

Installing the help pages via a package

A package is usually used to extend the Offline Help.

Example 8. Example: Storing the data in the package
_cds_img_3rd_party_help_package.png

Sample entry in the package.manifest file

<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>


: