Merging HTML files into topics

Products
Support
Company
Free Trial
News
Contact
Buy Now

Zoom Window Out
Larger Text | Smaller Text
Hide Page Header
Show Expanding Text
Printable Version
Save Permalink URL

Navigation: Basic Working Procedures > Importing Data

In addition to importing HTML and text files you can also use a command that enables you to merge external HTML files into existing topics at publish time with the HTML Code Object tool. The files can be local or read from a location on the Internet with a URL. This can be very useful if you have material that changes frequently. You can maintain it in an external HTML file and automatically merge the latest version into your project when you publish.

Key Information

This only works in HTML-based output formats. Merged HTML files are not included in PDF, printed manuals and MS Word DOCX output.

Inserting an external HTML file in an existing topic

Merging HTML files injects the entire external HTML file, including its <head> section and everything it contains. If you use it to insert an HTML file in the middle of an existing topic, it will also paste in all the information that is normally in the head section of the HTML page. This may work because most browsers are quite forgiving, but it can also cause problems.

Because of this, it is advisable to remove everything in the external file outside the opening and closing <body> and </body> tags, and those tags as well, when merging into topic pages. Basically, such files should only contain normal HTML code, without the additional sections needed for independent pages.

Step 1: Preparing a full page for insertion inside a topic:

1.Open the external HTML file in an editor.

2.Locate the opening <body> tag and delete it and everything that comes before it.

3.Locate the closing </body> tag and delete it and everything that comes after it.

4.Save the file with the .htm or .html extension.

Step 2: Insert the file with the Code Object tool

See Inserting HTML code objects for instructions.

Replacing a topic with an external file

In some special cases you may want to replace a topic entirely with an external HTML file. It's important to understand that when you to a this you are responsible for the entire layout. You must provide not only the page content but also everything that would normally be in the HTML page template. So you need to provide the <head> section and all the settings there, including CSS file references JavaScript file references meta tags and so on.

This method is incompatible with most skins and templates!

This is a method that should only be used in very special cases where you completely understand the HTML code you are using and the results it will produce. It will be incompatible with most skins in templates included with Help+Manual and all Premium Pack skins without exception. In the huge majority of cases the insertion method described above is the only method you should use.

Procedure

It's important to understand that the #MERGE command inserts the entire HTML file it references. Since HTML files are normally complete, with all the header and layout information they need, you don't want the page components that are normally used for Help+Manual topic pages. You need to create a special HTML topic page template that does not contain this information; otherwise you will have two pages in one, nested inside each other.

The solution here is to create an empty HTML topic page template that only contains the variable for inserting the content from your topic page.

Step 1: Create a special HTML page template for merged HTML files

1.In your project, go to Project Explorer: Configuration > HTML Page Templates, click on Add to create a new page template and give the template a descriptive Name like External.

2.Select the new template, and in the Source Code tab select all the code and delete everything.

3.Type in the variable <%TOPIC_TEXT%> in the Source Code tab, so that this is the only content. It should look like this:

4.IF YOU ARE USING A SKIN:
If you are using a skin to publish you must repeat the above steps in the skin file as well. Open the .hmskin skin file in Help+Manual (select .hmskin as the file type to open in the Open dialog) and add your additional HTML page template there as well, with exactly the same contents and the same name.

Step 2: Create the topic with the #MERGE command to insert the file

1.Create an empty topic in the position where you want to insert the file.

2.Select the Topic Options tab on the left of the main editor window, and in the HTML Page Template: field select the External template you created in step 1 above.

3.Use the Code Object tool to insert the external file.

Please enable JavaScript to view this site.

This method is incompatible with most skins and templates!

Procedure