mshcMigrate.exe‎ > ‎Migrate‎ > ‎Migrate Options‎ > ‎

h3m.js Script File

Migrate Option: Include h3m.js Fix Script 

The h3m.js script was developed by Helpware to fix some bugs and shortcoming in HV 1.0.

When the "Include h3m.js Fix Script" option is checked the migrate command does the following...
  • Adds the h3m.js file to the root of the project. 
    (Note: No action is taken if it already exists in the project. Maybe you made some modifications to the file).
  • Adds a script include statement to the end of each topic (just above </body> tag).
  • Migrate no longer strips bookmarks from links to other topic files (since they will now work).
NOTE: Remember for any script to work, SelfBranded=true is required.


About the h3m.js Script

Background 

The way we link between topics in HV 1.0 is via the brief form of the Page Id link  <a href="ms.help?id=xxxxx"> or <a href="ms-xhelp:///?id=xxxxx">. 

Agent expands this to something like <a href="http://127.0.0.1:47873/help/0-21260/ms.help?method=page&id=xxxxx&product=VS&productVersion=100&topicVersion=100">. 
Try doing a browser "view source" and that's what you will see.

If you add a book mark to the link <a href="ms.help?id=xxxxx#Bookmark">
Agent expands this to <a href="http://127.0.0.1:47873/help/0-21260/ms.help?method=page&id=xxxxx#Bookmark&product=VS&productVersion=100&topicVersion=100">.
Which fails, since a bookmark must be at the end of the link.

H3m.js Script Fixes

Note that the following script fixes made by h3m.js wont show in a browser "view source" since script alters the HTML memory copy not the HTML source file.



Script Fix 1 - Bookmark moved to end.

The script allows you to use links like <a href="ms.help?id=xxxxx#Bookmark">.
Agent expands this to <a href="....?method=page&id=xxxxx#Bookmark&product=VS&productVersion=100&topicVersion=100">
and our script moves the #bookmark to it's correct position at the end of the link
 <a href="....?method=page&id=xxxxx&product=VS&productVersion=100&topicVersion=100#Bookmark">. 



Script Fix 2 - Fix &embedded=true position.

Notice that HV 1.0 often appends '&embedded=true' to the end of the URL to control the visible state of the embedded navigation pane. Unfortunately this action turns a working bookmark link into a broken link. 

So the script takes <a href="......&topicVersion=100#Bookmark&embedded=true">
and makes the correction  <a href="......&topicVersion=100&embedded=true#Bookmark"> which is a valid link.



Script Fix 3 - Remove target from local bookmark links.

HV 1.0 Agent takes <a href="#Bookmark"> and converts to <a href="#Bookmark" target="_blank">.
The script fixes this bug by removing the target attribute from all local bookmark jumps.



Script Fix 4 - Catalog Independent Links.

Some times you need to use a full Page Id or F1 link etc. However then your link is hardwired to the a certain catalog.

When a topic uses the h3m.js script, catalog independent links like the following are allowed...
<a href="ms.help?method=page&id=xxx&product=*&productVersion=*&locale=*&embedded=*">
The script replaces the *s (asterisks) with correct values extracted from the current document URL.

You can also use an ! (exclamation mark) with embedded parameters ...&embedded=!"> to toggle the nav pane's visibility state.

Examples:

If xx is the id of the current page then...
  • Open the embedded navigation
    <a href="ms.help?method=page&id=xxx&product=*&productVersion=*&locale=*&embedded=false">
  • Close the embedded navigation
    <a href="ms.help?method=page&id=xxx&product=*&productVersion=*&locale=*&embedded=true">
  • Toggle the embedded navigation state
    <a href="ms.help?method=page&id=xxx&product=*&productVersion=*&locale=*&embedded=!">

How to use h3m.js

If you are using mshcMigrate, simply check the "Fix Script" option before running the migrate command.

If you want to add h3m.js by hand then add this line to the <head> section of each topic file. 

<head>
<script type="text/javascript" src="h3m.js"></script>
</head>

Then add this call at the end of each topic just before the </body> tag.

<script type="text/javascript">
<!--
h3m_fix();
-->
</script>


Make sure the topics are marked SelfBranded=true otherwise Agent simply removes your script.

<!-- $h3m:false -->

Please this near the top of a topic file if you want to stop Migrate from adding h3m.js script to a topic file.

Comments