External File Links in HTML Help

HM5 served us well, now its time has come and it has been replaced... If you have HM5 questions, please post them here.

Moderators: Alexander Halser, Tim Green

Post Reply
Leonard Mann
Posts: 11
Joined: Fri Aug 06, 2010 5:48 pm

External File Links in HTML Help

Unread post by Leonard Mann »

Our HR Manager has requested some sort of document control functionality from our ERP system.
The objective is simple enough.
Create a hierarchical structure of the documents based on content.
ie.
Workplace Procedures
Plant Procedures
Safety Document.pdf
Equipment Document.pdf
Office Procedures
Hiring Policies.pdf
Overtime Policies.pdf
....

All the documents will be converted to PDF.
However, the documents may reside in various directories on the server.

At first glance it would seem that H&M5 would do an excellent job of producing a HTML Help file that the HR manager could maintain.
I would then just call the Help File from the ERP system.

I have not been able to get the 'File Link' option to work properly. The link will appear in the Help file but nothing happens when you click on it.
The note in the File Link screen that says WIndows XP SP2 blocks External File links in HTML Help indicates that this cannot be done.

Is there a way of accessing File Links in different directories in HTML Help.
If not is there another way that H&M5 can accomplish this task?

Thanks,
Leonard
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: External File Links in HTML Help

Unread post by Tim Green »

Hi Leonard,

The problem here is that the Microsoft HTML Help viewer has a bug that makes it unable to understand relative paths. For all file references it needs a complete absolute path including a drive letter. If you can provide this it will work. You just need to select Internet Link instead of File Link and enter the entire path like this, with the file:/// protocol selector and "%20" to replace any spaces in the path:

Code: Select all

file:///D:\Documents\My%20HelpAndManual%20Projects\ChangeLog.pdf
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.
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: External File Links in HTML Help

Unread post by Tim Green »

Hi Leonard,

Update: I've modified Rob Chandler's script for accessing external files so that it also processes relative paths. This will enable you to create file link references with relative paths that will work in your CHM files. Note that these links should ONLY be used in CHM, they won't work in WebHelp so you should exclude them there with conditional text tags. The script itself is already tagged so that it will only be included in CHM.

First, here's the script:

Code: Select all

<IF_CHM><script type="text/javascript">
    function parser(fn) {
    var X, Y, sl, a, ra, stepsUp, path, pathSteps, link,p,w;
    ra = /:/;
    a = location.href.search(ra);
    if (a == 2)
    X = 14;
    else
    X = 7;
    sl = "\\";
    Y = location.href.lastIndexOf(sl) + 1;
    stepsUp = fn.match(/\.\.\\/ig);
    path = location.href.substring(X, Y);
    if (stepsUp) {
       fn = fn.replace(/\.\.\\/ig,"");
        pathSteps = path.match(/(\\.*?)(?=\\)/ig);
        p=""; w=pathSteps.length-1; 
           for (var q = 0; q < stepsUp.length; q++) {
           path = path.replace(pathSteps[w],"");
           w--;
            }
        } 
    link = 'file:///' + path + fn;
    location.replace(link);
    }
</script></IF_CHM>
Copy this and paste it into your HTML Page Template, directly before the closing </head> tag. The template is in Project Explorer > Configuration > HTML Page Templates > Default. You need to select the source code tab to do the editing and leave it selected. Switching back would delete your changes. If you are using a skin you need to add it to the skin and not to your project.

Then to create your links select the Script Link option and enter your links like this:

Example 1: A relative path pointing to a directory below the CHM location:

Code: Select all

javascript:parser('Manual\\mywordfile.docx')
Example 2: A relative path pointing to a directory above the CHM location:

Code: Select all

javascript:parser('..\\..\\mypdf_file.pdf')
IMPORTANT INSTRUCTIONS
  • You must enclose the path between javascript:parser(' at the beginning and ') at the end. Note the single quotes. It won't work if you use double quotes!!
  • All slashes in the path MUST be backslashes and must be DOUBLE -- i.e. for every backslash in the path you must write TWO backslashes. This is also essential, it won't work otherwise!
If you observe these rules it should work fine for relative paths on the current drive. Don't use this for paths to files on other drives, those must be entered as absolute paths as Internet links, using the method I outlined in my last post.
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.
Leonard Mann
Posts: 11
Joined: Fri Aug 06, 2010 5:48 pm

Re: External File Links in HTML Help

Unread post by Leonard Mann »

Thanks Tim,

The Internet Link looks like it will work just fine for me.
It appears to work if I use:
file:///H:\AppHelp\OTPolicy.pdf
or
file:///\\ServerName\AppHelp\OTPolicy.pdf.

I did have a problem with the Script to use Relative Paths, though.
However, I think it has something to do with my setup.

I get a Script Error on the URL:
mk:@MSITStore:C:\AppHelp\AppHelp.chm::/Documents.htm

I am not sure where the 'mk:@MSITStore' in the above URL comes from.
Its not a big deal as, I said, the Internet Link will work just fine for me. Although, It might be nice get the relative path working.

Thanks for the Help.

Leonard
Leonard Mann
Posts: 11
Joined: Fri Aug 06, 2010 5:48 pm

Re: External File Links in HTML Help

Unread post by Leonard Mann »

Hi Tim,

I figured out the problem with the Script.

I forgot that I was using one of the Skins when I published the Project.
I put the code you suggested into the skin as well and all works fine.

Thanks Again,

Leonard
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: External File Links in HTML Help

Unread post by Tim Green »

Hi Leonard,

Yes, when you use skins you need to make any template changes in the skins. Note also that if there are any spaces in the path you should replace them with "%20" (without the quotes). For example, if your relative path is

Code: Select all

\My Files\PDF Files\thisfile.pdf
you would enter:

Code: Select all

javascript:parser('\\My%20Files\\PDF%20Files\\thisfile.pdf')
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.
chris_martin
Posts: 26
Joined: Fri Sep 24, 2010 4:51 pm

Re: External File Links in HTML Help

Unread post by chris_martin »

Hi Tim. I'm a little late to this party, but I'm wondering how I can mess with the code to get these external files to open in new windows?
chris_martin
Posts: 26
Joined: Fri Sep 24, 2010 4:51 pm

Re: External File Links in HTML Help

Unread post by chris_martin »

Actually, let me elaborate a bit: how can I get PDF files to open in a new window?
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: External File Links in HTML Help

Unread post by Tim Green »

Hi Chris,
chris_martin wrote:Actually, let me elaborate a bit: how can I get PDF files to open in a new window?
To do this we need a little trickery, because we need to create a link on the fly that will insert the absolute path and open the PDF in a new window. First comment out location.replace(link); at the end of the script and replace it with return(link);, like this

Code: Select all

        // location.replace(link);
        return(link);
        }
Then add the following little function directly after the end of this code:

Code: Select all

   function updateLink(obj,linkID){
   obj.target='_blank';
   obj.href=parser(linkID);
}
The complete end of your script should now look like this:

Code: Select all

// location.replace(link);
        return(link);
        }
   
   function updateLink(obj,linkID){
   obj.target='_blank';
   obj.href=parser(linkID);
}
    </script></IF_CHM>
Now to create your script link you need to enter your code in the script box of the script link like this:

#" onclick="updateLink(this,'demo.pdf')

Be VERY careful to get this right: The only thing you are allowed to change is the filename in red, and there should be no spaces in the filename. Note that there is NO quote at the beginning or the end. There is one double quote after the first # character and another one after onclick=, and the filename inside the brackets is enclosed in single quotes. Every single detail of this must be exactly right for it to work.

This works because Help & Manual inserts this code between quotes in the href= property of a link, so that the resulting link actually looks like this:

Code: Select all

<a href="#" onclick="updateLink(this,'demo.pdf')">Link Text</a>
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.
chris_martin
Posts: 26
Joined: Fri Sep 24, 2010 4:51 pm

Re: External File Links in HTML Help

Unread post by chris_martin »

Worked like a charm! Thank you!
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: External File Links in HTML Help

Unread post by Tim Green »

Hi Chris,
Worked like a charm! Thank you!
A word of warning on something I just discovered: If you are also generating WebHelp from the same project you may discover that your topic pages are empty. This is because Help & Manual's conditional tags -- i.e. <IF_CHM> ... </IF_CHM> sometimes trip up on JavaScript code that contains certain special characters. The way to avoid this is to put the JavaScript in an external document and refer to it in the place in the head section where you want to use the code:
  1. First cut out all the code between the <script> and </script> tags (without the tags!) and save it in your project folder as a plain-text file called chmlink.js
  2. Add chmlink.js to the Baggage Files section of your project.
  3. Replace the <IF_CHM><script>...</script></IF_CHM> section in your template with this line:

    Code: Select all

    <IF_CHM><script type="text/javascript" src="chmlink.js"></script></IF_CHM> 
That's it, then it will work in both CHM and WebHelp -- but you will have to use conditional text to insert alternative links for the WebHelp version, of course, because this script is for CHM only. 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.
chris_martin
Posts: 26
Joined: Fri Sep 24, 2010 4:51 pm

Re: External File Links in HTML Help

Unread post by chris_martin »

Hi Tim. Thanks for the warning! Hasn't been a problem so far...
Richard Shaw
Posts: 16
Joined: Fri Sep 04, 2009 3:14 pm

Re: External File Links in HTML Help

Unread post by Richard Shaw »

Hi Tim,
having managed to lose the parser function from my help project, I came back to this topic to restore the functionality. Having restored it to the default topic, I found I had a load of compilation errors, caused the the slash in the closing IF_CHM tag being the wrong way round.

</script><\IF_CHM>
_________^

It's only wrong in the first example, which unfortunately was the one I copied.

Thanks,
Richard
User avatar
Tim Green
Site Admin
Posts: 23153
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: External File Links in HTML Help

Unread post by Tim Green »

Hi Richard,

Sorry about that -- nobody noticed it up to now. I've corrected it in the original message.

BTW: The CHM skins in the Premium Pack for Help & Manual 6 now have this functionality built in. 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