Introduction.

HTML Help is a system which allows Unity Asset Store publishers to include HTML formatted documents with their assets and to have these displayed wihin the Unity Editor and thus provide the same quality of offline doumentation to their customers as they would via a website.

As well as displaying a HTML document the system also allows the publisher to provide direct links to, amongst others, the online documentation, the publishers website and the publishers support page.

The help system can be invoked via a Unity Editor menu option and/or an embedded help button. Context sensitive help is also possible.
The system is driven via a simpe XML file which can be created manually using the supplied template or via a Unity Editor window.



Creating a Help system.

To create a help system complete the following steps:-

1) Create your HTML document.

    Note: The default background colour for the HTML viewer is black so ensure you are setting a suitable background image or a light colour.
    For example within the <head> tag add the following
            
        <style>
            body {
                background-Color: rgb(220,220,220);
            }
        </style>
    

2) Copy your HTML document to your Unity project.

    Note: It is recomended to use the /Assets/MyAsset/Editor/Resources folder where MyAsset is the name of your asset.
For example /Assets/MyAsset/Editor/Resources/MyAssetHelp.html
If your document relies on additional files, for example images, these should be copied to a folder named the same as your document followed by '_files'
For example /Assets/MyAsset/Editor/Resources/MyAssetHelp_files
and then
/Assets/MyAsset/Editor/Resources/MyAssetHelp_files/image1.jpg
/Assets/MyAsset/Editor/Resources/MyAssetHelp_files/image2.jpg
Tip: The easiest was to do this is to open your document in a normal web browser and then use the 'Save Page As' function.

3) Create the XML file.

    Note: It is recomended to use the /Assets/MyAsset/Editor/Resources folder
For example /Assets/MyAsset/Editor/Resources/MyAssetHelp.xml
You may either create the xml file manually using the file /Assets/HtmlHelp/Editor/Template/Template.xml and replacing the details with your own
Or use the Editor window via the Tools->Make Help from the Unity Editor menu.
If you decide to use your own icons for the help toolbar copy these also to this folder.

4) Create the Menu Option.

    If you would like to add a Unity Editor menu option for your help document
Copy the file /Assets/HtmlHelp/Editor/Template/Template.cs to your asset and rename it
For example /Assets/MyAsset/Editor/Scripts/MyAssetHelp.cs
Note: The file should be in a folder called Editor or a sub folder thereof
Open the file in a text or C# editor
Change the namespace (line 5) to, for example, the name of your asset
Change the name of the XML file (line 12) to the name of the file created in step 3 above
Change the name of the menu item to be created (line 13) to, for example, Help/the name of your asset
If you wish the help document to be invoked via a button within one of your own Unity Editor scripts please refer to the section Creating a Help Button below.

5) Copy the runtime help system to your asset.

    Copy the files
/Assets/HtmlHelp/Editor/Runtime/ShowHtml.unitypackage
/Assets/HtmlHelp/Editor/Runtime/ShowHtml Install.txt (or include the contents in your own installation/read me documentation)
To, for example
/Assets/MyAsset/Editor/Resources

5) Publish your asset.

Make HTML

Make Html is a Unity Editor window to make the creation of a help XML file easy.
To start the program use the Tools->Make Html menu option



The window is split up into 6 sections

    XML File
Settings
Options
Toolbar
Icons
Preview

XML File Enter the folder and name of an XML file and press Load to read an existing XML file. If you press load without entering a folder and name you will be prompted to select a file.
Pressing Save will save the file using the current folder and name. Pressing Save As will promt you to select a folder and name.
Settings Press Clear to remove all settings. Press Defaults to restore the default values.
Local HTML File Enter the name and extension of the local HTML help document. This is the only required entry. Press Browse to select a file.
Minimum Width The minimum width of the help window. Default 700 pixels.
Minimum Height The minimum heigth of the help window. Default 600 pixels.
Resizable If the help window should be resizable select, otherwise deselect. Default selected.
Options Press Clear to remove all options.
Asset Name The name of your asset. This will be the help window title if no Asset Title is specified. Also used in the toolbar tooltips.
Asset Title The help window title
Publishers Name Your (company) name. This is used in the toolbar tooltip.
Copyright If specified this will appear at the bottom of the help window
Toolbar Press Clear to remove all toolbar entries. If all Toolbar entries are left blank no toolbar will be displayed in the help window
The icons will appear on the toolbar in the order in which they are listed in the XML file. To change the icon sequence edit the XML file into the order required.
Navigation If specified navigation entries are presented as a drop down on the toolbar. These can be used to jump to tags with id's within the HTML document.
Press Clear to remove all navigation entries.
Pressing Generate will read the Local HTML document and populate the entries with every tag with an id attribute found. The descriptions can then be edited to be meaningful in the dropdown.
The TAG id and a description may also be added manually.
To remove a id TAG set it to blank
Online Documentation URL Enter the URL of the corresponding online documentation
Tutorial URL Enter the URL of a tutorial, for example a YouTube video.
Publishers Website URL Enter the URL of your website
Support URL Enter the URL for your support website
Support Email Enter the email address of your customer support.
Warning: The email function uses the mailto: protocol and requires the end user to have a local email client installed on their system. Windows 7 systems with no email client installed can cause problems if this toolbar option is used.
Show Refresh button Select this to display a refresh button on the toolbar.
Icons The html help system comes with a default set of icons for displaying on the toolbar. If you are not using the toolbar clear the icons
Each icon refers back to one item on the toolbar options described above.
Press Clear to remove the icons. If no icons are defined and a Toolbar option is used the default icon will be displayed.
Press Defaults to restore the default values.
To replace an icon press Change next to the icon to replace and then select the new icon. Icons should be .png or .jpg files with a width and height of 40 pixels. Please make sure to use a unique id so as not to case conflicts with otther users.
Icons should reside in a Resources folder
Note: I am not a graphics designer so if someone can come up with a better set of default icons and would be happy to share them please get in touch with me.
Preview Before saving your XML file you may see how your help subsystem will display to your customers. Press Preview to open your help window. You can then make sure all options selected work as required.

XML File layout.
As stated above you may manually create the required XML file using Template.xml.
The xml file shown below was generated via Make Html screen shot above:



Creating a Help Button

As well as being able to create a Unity Editor menu item, using TTemplate.cs as a guide you can also integrate the help system directly into your own Unity Editor Scripts. See Example1.cs and Example2.cs for complete details

The following code will produce a help button.

    
        if (GUILayout.Button("Help", GUILayout.Width(60)))
        {
            SSSoftWare.ShowHtml html = CreateInstance<SSSoftWare.ShowHtml>();
            html.ShowHelp("myasset.xml"); // Name of your XML definition file
        }
    
Which when pressed will invoke the help system defined in myasset.xml


The help system can also be used to create context sensitive help by using the id of tags within your html document
The following code creates a graphic context sensitive help button for a Unity Editor Text Field
    
        string xmlIn=string.Empty;
        GUIStyle styleNone = new GUIStyle();
        styleNone.border = new RectOffset(0, 0, 0, 0);
        ...
        ...
        EditorGUILayout.BeginHorizontal();
        EditorGUILayout.LabelField("File Name", GUILayout.Width(110));
        xmlIn = EditorGUILayout.TextField(xmlIn, GUILayout.Width(110));
        Rect r = GUILayoutUtility.GetLastRect();
        r.x += r.width+4;
        r.y -= 2;
        r.width = 22;
        r.height = 22;
        if (GUI.Button(r, new GUIContent(Resources.Load("Support") as Texture2D, "Help"),styleNone))
        {
            SSSoftWare.ShowHtml html = CreateInstance<SSSoftWare.ShowHtml>();
            html.ShowHelp("example2.xml", "tag2"); // Name of your XML definition file and tag id
        }
        EditorGUILayout.EndHorizontal();
    
This displays a button using the default support icon which when pressed will open the html document and position it at the tag with id 'tag2'.
See example2.cs, example2.xml and example2.html for full details

Package Contents

    /Assets/HtmlHelp/Editor
        /Plugins
        `   htmlhelp.dll            -   HTML help code
        /Resources
            /htmlhelp_files         -   This help files
                prettify.css
                ScreenShot001.png
                ScreenShot002.png
                ScreenShot003.png
            htmlhelp.html           -   This help document
            htmlhelp.xml            -   This help xml file
            Navigation.png          -   Default Navigation icon
            Email.png               -   Default Email icon
            Online.png              -   Default Online Help icon
            Publisher.png           -   Default Publisher icon
            Refresh.png             -   Default Refresh icon
            Support.png             -   Default Support icon
            Tutorial.png            -   Default Tutorial icon
        /Example
            example1.html       -   Example html document
            example1.xml        -   Example xml file
            example1.cs         -   Example code file. A help button
            example2.html       -   Example html document
            example2.xml        -   Example xml file
            example2.cs         -   Example code file. Context sensitive help
        /Runtime
            showhtml.unitypackage   -   Runtime distribution package
            showhtml install.txt    -   Runtime distribution documentation
        /Template
            Template.html           -   Template html document
            Template.xml            -   Template xml file
            Template.cs             -   Template code file. Help menu option

Building your own help system

If you wish to build your own help system and to incorporate it into your own software please contact me at https://stevesmith.software and I will send you the complete source code of the sytem.
The source code is for your internal use only and should not be released as a part of your work. Distribution of derived works may only be done in the form of a dll.

Copyright and Attribution

All code and images are copyright SteveSmith.Software 2018. All Rights Reserved.
The Help Icon used in the Unity Asset Store key images copyright Darth Stabro used under the Creative Commons Attribution 3.0 Unported license.