TOC Auto-Sync and Custom Buttons

Report · Jul 03, 2009

I have two CHM files.

One contains English content, the other has French content. We're okay with having to change Windows display language to French in order to see the localized interface. It would be great to force it to French without having to do that, but it's better than nothing.

I have a handy dandy little javascript in my master page to flip between topics in the two CHM files. This is where my problems begin.

My flipping back and forth works great but the TOC does not auto-sync despite me having that checkbox enabled on the windows in both projects.

Then I added a Custom Button in each project (let's call it Cat in English and Chat in French) that points to a Redirect Topic (using the meta refresh method) to launch a Remote Topic. The redirection works great but again, the TOC does not auto-sync.

Getting back to my English/French setup... let's say I'm in the English project CHM, I change my display language to French, all of the interface buttons change to French except my Custom Button which is still "Cat". From what I've read, I'm guessing there's no way around this? I'd rather not have to put "Cat/Chat" for the Custom Button text or leave it as is where it will stick out like a sore thumb unless my display language always matches my language content.

Any suggestions or am I stuck with what I have?

Report · Jul 03, 2009

Hi there

I'm a bit confused to say the least.

You have two different CHM files, right? One in English and one in French.

I'm assuming your JavaScript allows displaying the matching topic from the other language? If so, isn't the matching topic simply replacing the topic that was there before? Here's where it gets real fuzzy. The TOC should already be synced to the topic. Are you saying it loses focus or something?

If there are two projects, one in English and one in French, each project would have its own Custom Button definition, right? So why not enter Chat in the French project?

Personally, assuming I'm correctly understanding this setup, I would think you are somewhat asking for trouble if you allow a click within a topic to change the language. I would think it to be a better solution just to keep the user inside the same help file. Choose the language at the beginning if you like, but remain in that language until the file is closed.

Cheers... Rick

Helpful and Handy Links

Report · Jul 03, 2009

You have two different CHM files, right? One in English and one in French.

Correct... one English, one French.

I'm assuming your JavaScript allows displaying the matching topic from the other language? If so, isn't the matching topic simply replacing the topic that was there before? Here's where it gets real fuzzy. The TOC should already be synced to the topic. Are you saying it loses focus or something?

My javascript determines the matching topic from the other CHM and changes the window location to the other topic. If I'm in the English help, on an English topic and click my French link, the link opens the corresponding French topic but my TOC never changes to the French TOC - it's still showing the English one.

If there are two projects, one in English and one in French, each project would have its own Custom Button definition, right? So why not enter Chat in the French project?

I would have Chat in the French project for the Custom Button... the confusion would be if I open the French CHM while my Windows display language is English or change my Windows display language to French and open the English CHM. In those scenarios, the interface buttons will be correct but the Custom Button text will match the content language rather than the interface language - that's when it will look wrong.

Personally, assuming I'm correctly understanding this setup, I would think you are somewhat asking for trouble if you allow a click within a topic to change the language. I would think it to be a better solution just to keep the user inside the same help file. Choose the language at the beginning if you like, but remain in that language until the file is closed.

Ah, but the end users want on-the-fly translation by topic without having to open the other CHM and find the topic all over again. This is CSH, so the user may very well have gotten directly to a topic and would like to see the other language immediately. Essentially, it should be as though the user closed the current CHM, opened the other CHM and located the exact same topic - instantaneously

Report · Jul 03, 2009

You have two different CHM files, right? One in English and one in French.

Correct... one English, one French.

Yay! I understood!

I'm assuming your JavaScript allows displaying the matching topic from the other language? If so, isn't the matching topic simply replacing the topic that was there before? Here's where it gets real fuzzy. The TOC should already be synced to the topic. Are you saying it loses focus or something?

My javascript determines the matching topic from the other CHM and changes the window location to the other topic. If I'm in the English help, on an English topic and click my French link, the link opens the corresponding French topic but my TOC never changes to the French TOC - it's still showing the English one.

Okay, so that's not really a synchronization issue. In my view, synchronization means expanding and highlighting the page in the TOC so the user may see where they were.

If there are two projects, one in English and one in French, each project would have its own Custom Button definition, right? So why not enter Chat in the French project?

I would have Chat in the French project for the Custom Button... the confusion would be if I open the French CHM while my Windows display language is English or change my Windows display language to French and open the English CHM. In those scenarios, the interface buttons will be correct but the Custom Button text will match the content language rather than the interface language - that's when it will look wrong.

Gotcha.

Personally, assuming I'm correctly understanding this setup, I would think you are somewhat asking for trouble if you allow a click within a topic to change the language. I would think it to be a better solution just to keep the user inside the same help file. Choose the language at the beginning if you like, but remain in that language until the file is closed.

Ah, but the end users want on-the-fly translation by topic without having to open the other CHM and find the topic all over again. This is CSH, so the user may very well have gotten directly to a topic and would like to see the other language immediately. Essentially, it should be as though the user closed the current CHM, opened the other CHM and located the exact same topic - instantaneously

I'm thinking that perhaps a possible answer would involve using an HTML Help Shortcut control to launch a new instance of the viewer. Open the CHM for the correct language and display the relevant topic. What I think you will have issues with here is that the CHM viewer adapts to the language of the operating system I believe. So I'm not sure the TOC will know how to dynamically interpret you want French or English. Maybe it will based on the language choice in RoboHelp. But I'd be surprised if it worked that way.

Hopefully Pete Lees will see this thread and pop in to offer some other insight.

Pffft Pffft tap tap tap... is this thing on? Earth to Pete. Calling Pete. Pete, are you there and monitoring this frequency? ... - - - .... ---.--

Cheers... Rick

Helpful and Handy Links

Report · Jul 03, 2009

Hi, MaritimeGirl, Rick,

Yes, I believe that Rick is correct: you'll probably want your script to execute an HTML Help Close control (to close the current Help window) and execute an HTML Help Shortcut control (to open the other Help file). This posting in the microsoft.public.helpauthoring newsgroup may give you some ideas:

http://groups.google.com/group/microsoft.public.helpauthoring/msg/696d0f2c74ea4f49

Or I may be able to work up some sample Help files, if you think it could be useful.

On the localisation of the text labels for the custom toolbar buttons, I don't think there's much you can do about that. These text labels are set at compile time, obviously, and can't be altered dynamically at run time. Is there a language-agnostic term that you can use in both Help windows? Could you make do without any button labels at all?

Pete

Report · Jul 03, 2009

Hi,

I just tried what you wrote in the post at that link and boy, oh boy, the wysiwyg editor is having an absolute field day changing what I type

To test, I put just the shortcut object in my Master Page... it now brings up a window saying "Cannot open the file: ms-its:MyFrench.chm" within a window entitled Help. MyFrench.chm is in the same folder as MyEnglish.chm. Inside topics within subfolders, wouldn't the path not know where the other .chm would be? Plus, as mentioned in my previous post, I'm assuming my href would have to alter the param value to include the destination topic at runtime.

As for the button labels, using a generic word might work but that was going to be my next question. For some odd reason, in "Tri-pane Tabs and Windows" on the Window Properties window, I have the option to turn things on and off such as Glossary, Search Tab, etc. but TOC & Index are paired. I want to turn off/rename the native Index because my Custom Button would be called Index and point to a different CHM. If I can't turn off/rename the native Index, I'd end up with an Index tab and an Index button that point to two different things - a wee bit confusing

I can "break" the native Index by going into Advanced Properties and putting garbage text in the textbox for Index - it then magically disappears when I generate and look at my .chm. I thought perhaps I could go into Project Settings>Language>Advanced and on the LNG File tab, change Index=Index to be Index=Something and that I'd see that as the tab title when I regenerated... no such luck.

Report · Jul 03, 2009

Is it possible for you to rework your Master page javascript so that you can have all the English and French topics in one .chm? It might be a little kinder and quicker than opening and closing .chms.

This gives you tab names that are sensitive to the PC language; custom buttons labeled in one or the other (but at least you shouldn't need two Index buttons); and a single truly ginormous TOC that will probably synch. Alas, it will also give you a truly ginormous Index, but that's life/c'est la vie.

My rationale for this is that, since bilingual help is obviously important for your customers, making the two languages visible may not frighten them. This is all in that foggy realm of "usability," and I wouldn't recommend it for most help systems, but this sounds like a distinctive situation.

Report · Jul 06, 2009

I agree with Elisa that switching between the two Help files may be distracting to your users. However, if this is something that you're still keen to do, you can achieve it by linking all your topics to a JavaScript (.js) file that contains the function below.

function SwitchLanguage(TargetHelpFile,TopicFile) {

// Construct an HTML Help Close control with which to close the current Help
// file.

   Close =    "<object id='Close' classid='clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11'>" +
              "<param name='Command' value='Close'>" +
              "</object>";

// Add the Close control to the current topic, and click it.

document.body.insertAdjacentHTML("BeforeEnd",Close);
document.Close.hhclick();

// Construct an HTML Help Shortcut control with which to open the required topic
// in a new Help window.

   Shortcut = "<object id='Shortcut' classid='clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11'>" +
              "<param name='Command' value='Shortcut'>" +
              "<param name='Item1' value=',hh.exe,ms-its:" + TargetHelpFile + "::/" + TopicFile + "'>" +
              "</object>";

// Add the Shortcut control to the current topic, and click it.

document.body.insertAdjacentHTML("BeforeEnd",Shortcut);
document.Shortcut.hhclick();

}

Then you code the hyperlinks between the two files like this:

<a href="JavaScript:SwitchLanguage('french.chm','topic1.htm')">Text that user clicks</a>

where "french.chm" is the name of the target Help file, and "topic1.htm" is the file name of the required topic.

There is a lot of scope for enhancing the script, especially when the file names of the topics in the French Help file are identical to those in the English file. I've illustrated this in the sample files that I've uploaded here:

http://rapidshare.com/files/252570423/Help_Sample.zip.html

In these examples, the script determines the names of the current Help file and topic file and then creates a link on the fly to the equivalent topic in the second Help file. Would be interested to know if this goes some way towards meeting your needs.

Pete

Report · Jul 06, 2009

One all-encompassing CHM, while my personal preference, is not permitted for this project. The original WinHelp documents were converted to separate projects and must remain separate - not my choice. If I wanted to get all wild and crazy, I'd go so far as using the conditional tags and store English and French topics combined - I can dream!

Unfortunately, my English and French files do not share filenames in any predictable way so that's why my generic javascript in my Master Page must determine the matching page at runtime based on the currently viewed topic.

Getting back to the results of testing using the object. As I previously mentioned, I get "Cannot open the file: ms-its:MyFrench.chm::/mytopic.htm" when I use it. If I use a simple window.location.href='MyFrench.chm::/mytopic.htm' the content frame changes to the topic I want, but of course, as we know, my TOC doesn't sync. So, changing my javascript to dynamically embed the object code won't get me any further ahead since I still get that error. Any ideas?

Report · Jul 07, 2009

Well, it turns out there's nothing wrong with the object code and that the "Cannot open the file:ms-its:MyFrench.chm" is RoboHelp being hard to get along with. If I open the CHM from outside of RoboHelp, lo and behold, the link to the external CHM opens successfully.

So, that leads to my next question - a relatively simple one - is if I want to keep my original CHM open when I launch my external one, how do I set an X,Y coordinate so that I can still see a bit of my original CHM? I tried creating a new window with the TOP/LEFT values different than my original window and set that in the window param value but it still opens in exactly the same position.

Any suggestions?

Report · Jul 07, 2009

If you've selected the option to "Remember Window Size And Position", try turning it off. The Help viewer may just be retaining the position to which you last moved it.

Pete

Report · Jul 08, 2009

I took a look at my window defintion and I didn't have that option activated.

Report · Jul 08, 2009

What happens if you rename or delete the file hh.dat in the hidden folder %UserProfile%\Application Data\Microsoft\HTML Help (so, typically, C:\Documents and Settings\MaritimeGirl\Application Data\Microsoft\HTML Help)?

This is the file in which Windows stores the most recent size and position of every Help file that you open. By renaming or deleting the file, you erase this history and force Windows to open each Help file with its default dimensions and position. So, if your French Help file continues to be in the wrong position, you can be sure that the window settings in your Help project are wrong.

Pete

Report · Jul 09, 2009

The hh.dat wasn't the culprit.

It turns out that setting the window on the Shortcut Control is pointless. I had to set the top/left on the window in the second CHM file. While it's not exactly what I was hoping, to open at an offset from the original, it should suffice. It'll just look a little bit odd if I open the English CHM from the French CHM and it opens higher and to the left from the French CHM

Report · Jul 03, 2009

Well, I just tossed around the HTML Help Shortcut control and my waterlogged Friday brain must be missing something. I used this as a guide:

http://www.hypertexas.com/RHTutor/OpeningDocsFromCHM.htm

I inserted a new one into my English project's Master Page and gave it the name of the French CHM, leaving it as the default button with label Shortcut. I compiled, launched, clicked the button. Nothing happened. No error, just nothing. I'm not sure exactly what and where it was supposed to open but if it was supposed to launch the other CHM separately, I wouldn't want my original CHM still open.

Now, remember, this has to go in my Master Page because each topic has to dynamically determine the corresponding topic in the other language. If the HTML Help Shortcut worked, wouldn't that mean that I'd have to change my current javascript to alter the param value for Item1 to point to the correct topic?

Adobe Community

TOC Auto-Sync and Custom Buttons