Inserting HTML code objects

The BTN_Insert_HTML Insert HTML Code Object tool in Write > Insert Object allows you to add special features or formatting to your topic pages with HTML code. For example, you can write dynamic HTML code with JavaScript to add features not available directly in Help+Manual.

This function "injects" HTML code into your topic at the point where you insert it. The code is entirely your responsibility and is not checked or parsed by Help+Manual in any way, so you need to be familiar with HTML coding.

Productivity Tip

You can resize the HTML code objects in your topics to make their contents visible. You can also the code object editor for editing larger blocks of code.

Use snippets to insert formatted HTML and Markdown

If you want to add formatted HTML and Markdown content to your content it is better to use the Snippets tool instead of the HTML Code Object tool. The Snippets tool now supports formatted HTML, Markdown and PDF files as well as Help+Manual topics and XML snippets, and can also include any referenced image files. Unlike code objects, HTML and Markdown snippets are converted automatically and can be exported to all output formats supported by Help+Manual.

Where HTML code objects are supported

HTML code objects are supported in all HTML-based output formats. This includes the eWriter Help format, which supports scripting in the same way as WebHelp. You will only find restrictions there in some cases because of the fact that eWriter is a local format like CHM, not a server-based format on the Internet like WebHelp.

The ePUB eBooks standard includes scripting but most ePUB readers do not so it should be avoided as it will hardly ever work,

If you want to use this feature in projects that will also be published to formats where it is not supported you need to use Help+Manual's conditional output features to create alternative text for those versions.

Note that the Insert HTML Code Object tool inserts the code directly in the body of your topic. If you want to insert scripts in the <head> section of your topic page you must do so in the HTML template, either directly or by reference. See below for more information on this.

How to insert plain HTML code in a topic

1.Click in the editor at the point where you want to insert the plain HTML code and select the BTN_Insert_HTML HTML Code Object tool in Write > Insert Object.

2.Then select the Static HTML Code option and enter and edit your code in the HTML Code: box, which includes syntax highlighting for HTML,

Insert inline code without block tags:
Normally, the HTML code block is inserted in a standard <p> paragraph or <div> layer tag. You can prevent this by activating the HTML code must not be enclosed in a block tag option.

3.You can resize the window for easier editing by dragging on the lower right corner.

The Load from File and Save to File functions allow you to save blocks of code in external text files for reuse.

Referencing external files in plain HTML code

If you reference external files in your plain HTML code you are entirely responsible for making sure that the files are included in your output. Help+Manual does not parse or check the code and it will not do this for you. There are two ways to make sure that referenced files are included in your project:

Method 1: Adding the files to the Baggage Files

This is the simplest solution. The Baggage Files function provides a quick and easy way to integrate external files in your project and make sure that they are available to the compiler and included in your output.

•See Using Baggage Files for details on using this function.

•See Graphics references for more details on referencing graphics files. Since graphics files are often large it is not always a good idea to add them to the Baggage.

Method 2: Integrating the files in your output manually

This is not really necessary since it is much easier to add any referenced files to your Baggage. The following instructions are just included for the sake of completeness.

•In WebHelp you must manually copy the files to your output directory if you have not added them to the Baggage Files (see above).

•In HTML Help you need to tell the HTML Help compiler to add the files to the .chm file. Proceed as follows:

1.Copy the external file(s) to your project folder (the folder containing your .hmxz or .hmxp project file).

2.In the Project Explorer open Configuration > Publishing Options > HTML Help > Extended HHP Settings.

3.In the editing box add the following entries, replacing the dummy filenames in the examples with your own files (one file per line):

[FILES]
..\donald.js
..\mickey.asp

Don't add a second [FILES] header if one already exists. Enter each external filename on its own line below the [FILES] header and precede it with the ..\ relative path reference.

This example assumes the files are stored in your project directory. (This is necessary because the project is published from a temporary subdirectory in the project directory, so files in the project directory are one level up.) If your files are located anywhere else you need to adjust the ..\ relative path reference accordingly.

Inserting external and online HTML files with a code object

In addition to HTML code and JavaScript, you can also use a code object to merge an entire external HTML file into your page. Here too, this will only work in HTML-based output formats. It will be ignored in other formats. The raw HTML is inserted in the page without conversion and that only works in HTML pages.

How and when the files are inserted

The files are not dynamic content. They are inserted in the HTML of your output pages when the project is compiled and they then become static content and part of the output.

Format of the files to insert

Note that the #MERGE command will insert the entire HTML file. It is thus better to only use files that contain plain HTML code, without any <html>, <head> or <body> structural components. See this topic for more details.

Inserting local files

Select the Merge Content of File option and then navigate to the file with the [..] browse button. The #MERGE command will be generated and inserted automatically. You can also enter the path and file name manually, if you wish. If you use a relative path it must be relative to the folder containing your project. (You can also reference online files here if you enter the http URL manually.)

Activating the option to prevent the HTML code from being inserted in a block tag is recommended.

Inserting online files

You can also insert online files with the Merge Web Content option. Note that this will not work for all files, particularly complex files with many containers or dynamic content. Here too, the files should ideally contain only plain HTML code, without <html>, <head> or <body> sections.

Referencing code in the <head> section

If you reference JavaScript or other script code in your HTML code objects you may want to insert scripts containing the functions to be executed in the <head> section of your HTML topic page that you then reference and run from the code objects inserted in the body of your topics. You can't do this directly in the topic page because this only inserts the code between the <body> and </body> tags in the final HTML page.

The code for the sections of your HTML pages above and below the <body> and </body> tags is provided by your HTML topic page templates, which you can access and edit in the Project Explorer. You can add script code and references to external script files to the <head> section of your pages by editing these templates. By default you have one HTML topic page template called Default, which is used for all topics. However, you can create as many different templates as you like and assign them to individual topics in the Topic Options tab on the left of the main editor window.

In addition to this you can use HTML variables that you can redefine in individual topics to add different script and code to the <head> section of every single topic. To do this you insert the variables in your template and then redefine their content for individual topics in the Topic Options tab on the left of the main editor window.

See Using HTML Templates for general information on how to access and edit your HTML topic page templates. See The power of editable variables for details on how to use HTML variables to insert individual code in your templates on a per-topic basis.

Please enable JavaScript to view this site.

Use snippets to insert formatted HTML and Markdown

Method 1: Adding the files to the Baggage Files

Method 2: Integrating the files in your output manually