Understanding HTML Templates

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
paulororke
Posts: 8
Joined: Tue Sep 18, 2018 4:04 pm

Understanding HTML Templates

Unread post by paulororke »

Hi,

I am struggling to understand how to apply and use HTML templates. I have a manual that involves 4 different products. I want to make a HTML Template for each one that simply adds an image and a couple of <hr> elements.

I am having quite the struggle in getting this to work. There are two things I am confused about:

1. Reading the help pages says I must edit the skin directly to add these templates. I tried opening the .hmskin file in the project folder, add some templates and save this "project" using the save icon at the top of the app. I was expecting to then see these available in the project when I open it via the .hmxp file in the same folder but they are not there. What is the correct method to create additional HTML Templates?

If I use the toolbar tool "Templates and Skins" to open the current project skin I can see these new skins but I have failed spectacularly to make them available to use in that same project. :frustration:


2. I create a HTML Template in the project itself I see it and can use it but not all the elements I add are visible when I switch a topic to use that Template.

Code: Select all

<%DOCTYPE%>
<html>
<head>
   <title><%TOPIC_TITLE%></title>
   <meta name="generator" content="Help & Manual" />
   <meta name="keywords" content="<%TOPIC_KEYWORDS%>" />
   <meta http-equiv="Content-Type" content="text/html; charset=<%DOCCHARSET%>" />
   <IF_CHM><meta http-equiv="X-UA-Compatible" content="IE=10" /></IF_CHM>
   <IF_HTML><meta http-equiv="X-UA-Compatible" content="IE=edge" /></IF_HTML>
   <meta name="description" content="<%TOPIC_DESCRIPTION%>" />
   <meta name="picture" content="<%TOPIC_PICTURE%>" />
   <link type="text/css" href="<%STYLESHEET%>" rel="stylesheet" />
   <style type="text/css">
     body { margin: 0px; background: #FFFFFF; }
   </style>
</head>
<body>

<IF_TOPIC_HEADER>
<table style="width:100%; border:none; border-spacing:0px; padding:5px; background:#FF0000">     
  <hr>
  <tr style="vertical-align:middle">
    <td style="text-align:left"> 
      <%TOPIC_HEADER%>
      <img src="Images\100x100.png">
    </td>
    <td style="text-align:right">
     <a href="<%HREF_DEFAULT_PAGE%>">Top</a>&nbsp;
     <IF_PREVIOUS_PAGE><a href="<%HREF_PREVIOUS_PAGE%>">Previous</a>&nbsp;</IF_PREVIOUS_PAGE>
     <IF_NEXT_PAGE><a href="<%HREF_NEXT_PAGE%>">Next</a></IF_NEXT_PAGE>
    </td>
  </tr>
  <hr>
</table>
</IF_TOPIC_HEADER>

<!-- Placeholder for topic body. -->
<table style="width:100%;border:none;border-spacing:0px"><tr style="vertical-align:top"><td style="text-align:left;padding:5px">
<IF_TOPIC_BREADCRUMBS><p style="font-size: 8pt; margin-bottom: 15px">
<%TOPIC_BREADCRUMBS%> > <%TOPIC_TITLE%></p></IF_TOPIC_BREADCRUMBS>
<%TOPIC_TEXT%>
</td></tr></table>

</body>
</html>
The only thing I seem to be able to affect here is the table background colour.

What am I missing?
Simon_Dismore
Posts: 204
Joined: Thu Jul 13, 2017 2:57 pm

Re: Understanding HTML Templates

Unread post by Simon_Dismore »

If you are new to H&M and to skins, it might make sense to experiment without using any skins to begin with.

If your changes don't work when you start from there, you can ask more generally "why not?"

But if your changes work in skins but not outside them, it's fair to ask "why not?"
User avatar
Tim Green
Site Admin
Posts: 23143
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Understanding HTML Templates

Unread post by Tim Green »

Hi Paul,
paulororke wrote:What am I missing?
Basically, you are trying to run before you can walk here. Before trying to roll your own you need to get a basic understanding of how templates and skins work in Help+Manual, otherwise you're going to be very frustrated. These chapters in the help are a good starting point:

Basic information on skins: https://helpandmanual.com/help/index.ht ... _skins.htm

Details on HTML templates: https://helpandmanual.com/help/index.ht ... plates.htm
2. I create a HTML Template in the project itself I see it and can use it but not all the elements I add are visible when I switch a topic to use that Template.
The only thing I seem to be able to affect here is the table background colour.
If you are using a skin nothing you edit in templates in the project will have any effect on your output at all, because all the templates in the project are replaced by those in the skins. You can still change the background color in the editor but that has no effect on the output. That's just a legacy leftover from the days when HM didn't use skins.
1. Reading the help pages says I must edit the skin directly to add these templates. I tried opening the .hmskin file in the project folder, add some templates and save this "project" using the save icon at the top of the app. I was expecting to then see these available in the project when I open it via the .hmxp file in the same folder
You didn't see them because that's not how it works. You don't "see" anything in a skin inside the project. You only see the templates in a skin when you are editing in the skin. Also, using multiple page templates is a completely different subject and quite complex -- when you create multiple page templates in a skin (which you should almost never need to do) you also need to create a matching dummy template with exactly the same name (content doesn't matter, you only need the name) in your project so taht you can choose that template for specific topics. However, that is a specialized option which, again, you should also never need to use. And if you use it in a pre-designed skin you need to create an exact copy of the custom code in the skin's original page template in your copy and only make editing changes that don't break the original code and layout, otherwise you will get serious errors.

But again, before you start doing something like that you should get a basic grasp of how templates and skins work in the first place.
What is the correct method to create additional HTML Templates?
Counter question: What do you want to achieve with your "additional" templates? Why do you want to create them in the first place?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
paulororke
Posts: 8
Joined: Tue Sep 18, 2018 4:04 pm

Re: Understanding HTML Templates

Unread post by paulororke »

Hi Tim,

thanks for the explanations. I will skip straight to your question: "What do you want to achieve with your "additional" templates? Why do you want to create them in the first place?"

I had thought the HTML Templates would cut down on the work of having to manually modify every page with similar content. The manual relates to installing and managing our software in a large environment. There are 5 different products, each with many pages. I had though that it would simplify things to be able to say "This page is Product A, apply the 'Product A' template and it's 'header' changes accordingly.

As it stands now I create a pages and for every one I have to manually add the product icon, it's name and the <hr> elements. I had thought that a classic use case for a 'template', or similar. This topic is for products A, apply template A. Perhaps the simplest way for me to do this would be to make 5 empty topics, one for each product, and simply copy/paste the appropriate header content each time.

It seems that you are saying these HTML Templates are only intended for entire projects?

I have some reading to do, but perhaps that I am barking up the wrong tree and I should use 5 empty topics as my "templates".
User avatar
Tim Green
Site Admin
Posts: 23143
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Understanding HTML Templates

Unread post by Tim Green »

Hi Paul,
I had thought the HTML Templates would cut down on the work of having to manually modify every page with similar content.
The the HTML templates are most decidedly the wrong choice for achieving that. They have nothing to do with topic content. They only define the layout and functionality (with scripting etc) of topic pages in WebHelp and other HTML-based output formats. The content all comes from your project, not from the HTML template.
I have some reading to do, but perhaps that I am barking up the wrong tree and I should use 5 empty topics as my "templates".
Definitely the wrong tree, or rabbit hole more like. There are much better solutions for modifying the content of your topics without having to maintain multiple versions of almost the same thing. What you want to do is to leverage all of Help+Manual's many tools for creating conditional, variable and reusable content with maximum efficiency. I won't try to go into it all here at once, but here is where you should look to get started:

Snippets, for both paste-in templates and reusable content that you only need to edit in one place, that you can insert in topics between other bits of content:

https://helpandmanual.com/help/index.ht ... ippets.htm

Conditional output, for including and excluding chapters, topics and any content within topics on the basis of output format or conditions that you define yourself:

https://helpandmanual.com/help/index.ht ... itions.htm

Modular help systems, which allow you to combine multiple projects and publish them as though they were a single project:

https://helpandmanual.com/help/index.ht ... odular.htm

Style repositories, that allow you to have a central stylesheet and source of snippets for multiple projects:


https://helpandmanual.com/help/index.ht ... tories.htm
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Understanding HTML Templates

Unread post by Martin Wynne »

Hi Paul,

You can do what you want with the HTML topic page templates, but it gets a bit involved if you are also using a skin.

If you just want some identifying header information on a topic page -- "This page is about Product A" -- "This page is about Product B" -- the easiest way would be to use snippets. You would have full editor formatting available in creating (and later editing) each snippet. When starting a new topic page, just insert the relevant linked snippet.

The alternative would be to create different manuals for each product, using the Build Options. That way only the pages relevant to each product appear in its manual.

edit: Tim beat me to it. :)

Martin.
paulororke
Posts: 8
Joined: Tue Sep 18, 2018 4:04 pm

Re: Understanding HTML Templates

Unread post by paulororke »

Thanks for the responses all of you.

I will do the required reading and change my approach accordingly.

Great support guys!
Post Reply