'Come from' information for popup topics or snippets

[Rob Davis]

HI
(This takes me back to my Structured Programming days!)
In a Snippet, (or a popup topic which occurs once in the TOC but will be referred to from within many topics), I would like the user to see some information that changes depending on how he arrives at the that point.
I can set up lists for each of the variables based on the different usages (and include a value for the case where there is no match),
I envisage some code at the start of the topic that effectively sets up a CASE structure, based on the state of a 'return' link set when the user left the main-line topic. e.g.
SOURCE ......VAR1.........VAR2
Picture......PicFile........PicDir
Record......RecFile.......RecDir
Export......ExpFile........ExpDir
Exception.(filename)....(Folder)
Then, the topic text might say "When inserting a (Source) file, the user inserts (Variable1) and (Variable2) in the 'FileType' and 'Location' fields.".
The 'Exception' values have to work for the print version of the file, where the user reads the topic in the natural flow of the file.

Suggestions please?

Thanks
Rob

[Tim Green]

Hi Rob,

I would like the user to see some information that changes depending on how he arrives at the that point.

That isn't directly possible in Help & Manual because when you exclude content with conditions it is really excluded, i.e. it is not there at all. You would need to set up JavaScript to hide and display content in the current topic.

[Rob Davis]

HI Tim
Thanks for the reply.
Don't know if I explained well enough. I was not talking about different builds or conditions (except for the PDF, that is.)
What I was craving was really just an internal variable that would pass the name of Topic containing the last-used link.
Maybe just a bit ambitious especially with my zero-knowledge of JavaScript et al. (COBOL, FORTRAN and PL1 skills are not highly rated these days!)
I'll just write the popup with nice bland 'a or b or c' descriptions.
Regards

[Tim Green]

Hi Rob,

What I was craving was really just an internal variable that would pass the name of Topic containing the last-used link.

That's possible, but more complex than you might imagine. Unlike the languages you are familiar with, JavaScript is not allowed to be "stateful", i.e. current state information is stringently restricted due to the security nightmare that is the Web. In WebHelp, topics must be loaded into an iFrame to make it possible to maintain things like the TOC on the same page, and it is not possible to get the link that was clicked to load the current topic into the iFrame directly -- normally you could just get the name of the page containing the link that loaded the iFrame, and that wouldn't help you here.

There would be three ways to communicate the link: via the URL that loads the topic, via a cookie, or by setting a variable in the parent document and reading it remotely in the current topic after it has been loaded. In all these cases, however, you would have to set up scripting that would manage it on both ends. The link would have to trigger a function that would store the current link data, and the page being loaded would have to read that data after loading. You would need a way to attach the link tracking function to all the links in your project to do this. It's possible, but not quite as transparent as you were hoping...

[Rob Davis]

Thanks for the explanation.
And here I thought it was as simple as getting a variable based on the 'Back' button.
Guess I will leave coding to the youngsters - until I learn JavaScript, that its!

[Simon Dismore]

You can achieve this result using a more declarative approach:

• define your custom "text variables" (actually constants) in common properties,
• insert these variables into your snippet,
• link the snippet into each topic that needs it,
• redefine the text variables on a per-topic basis as required,
• recompile and publish.

Here are the steps:

1. In Configuration > Common Properties > Text Variables, create variables and assign global default values for them (e.g. I created ROBSOURCE, ROBVAR1, ROBVAR2).

global default values.png

2. Create a snippet topic in the current file.

3. Use Write > [Insert Object] Variable to mark the points in the snippet where the text variables should be transcluded. For example: "In <%ROBSOURCE%> you can copy from <%ROBVAR1%> to <%ROBVAR2%>."

snippet with variables.png

4. Navigate to a normal full-page topic that requires the snippet, and use Write > [Insert Object] Snippet to insert the snippet topic.

When the project is compiled, the global default variables will be transcluded into the snippet everywhere it is used. These defaults can be redefined for an individual topic as follows:

50. Select the topic Options tab in the editor.
51. Locate the Topic Variables table.
52. Click the + (plus) button to add one of your text variables to the table.
53. Edit the value cell as required. The value in the topic variables table will over-ride the default value in the project's common properties.
54. Repeat for each variable that needs to be redefined for this specific topic.

redefining variables within a topic.png

The snippet will be incorporated into each topic that links to it. If a topic has redefined the variables, the per-topic values will be transcluded. Otherwise, the global default values will be transcluded.

If you are interested in learning JavaScript, it's possible to achieve a similar result using popups. Global and per-topic variables are defined in the same way, but I think the transclusion points in the snippet will have to be indicated using a different technique, and the popup will need to be invoked via a modified script that transcludes variables dynamically at run-time. I haven't tested this.

[Simon Dismore]

it's possible to achieve a similar result using popups

Here's how.

Javascript popups are displayed by a function stored in a JavaScript variable called hmshowPopup. The variable is set up by the script "helpman_topicinit.js" which is automatically invoked from the <head> section of your page. You'll need to modify this function so that it will replace tokens in the popup text with values from the H&M text variables. There are many ways you could achieve this. The method I'm going to describe isn't the most efficient, but it's easy to explain and implement, and it works.

The first stage is to edit your popup so that it uses tokens that the H&M Compiler will *not* detect and replace. In my test I used {{ }} to delimit my tokens instead of <% %>.

redefining variables within a popup.png

The second stage is to edit your HTML Page Template to assign a modified function to the hmshowPopup variable.

You do this by adding a script to the bottom of the page template. A script in this position will be invoked after helpman_topicinit.js has been run. At this point the hmshowPopup variable will contain the standard popup code as delivered by ec-software.

The code you want to paste is:

Code: Select all

<script type="text/javascript">
hmshowPopup = function(event, txt, trigger) {
  $('#hmpopupdiv').stop().remove();
  var pop = $('<div id="hmpopupdiv"></div>').appendTo('body');
  if (hmPopupSticky) { 
    $('body').bind('mouseup.hmpopup', hmhidePopup);
    $('body').bind('keydown.hmpopup', function(e) { if (e.keyCode == 27) hmhidePopup(); } ); 
  }	      
  txt = txt.split("{{ROBSOURCE}}").join("<%ROBSOURCE%>");
  txt = txt.split("{{ROBVAR1}}").join("<%ROBVAR1%>");
  txt = txt.split("{{ROBVAR2}}").join("<%ROBVAR2%>");

  pop.html(txt);

  var posLeft = event.clientX+$(document).scrollLeft();
  var posTop =  event.clientY+$(document).scrollTop();

  var maxW = $(window).width()/1.5;
  var w = pop.width();
  if (w > maxW) pop.width(maxW);
  var t = 20 + posTop;           
  var l = (posLeft - w/2);
  if (l < 10) l = 10;
  if ((l + pop.outerWidth()) > $(window).width()) l = $(window).width() - pop.outerWidth();
  if (l < 0) l = 0;
  pop.css( { left: l+'px', top: t+'px'} );
  if (hmAnimate) pop.show('fast');
    else pop.show();
}
</script>

This is an copy of the original code, with three new lines added before pop.html(txt). These new lines search for each of your tokens (e.g. {{ROBSOURCE}}) and replace them with your variable values. Because the script is part of the page template, H&M will have substituted the actual variable values directly into the script. So on a page where you have redefined one of your variables, the topic-specific value will be embedded in your script, e.g.

Code: Select all

  txt = txt.split("{{ROBVAR1}}").join("topic RobVar1");

On a page where you haven't redefined the value, the global default will be embedded in the script instead, e.g.

Code: Select all

  txt = txt.split("{{ROBVAR2}}").join("default RobVar2");

Recompile, publish and enjoy....

[Rob Davis]

Simon - thanks a lot for the detailed information. I will try to digest and use.

[Simon Dismore]

The code you want to paste is...

On reflection I think it would be safe to copy the original function directly from the variable, so the code added to the page template can be much simpler:

Code: Select all

<script type="text/javascript">
var hmshowPopup_base = hmshowPopup; 
hmshowPopup = function(event, txt, trigger) {
  txt = txt.split("{{ROBSOURCE}}").join("<%ROBSOURCE%>");
  txt = txt.split("{{ROBVAR1}}").join("<%ROBVAR1%>");
  txt = txt.split("{{ROBVAR2}}").join("<%ROBVAR2%>");

  return hmshowPopup_base(event, txt, trigger);
}
</script>

This has the advantage that you'll always be using the latest version of the hmshowPopup function as delivered, rather than freezing it at the current version. In addition, your intentions will be clearer to anyone who has to maintain your projects in future. It's also a few bytes more efficient per topic.