How to make a map so a Web app can draw from Webhelp?

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

Moderators: Alexander Halser, Tim Green

Post Reply
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

How to make a map so a Web app can draw from Webhelp?

Unread post by Dave Gehman »

We have a Web-based application in JavaScript. A WebHelp HTML entity will serve as its help file.

Ideally, we want a couple of things:
1. The ability for a user of the Web app to do something analogous to the conventional press of F1 to call for help -- maybe right-click & select a Help options -- that then presents information from the WebHelp address that explains the actions and concepts in the context of where the user is in the app.
2. Creation of context-sensitive help such as tooltips that are not hard-coded, but dynamically draw from the WebHelp pages.

I understand that these have to be implemented in code in the web app. I'm having trouble seeing how we can implement this. Or even if we can.

I've exported a text Map File from the Project > Context Tool dialog, but I can't see how that will help our developer create actions or methods that reach into specific locations in the WebHelp file.

Is there a way to create a (fine-grained) map file of the WebHelp pages? Or do we have to create this manually?

In a way, it is like tapping into an HTML link in the WebHelp (such as you'd have with a cross-referenced hyperlink in one chapter in the WebHelp that jumps to a location in a different chapter)... but with the non-trivial major difference that the calling location, the location of the hyperlink, is outside the WebHelp code...
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Tim Green »

Hi Dave,

WebHelp pages are all always in the same folder, so you don't really need a map of them at all. You just need a list of the filenames, and you can get that with the Sitemap feature -- and when you upload that along with your WebHelp it will also improve search engine performance. You can generate that in Configuration > Publishing Options > WebHelp > Navigation (in your project if you are not using a skin, in the .hmskin if you are).

Then you just need to know how to link to your WebHelp pages. For linking to standard WebHelp created without skins and with the standard HM skins and older Premium Pack skins, the instructions are here:

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

The instructions for the new V3 skins in the Premium Pack are in the Premium Pack help here:

http://www.it-authoring.com/info/pp3hel ... nking.html

These skins also import embedded help in your own web pages and the ability to display both popups and full help topics overlaid on your own web pages without taking the user away to another tab or window. See this chapter here for details:

http://www.it-authoring.com/info/pp3hel ... edded.html
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.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Dave Gehman »

Thanks - your pointers to your help file topics are exactly what I need to begin exploration.

I do think we'll need a map other than the site map, however, because we'll need a fairly fine granularity. That is (if I'm conceiving of this correctly), we'll need anchors that act as targets within a given page in order to reach a specific image, sentence or paragraph, so that our developers can create calls that use the "a name" or "#" keywords/codes.
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Tim Green »

Dave Gehman wrote:I do think we'll need a map other than the site map, however, because we'll need a fairly fine granularity. That is (if I'm conceiving of this correctly), we'll need anchors that act as targets within a given page in order to reach a specific image, sentence or paragraph, so that our developers can create calls that use the "a name" or "#" keywords/codes.
That's what anchors are for:

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

You can generate a map list of topic IDs with anchors using the context tool:

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

You just need to know that the HTML files are generated by downcasing the ID and adding your chosen topic extension (usually .htm or .html). If you avoid special characters in your IDs you don't have to worry about characters being converted to - or _ on publishing. :)
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.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Dave Gehman »

I see that a typical anchor looks like this (this one is an anchor I created for the definition of the word 'account'):
<a id="defaccount" class="hmanchor">
The immediately following HTML is the definition itself:
<p class="p_Normal">An account or user account is identified to the kBridge system by a user name, password, and security details, such as access to certain projects or designs.</p>
The page itself is "terms-and-definitions.html"

Q1: Is this correct? Our developer would create a link directly to the "account" anchor as follows:
<a href="terms-and-definitions.html/#defaccount">
Q2: If our developer wanted to call the anchor + the following <p> content (i.e. to make a tooltip), is there a way to do this?

Q3: Since this would result in a really bad tooltip because it's way too long, is there a way to create an ancillary tooltip summary that does NOT appear on the WebHelp page? For example, something like
User name, password, security level
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Dave Gehman »

Dave Gehman wrote: Q1: Is this correct? Our developer would create a link directly to the "account" anchor as follows:
<a href="terms-and-definitions.html/#defaccount">
Yep, that's correct, found that in the H+M help file - thanks!

Follow-on questions: still could use help there .
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Tim Green »

Hi Dave,
Q1: Is this correct? Our developer would create a link directly to the "account" anchor as follows:
Not quite. Please see the documentation pages I referenced for details on the anchor link syntax.
Q2: If our developer wanted to call the anchor + the following <p> content (i.e. to make a tooltip), is there a way to do this?
Q3: Since this would result in a really bad tooltip because it's way too long, is there a way to create an ancillary tooltip summary that does NOT appear on the WebHelp page? For example, something like
Do you mean you want to pull content from the help page to display it in a tooltip on a page in your website? That won't work without reading the entire page in the background somehow, which would generate large unnecessary overheads. It would be much more efficient to just embed tooltips in your own pages, without trying to interface with the help. What you would really need would be a single file of tooltips with IDs that you would load once per session on your own web page and then reference and display with your tooltips, if you don't want to embed them in your pages. HM doesn't generate something like that, however.
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.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Dave Gehman »

Tim Green wrote:
Q1: Is this correct?...
Not quite. Please see the documentation pages I referenced for details on the anchor link syntax.
Yes, I've been working through this. Our developers are Web-savvy, so they'll be able to walk me through the intricacies.
Time Green wrote: Do you mean you want to pull content from the help page to display it in a tooltip on a page in your website? That won't work without reading the entire page in the background somehow, which would generate large unnecessary overheads. It would be much more efficient to just embed tooltips in your own pages, without trying to interface with the help. What you would really need would be a single file of tooltips with IDs that you would load once per session on your own web page and then reference and display with your tooltips, if you don't want to embed them in your pages. HM doesn't generate something like that, however.
Not quite - we want to pull tooltip content from WebHelp into a screen in our JavaScript Web app (I'm told there is a difference, but I don't know what -- possibly something to do with the fact that the app screen is dynamic, the Web page is relatively static.)

However, I'm puzzled. if we can insert, into our JS app, pinpoint contextual help that jumps to a specific anchor in our WebHelp, why can't a tooltip code snippet do the same thing -- without reading the entire page in the background?

That said, or rather that asked, adding a routine to read in material from the WebHelp at initiation wouldn't be a big deal.
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Tim Green »

However, I'm puzzled. if we can insert, into our JS app, pinpoint contextual help that jumps to a specific anchor in our WebHelp,

When you do that you you are simply displaying the entire web page. To do that you must load and render the entire page, then the page is scrolled down to the position where the anchor is.
why can't a tooltip code snippet do the same thing -- without reading the entire page in the background?
If the "tooltip code snippet" is in the topic then it is in the topic's HTML page. The only way to get it out would be to load and render the entire page in the background, then search for it, then extract and format it, then display it.
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.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: How to make a map so a Web app can draw from Webhelp?

Unread post by Dave Gehman »

Tim Green wrote: When you do that you you are simply displaying the entire web page. To do that you must load and render the entire page, then the page is scrolled down to the position where the anchor is.
....

If the "tooltip code snippet" is in the topic then it is in the topic's HTML page. The only way to get it out would be to load and render the entire page in the background, then search for it, then extract and format it, then display it.
All is revealed. Makes sense. Many thanks.
Post Reply