Need info, workflow around field level context help & popups

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

Need info, workflow around field level context help & popups

Unread post by Dave Gehman »

This is for a Web (cloud-based) application developed mainly in JavaScript. The associated H+M help will be the WebHelp type. The overriding problem is that I know nothing of coding in JS.

What's desired
It would be great to have something beyond tool tips in the application for some areas that a user will be doing with our application. It looks as though that "something" is field-level contextual links to the help file and/or pop-ups that draw from the help file.

Problem is, I can't wrap my mind around the workflow in creating these.

(1) Specifically, I need to understand how (quoting from http://www.it-authoring.com/info/hmwebh ... rmats.html) "Calls to WebHelp are made with normal URLs." URLs I understand, but how and where are these calls made? Does our JavaScript coding team make these?

If so, a second puzzle: I see that I can work with a map file, which per http://www.it-authoring.com/info/hmwebh ... files.html can be given to me by our coders: "The compilers for many programming languages have facilities for automatically generating text [map] files... containing topic IDs and/or help context numbers for the components and controls used in the program."

(2) My puzzle is: how does this automatic generator know what is a topic or a context numbers? Are these gathered by the compiler from something-or-other (what?) put in the code by our JS coders?

If the answers to both puzzles are, "You have to know about JS coding," I'll come back later after I assimilate the basics of JS.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Need info, workflow around field level context help & po

Unread post by Tim Green »

Hi Dave,
(1) Specifically, I need to understand how (quoting from http://www.it-authoring.com/info/hmwebh ... rmats.html) "Calls to WebHelp are made with normal URLs." URLs I understand, but how and where are these calls made? Does our JavaScript coding team make these?
That really depends how your web application is made. The final result needs to be links that the user will click on pointing to the specific URLs you want to go to. Those are usually <a> tags with a href reference, but it's also possible for them to be scripted -- again, that all depends on your application, not on Help+Manual. What matters is that in response to user interaction (normally a click or a tap) the desired URL is called to go to your WebHelp. This is normally done with a regular link on the page.
If so, a second puzzle: I see that I can work with a map file, which per http://www.it-authoring.com/info/hmwebh ... files.html can be given to me by our coders: "The compilers for many programming languages have facilities for automatically generating text [map] files... containing topic IDs and/or help context numbers for the components and controls used in the program."
They would do that if you hadn't started developing your help yet. They would generate a map file with topic IDs they want to link to and you would import it into Help+Manual with the context tool set to create topic files for IDs that don't currently exist in the current project. The map file can theoretically also include context IDs but those are really only for CHM files, which you won't be using. Help+Manual WebHelp can use context IDs but they are not recommended, because they are very human-unfriendly. Developers only use them in WebHelp if they are already using them in CHM and want to simplify the process of generating the URLs for WebHelp by slotting the same context ID numbers into the WebHelp URL syntax. If you don't have to do this it's much better to use topic IDs. You're more likely to have and idea what a reference to user_widgets.html is than one to 88774567... 8)
(2) My puzzle is: how does this automatic generator know what is a topic or a context numbers? Are these gathered by the compiler from something-or-other (what?) put in the code by our JS coders?
That question doesn't arise because you'd only be using the map file like that to create new topic files in your project. Once you've done that, you're more likely to be exporting a map file from Help+Manual with a list of topic IDs to link to.

Field-level help and popups in your own web pages aren't available in WebHelp in standard skins. That's very important. In standard WebHelp you can only link to WebHelp topics from your pages and display them in a new tab or window, and popups are only available within the WebHelp itself. Field-level topics and popups within your own pages are only available in the new V3 skins in the Premium Pack:

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: Need info, workflow around field level context help & po

Unread post by Dave Gehman »

Thank you again.

I begin to see (I think, anyway).

Bottom line #1, anything a user can click on in the application needs to be put there by our coders. There is no automated injection of WebHelp links (equivalent to 'there is no free lunch,' which I can understand and live with).

Creating the map file from the application code prior to development of help... in an ideal world that would be great. But we have to develop code and help simultaneously.

So, bottom line #2, there's not much reason for the developers to create a map file.

Bottom line #3, if I want the application coders to insert calls to WebHelp, I can supply them with map files as development progresses. We will have to coordinate closely so that they know where to put calls to which topics / keywords.

Bottom line #4, if I want to lean on an available skin, we need the Premium Pack.

Do I have these right?
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Need info, workflow around field level context help & po

Unread post by Tim Green »

Hi Dave,

That's a pretty good summation. Also general advice: Worry less. 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.
Post Reply