Context-sensitive links to website output

[Jess77]

Hi,

My web output is to HTML5. My company has put this on a web site as opposed to a local copy inside the software. They would like to link that web site from the software. Furthermore, they would like those links to be context-sensitive to the module level. This means about 12 to 15 links.

I am having trouble figuring this out. Do I give the web developer the web address or the Default_CSH.htm#TopicID?

If the web address, what is the web site link?

When click from the TOC. the link is: [website name]/#filename.htm%3FTocPath%3D[TOC Book name]%7C_____1
When I click from a link within a topic: [website name]/#filename.htm

If the Default_CSH.htm#TopicID, how do I find out what comes before it?

I've always programmed help links from a local copy and am a bit stumped.

Thank!

[kwag_myers]

The internal links should remain the same, since the entire Help project is in one directory, i.e., self-contained. The context-sensitive part has to be done by the developer(s) since it is the application that is making the call for the corresponding page. Does that make sense? All you should need to do is create the Header File.

[Jess77]

When you say remain the same, do you mean "\Website Output\Default_CSH.htm#TopicID"?

The developers have given me a spreadsheet and asked me to enter the links for each window. I've never done it this way.

I know the topic that matches each window (for the most part), but I don't know what link to give the developer. We have tried programming

website URL#TopicName.htm

This link does open the right topic but does not work from inside the application.

I've generated the header file, but I don't know how to formulate a link from that either.

[kwag_myers]

When you say remain the same, do you mean "\Website Output\Default_CSH.htm#TopicID"?

No. Context-sensitive help does not impact internal links because you are calling a topic file within the same directory, which is the Content folder. It's like an inter-office phone call where you only have to dial the last few numbers. If you want to call to or from outside the office, you have to dial more numbers. Likewise, if you are linking from application to help you must have all the folders between where the application resides and the default.htm file.

I think what the developers are asking for is something like this (from an auto-generated alias file):

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<CatapultAliasFile>
    <Map Name="NEW" Link="/Content/BookmarkTest.htm" />
    <Map Name="NEW1" Link="/Content/Chapter_1.htm" />
    <Map Name="NEW2" Link="/Content/Chapter_10.htm" />
    <Map Name="NEW3" Link="/Content/Chapter_2.htm" />
    <Map Name="NEW4" Link="/Content/Topic.htm" />
    <Map Name="NEW5" Link="/Content/TopicGM.htm" />
</CatapultAliasFile>

I would auto-generate the Alias file and copy the links into the spreadsheet. I think that's what they are after.

[Jess77]

What you're saying is making sense. Thank you for the analogy about the phone system; that crystallizes what I've been seeing into a usable framework.

Is that code sample from the Alias javascript file produced during compile? The one here: Output\Data\alias.js? That's the closest thing I see in my project to your code. Is the compiled file what you mean by "auto-generated" or is there some other way to do it?

I have followed the instructions to create the alias file, then then assign identifiers for the *.h file but the exported header file doesn't look like your code. However, the javascript in the Output folder does, but it's more like this:

Code: Select all

'    <Map Name=\"NAME\" Link=\"Topic.htm\" Skin=\"LightHTML5\" ResolvedId=\"ID#\" />' +
	'    <Map Name=\"NAME\" Link=\"Topic.htm\" Skin=\"LightHTML5\" ResolvedId=\"ID#\" />' +
	'    <Map Name=\"NAME\" Link=\"Topic.htm\" Skin=\"LightHTML5\" ResolvedId=\"ID#\" />' +

[kwag_myers]

The Alias file has a .flali extension. Look in the Advanced folder of the Project Organizer (available from the View tab). You should see the Alias file, where you can right-click and select Open with > NotePad.

What I suspect is the developers are using the spreadsheet as their Alias file, so they need you to copy yours into theirs. Keep in mind that users will be calling for topics from the application, where ever that may be. Basically, you are giving the web browser step-by-step instructions from the application to the Content folder. If the application is installed on their hard drive, the links will have the entire URL. If the application is web-based and the Content folder is a sub-folder, then the links must start from (but not including) the location of the application.

[Paul Griffiths]

If possible (it is not always possible) try to resist the situation in which you are telling the developers what the context IDs (aliases) are. This introduces a dependency between you and the code that you are better off without.

When it comes to context sensitivity, I always ask that each form, page, tab (or whatever) in the application has an identifier (known as a context ID or alias) with the following mandatory characteristics:

• Uniqueness (no other form/page/tab can have the same ID)
• Unchanging (the ID must not vary from one build to the next)

And the following desirable characteristics:

• Discoverable (it is obvious what the ID is for any given form/page/tab)
• Automatic (the ID is generated programmatically - or at least algorithmically - rather than being assigned in an ad hoc manner)
• Human Readable (for example, not something like a UUID)

[Msquared]

If possible (it is not always possible) try to resist the situation in which you are telling the developers what the context IDs (aliases) are. This introduces a dependency between you and the code that you are better off without.

I'm interested in why you say this, so I suspect I may be missing something. You've obviously thought the process through very carefully, and I'm always keen to learn, so I'd love to know more . . .

As far as I understand, either the developers tell me what the context IDs are, so I can included them in my alias file, or I tell them the context IDs I'd like to use so they can use them in their application. Regardless of which way round it is done, there is a dependency between me and the code. One or the other option seems to be necessary, as it's how the application specifies what help page is required for what application page.

Or are you just saying that there is a dependency, but it's better for the developers to tell me what the context Ids are, rather than the other way round?

In fact, we have a scheme which I think meets all your requirements, but it still doesn't always work, and when it doesn't, I end up telling the developers what the id should be.

We agreed that the Id would be the name of the web page that the help topic corresponded to, without the .aspx. So page edit_report.aspx, say, has help topic ID edit_report. that's the value the developers use when they call the Flare-generated help. When I document the application, I can see the page address and know what help id to use, until I need more than one distinct help topic for the same application page. Sometimes it happens that the developers manage to use the same page address for several things that need distinct help pages. In that case, I have to ask them to separate the pages. They usually do this by rewriting the URLs, so they just look different in the web browser (I think that's what happens) but in that case, I just tell them what id to use for each, as their page naming convention didn't deliver what I needed.

And of course, should they rename a page (which they do occasionally) the whole naming convention falls apart, as they don't always realise there is an implicit dependency with the help. So I'd be quite happy to have an explicit dependency via a shared file, as then either they would get build errors, or I would, if anything changed.

So, what have I missed?

[Jess77]

@Marjorie - How do you control what the ID is? I thought the system assigned it.

My manager would like to have the links leave off the ".htm" at the end and I'm not sure how to do that at the moment. If I made my IDs like yours, would that deliver what he has asked?

[Msquared]

How do you control what the ID is? I thought the system assigned it.

Depends what you call the ID. Above, I was referring to the name, not the number.

I see that was a rather confusing assumption, but I find this area confusing. I have managed to get CSH to work, and I understand what I have done and why it works, but I'm not completely sure that I've done it the "best" way, or the way that Madcap intended it to be used. That's why I was interested in hearing what Paul recommends.

You can edit the header file and change the number that has been assigned if you want, although I wouldn't recommend it, simply because if you make a mistake, and reuse a number that has already been used, the results will be unpredictable.

Now for your second question

My manager would like to have the links leave off the ".htm" at the end and I'm not sure how to do that at the moment. If I made my IDs like yours, would that deliver what he has asked?

Sorry, I don't understand the question - that's probably because, as I say, I've made it work, but don't feel I understand the whole story.

[Paul Griffiths]

@Marjorie

The dependency isn't symmetric, because you need to get context IDs from the application, but the application doesn't get anything back from the help system. In principle, if all the conditions I mentioned are fulfilled, the developers could write the the code in January and you could write the help content in (say) August and it would work. But if you supplied the context IDs in August, the developers would have to retrofit them back into the code.

Also, I would say that the Uniqueness condition is incompletely met in your case, which is why sometimes you have to intervene to make it work. (However, since your help system obviously does work, perhaps my labelling this a mandatory condition was a bit strong.)

I must admit I hadn't considered how a shared file might introduce a mutual dependency that could highlight errors at build time; I'll need to think more about that.