Links to Customer Files / Intranets - Alternative Method

 

 

What's covered?

This page provides an alternative method of providing editable links to the one described in Links to Customer Files / Intranets.

Whilst it is quicker and easier to implement, I believe the drawbacks outweigh that. However, the choice is yours.

 

Drawbacks

Before describing how this method works, let me tell you about the drawbacks.

  1. If your output is webhelp, when you upgrade the help at some point in the future and replace the topics, all the editing that your customer has done, will be lost. This does not usually lead to a letter of thanks! They have to be aware from the outset that the exercise of customising the help needs to be repeated whenever the help is updated.
  2. If your output is a CHM file, as you will see when you read the details of the method, your customer will need to have had a copy of the source files for editing. Again, when you upgrade they will need to repeat the process with the source files.
    Additionally each target file will need to be added as a baggage file making the whole process less attractive than it is for webhelp.

If you still feel it could meet your needs, then read on. If you find any enhancements, do let me know.

What You Do

Inserting the script in the topic

You need to decide upon a standard place to insert the script. My suggestion is that it goes immediately below the heading for the topic. Customers using the idea can then train their staff that they click this link instead of the help or as well as, it depends on whether they are providing alternative help or supplementary help.

There are two ways to insert the script but first a note about styles. Because of the way javascript writes the link, it will appear underlined but the text will be in the colour of your normal <p> tag rather than your hyperlink colour. To overcome that I added a <p> tag class in my style sheet called Internal where the colour is defined to be the same as a hyperlink. This is a one off task. You can use other styles if you prefer.

OK, let's insert the script.

Method 1

Use this method if you prefer to work from the WYSIWYG editor.

Click inside the box below and press Ctrl + C

Go to a blank line where you want to insert the script and use Insert | Advanced | Script. RH will insert the script into the true code and add some tags. You will see a red square in the WYSIWYG editor, that is explained below. Put the cursor in that line and select the Internal style from the dropdown list of styles.

Method 2

Use this method if you prefer to work in true code.

Click inside the box and press Ctrl + C

Now paste that into the desired position in your topic.

Sometimes RoboHelp has been known to strip out javascript in the output. Macromedia's response to that was to use Insert | Advanced | Script to ensure that the necessary tags were applied. The necessary tags are applied in this script and I have tested that this script does not get stripped from the output. Do let me know if you find otherwise.

The Red Square

In the RoboHelp WYSIWYG editor you will see a red square where the script has been inserted. If you click on preview, the red square will not be displayed.

At this stage you will note there is no link in Preview. To see the link, you can amend the variable called "filename" from "targetfile" to "1targetfile" and click Preview again. This time the link will display although obviously it will not work as it is not pointing to a file. Don't forget to change it back to "targetfile".

The Script Explained

The logic behind the script is that if the variable "filename" is left unchanged and reads "targetfile", the first part of the IF statement will apply and that is to do nothing. If however the variable "filename" is changed, then because it is different to the filename specified in the IF statement, the ELSE part of the script applies and a link will be written into the topic. That link will be shown in the topic as the text defined in the variable "linkText" and will target the path and filename specified in the "filename" variable.

Bulk Changes

If your help has not yet been written, You could add this script to a template so that it automatically gets added to every topic.

If the help has been written, consider using a multi file find and replace tool to past the script into the same location in every source file.

If your topics were based on a template, you could add the script to the header or footer and then choose to apply it to all topics based on that template. You would need to consider whether that would impact on any other header and footer information in a topic based on that template.

Generating the Help

Just generate your help in the normal way. No links will be seen in the initial output and nothing will appear in any printed documentation you create from the source files. As the links are customer specific, this is the desired result anyway.

What the Customer Does

Using a text editor, in any topic where the customer wants to define a link, they open the output file that you have installed. I would recommend a text editor over an HTML editor so that no other undesired changes get made.

After locating the script they can make the following changes, noting the points covered.

<p class=Internal><script type="text/javascript"

language=JavaScript1.2>var filename = "targetfile";

  var linkText = "Click here for internal procedures"

     if (filename != "targetfile") {

     document.writeln("<A HREF="+filename+">"+linkText+"</A>");

     }</script></p>

  1. The variable "filename" must be amended to show the path and filename, including the extension. Forward slashes are required in the path. The file can be in any location, it does not have to be within the help structure. You can alternatively point to an intranet.
  2. The change must be made within the quote marks.
  3. There is no validity check on the links so they need to be tested. For that reason, customers may like to consider putting all the target files in one location so as to make creating the links consistent and less susceptible to error.
  4. The text for the link as defined in the variable "linkText" can be changed to whatever the customer might prefer. The text shown is just the default.
  5. The style tags highlighted green can be changed subject to the limitations of what javascript will accept. That is why I created a style class rather than specifying a colour.

The customer must keep a record of all files that they amend with the relevant details. This will be needed if the operation is to be repeated in the event of an upgrade.

Donations

If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.

Topic Revisions

Date

Changes to this page

09 Jan 2005

New topic.