Template generated "see also" links ?

This is the place to share H&M templates and utilities with other users. Topic templates can be posted as text attachments (*.txt) or in the posting itself between

Code: Select all

 and 
tags. Print manual templates (*.mnl) are digital and can only be posted as attachments. Utilities and multiple files can be posted in ZIP archives. Please include plenty of comments so that users understand what you're doing! Registration is required to access this forum.

Moderators: Alexander Halser, Tim Green

Post Reply
Phil C
Posts: 84
Joined: Sun May 28, 2006 10:57 pm
Location: Tucson, Arizona

Template generated "see also" links ?

Unread post by Phil C »

After considering the work involved in setting up "see also" associative links in .CHM topics, it occurred to me to investigate automating the links.

The basic concept is to use a bit of javascript in the default html template to generate the link into the top line of the topic, beside the "show/hide hidden text" href, when the <%TOPIC_AKEYWORDS%> variable has content. The html looks simple enough to generate.

However, it also occurs to me that if it is as simple as it looks:
A. Somebody probably has already done it and so there is no point in my reinventing it.
(or)
B. Maybe I am overlooking something that shoots down the whole concept. The script is no problem, but I have zero experience with the use of visual objects in html/CHM. In particular it isn't clear to me whether the id attribute of the <object> has any particular requirements beyond just needing to match the hhclick method call. Otherwise, coding the object appears straightforward.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Template generated "see also" links ?

Unread post by Tim Green »

Hi Phil,

I've never tried this myself because I'm not a big believer in automated See Also lists, no matter how they are produced. I'm also not quite sure if it would work because I don't know if CHM will accept an ActiveX object that is generated on the fly, and it's not quite as simple as it looks at first glance. For each see also link you need to put an ActiveX object in the <head> section that matches the link that calls it. Suppose the keyword you are looking for is "Grand Duke Ferdinand", then the matching object and link you would need to create would look like this:

Code: Select all

ActiveX object at the end of the <head> section:
<object id="hhctrl_1" type="application/x-oleobject" classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"><param name="Command" value="ALink"><param name="Item1" value=""><param name="Item2" value="Grand Duke Ferdinand;"></object>

Matching link:
<a href="javascript:hhctrl_1.hhclick()" class="scriptlink">See Also</a>
The problem would be the ActiveX object. You'll have to try it to see if it works, because it may or may not get parsed if it is generated on the fly. 8)
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.
Phil C
Posts: 84
Joined: Sun May 28, 2006 10:57 pm
Location: Tucson, Arizona

Re: Template generated "see also" links ?

Unread post by Phil C »

I wasn't specific enough in my post. What I have in mind is not a separate associative hyperlink for each A-keyword, but rather a single "All Related Topics" link in a fixed place at the top of the topic. This would include all of the A-keywords specified in the topic options panel. I realize that with a large number of A-keywords in a topic, this scheme would probably not provide the best user experience. However, In my case there will be few A-keywords per topic, and the names of the topics in the resulting topic list should make it easy to select the ones you would be interested in seeing.

Therefore, only one object is required. The object framework can be automatically generated for every topic:
<object id="">
<param name="Command"...>
<param name="Item1"...>
</object>

At load time, one additional <param> has to be added to the object for each A-keyword. (Using DOM appendChild)
The problem would be the ActiveX object. You'll have to try it to see if it works, because it may or may not get parsed if it is generated on the fly. 8)
I agree. As I said, I have no experience dealing with objects. I will give it a try and let you know how well it works. Thank goodness for Firebug! Otherwise, I would be flying totally blind.
Phil C
Posts: 84
Joined: Sun May 28, 2006 10:57 pm
Location: Tucson, Arizona

Re: Template generated "see also" links ?

Unread post by Phil C »

It appears it is not possible to use the ocx dynamically.

If the object is created in the template <head> and the A-keyword params added dynamically via script after the page is loaded, the result when the link is clicked is a popup message to the effect that there are no related topics to display. (There actually are of course)

It appears what happens is the empty object in the head is compiled and the dynamically added param elements are ignored. I displayed the object in Firebug and it looked exactly as it should, so the problem wasn't due to an error in my script.

I also tried having the link call a custom function instead of hhclick(). The function dynamically constructs the object, appends it to the document and then invokes it with objid.hhclick(). The result?
"An error has occurred in the script..."
Error: Object doesn't support property or method 'hhclick'

Perhaps there is some other method needed to "register" the object before invoking it. I also wonder if there are jquery functions to do something similar. For now, I guess I will shelve it.
Phil C
Posts: 84
Joined: Sun May 28, 2006 10:57 pm
Location: Tucson, Arizona

Re: Template generated "see also" links ?

Unread post by Phil C »

Well, son-of-a-gun, Tim. I see you have been down this path already:
http://www.it-authoring.com/bb/helpauth ... 18&start=0

The thingy you proposed way back in 2002 would definitely be some of some "help" (to coin a phrase). :D

Check "Insert all A-keywords from this topic", Insert my "Related Topics" text, save as a snippet, and past it into every topic having A-keywords. Not as fully automated as I would like but a lot easier than what we have now.

BTW, why does HM6 make me go through the even-more-maddening step of having to save a link and then edit it before the macro option shows up in the dialog? Seems like this is designed to convince users that they really really really should avoid A-keywords. :(
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Template generated "see also" links ?

Unread post by Tim Green »

Hi Phil,
BTW, why does HM6 make me go through the even-more-maddening step of having to save a link and then edit it before the macro option shows up in the dialog?
This is a glitch, the macro option should always be displayed. I've passed on a report.
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.
Phil C
Posts: 84
Joined: Sun May 28, 2006 10:57 pm
Location: Tucson, Arizona

Re: Template generated "see also" links ?

Unread post by Phil C »

This is a glitch, the macro option should always be displayed. I've passed on a report.
Thought as much.

After reflecting on this topic some more, it seems like a silly idea to use javascript to implement completely static content that is known at design time. It now seems obvious that the best way to achieve the desired result programmatically is to write an html post-processor that would insert the desired tags into the generated html before the chm compiler is called.

I suppose to automate it I could set up a batch file to call the post-processor and then the help compiler, but was wondering if there was a way to do that in the HM6 publishing task automator. However, that kind of "task" does not appear to be possible with the task editor. Is that correct, or am I just missing seeing it?
David Makulec
Posts: 150
Joined: Tue Nov 03, 2009 6:14 pm

Re: Template generated "see also" links ?

Unread post by David Makulec »

While I share Tim's knee-jerk aversion to a totally automated "see also" solution, I myself have opted for a very rigidly-controlled structure, where every topic includes a "Related topics" set at the end of the topic.

I maintain this by hand. It's tedious.

But the structure is easily defined, with the side benefit (I, as a non-programmer, fantasize) that it could (in theory) be automated.

Four topic levels:

-- Each top-level topic ends with a "Related Topics" bulleted list of links to all second-level/child topics, in TOC order.
-- Second- and third-level topics end with a "Related Topics" bulleted list of links to a) all third- (or fourth-)level/child topics of that topic; b) all sibling topics of that topic; and c) the single parent topic of that topic.
-- Fourth (and lowest)-level topics end with a "Related Topics" bulleted list of links to a) all sibling topics of that topic (there are no children); and b) the single parent topic of that topic.

The bulleted links use the TOC topic name as the visible link text.

It's enough of a pain that I'd love to have these auto-update if I add or rearrange topics under a parent, or change one or more TOC topic name and thus need to edit the text of visible "Related Topics" links.

It's not clear to me if this is the same kind of problem as the A-keywords automation. But it seems <ahem> related.
Phil C
Posts: 84
Joined: Sun May 28, 2006 10:57 pm
Location: Tucson, Arizona

Re: Template generated "see also" links ?

Unread post by Phil C »

Your suggestion is sort of a localized "mini-TOC" of subordinate topics. Interesting.

My concept of "See also" links was only with respect to html outputs, and specifically, CHM. Because I use a skin with a TOC panel, linking to subordinate topics in the TOC is unnecessary. The need for links arises when I want to direct the reader's attention to another topic in a totally different section that discusses something relevant to the current topic.
David Makulec
Posts: 150
Joined: Tue Nov 03, 2009 6:14 pm

Re: Template generated "see also" links ?

Unread post by David Makulec »

Phil --
Your suggestion is sort of a localized "mini-TOC" of subordinate topics.
More or less, yes.

My employer has opted, for its own reasons, to provide Help in PDF format. (Not my call.)

In that context, I offer a topic's "Related Topics" list as an in-topic alternative to the PDF bookmarks and the PDF Contents page.

I, too, make linked references to topics in entirely different "branches" of the main TOC tree. But I tend to do so individually at the point of reference in the topic text, rather than gather those more far-reaching links into a single "see also" list.
Post Reply