When your URL/page call contains special characters

[ktbCA57]

We are having an issue with our context sensitive help mapping. I have contacted Tech Support and they came up with one idea and we are hoping that works.. but we are unable to test it until our engineers have time to actually implement the help into our application. I thought I'd ask here in case someone else had a similar issue and has a proven solution. I am not happy to wait until the help is implicated to have to announce that we cannot have CSH.

So, our app urls for each page in the app has a typical web page structure - something that looks like this: abcd.efgh.companyname.appname/bookmark

However, when I put anything that looks like that into the Alias file table to start mapping the topics in the help to the pages with addresses that look like that, I get an error about these "special characters" not being accepted. If we change the url to have underscores instead - something like this: abcd_efgh_companyname_appname_bookmark, then there are no errors, but we know it won't work because that's not the real name of the application page.

Madcap tech support suggested setting up the csh using the header file, then use the value assigned in the header file to map the topics in the alias file. I have no issue doing that, but we have no way to test this set up method as the help is not implemented yet.

Has anyone else come across this issue and found a resolution? Will the header file solution work? I know the issue seems complex and difficult to explain, so I hope I've described the issue well enough.

[NorthEast]

I don't quite understand the problem, or why Tech Support suggested using values instead of identifiers.

The CSH identifiers that you use in Flare can be absolutely anything you want (that has valid characters), but they have nothing to do with the URLs that you use for your app. You don't need to change any URLs in your app.

So your app page abcd.efgh.companyname.appname/bookmark can have a link to the help that uses the CSH identifier "cheeseburger", or whatever you want.

Now, you might want to use a CSH identifier name that more closely matches the name of the app page it was called from. So in your case, maybe the CSH identifier could just be "bookmark" if that's a unique page in your app, or maybe it could be "appname_bookmark", or whatever is appropriate. The key thing is that the CSH identifier name must be unique.

In one of our products, each app page has help CSH link, but the link is not hard-coded and the app generates the link based on its current page URL.
So the app page company.product.co.uk/app/module/add-new-thing will generate its help CSH link as company.product.co.uk/help/help.htm#cshid=app-module-add-new-thing.
So the page code is taking the relevant part of the app URL after the domain - app/module/add-new-thing - and is using that to generate the CSH identifier app-module-add-new-thing (replacing the slashes with hyphens). It then inserts that identifier after the cshid= part in the help link URL.

Then my job is just to make sure I set up the alias file in Flare to include an identifier for each page in the app, and link those to the appropriate help topic in my project.

[ktbCA57]

Thank you so much for your response... I think what you are saying IS what Tech Support was telling me. I set up the header file with the url and a value. Then I go to the Alias file and map the identifier using the same value - see image I created to sort of show what tech support showed us to do... but they weren't for sure this would work as we have no way to test it currently.

I'm hoping this is a bit clearer than my original posting and replicates more of what you are saying. I don't think the value matters - if it's a number or a name (but i like your idea better than the number) as long as it's unique and matches between the alias and header files.

alias vs header.png

Thank you again for your assistance!

[NorthEast]

Hmm... it's still not very clear to me, and what you've put in the screenshot is not how it works.

The header file contains an identifier (the text string) and a value (number).
#define my-identifier 1000

You use Flare's alias editor to map each identifier to a topic in your help. It shows you a list of identifiers from your header file(s), and you map them to topic. So in Flare's alias (.flali) file, it'll have an entry like this:
<Map Name="my-identifier" Link="/Content/My-Topic.htm" />

You can't do what's in your screenshot for two reasons:
* The identifier names in the alias file will need to match the name in the header.
* The identifier in the header has invalid characters ("." and "/"). You should format it with underscores (or hyphens) like it shows in your alias file.

When you make a CSH call from your app, you can use either the identifier (text string) OR the value (number). Generally, it'd make most sense to use the identifier. I think values only exist to support legacy help formats, and if you're not using them for CSH then the actual values don't matter.
* The identifier names must be unique.
* Values don't need to be unique, but should be if you actually intend to use values in your CSH calls. Flare will warn you if values are not unique.

So obviously your app needs to use the same identifier names that you've set in your alias (and header) file. So your app needs to use identifier names with the underscores (or whatever you end up using).

[ktbCA57]

I'm also still not clear.. I'm so sorry... if they are called different things in the alias and in the header, how do they get mapped? Also, I cannot change anything about the app identifiers. As per this message,

So your app needs to use identifier names with the underscores (or whatever you end up using)

. I cannot ask the developers to change anything. They are only agreeing to implement this if I do the heavy lifting.

In your previous message, you said

You don't need to change any URLs in your app.

I'm sorry I'm so confused.

[NorthEast]

if they are called different things in the alias and in the header, how do they get mapped?

It's the identifier name itself that is linking the information in the header file and alias file. So the identifier name needs to be the same in both.

It is a bit confusing, because there are two files involved when you set up the CSH in a project.
When you open the alias editor, it is actually showing you information taken from both the alias file (.flali) and the header file.

The alias editor initially shows a list of identifiers and values - all of which is taken from the header files.
The alias editor doesn't actually add anything to the alias file until you start linking identifiers to topics.

Also, I cannot change anything about the app identifiers. As per this message,.
...
I cannot ask the developers to change anything. They are only agreeing to implement this if I do the heavy lifting.

I understand the URL of the app itself can't change, you'd still open your app at https://companyname.appname.com/bookmark or whatever.

But your app URL has nothing to do with the identifiers that you use in a CSH URL link to your help. Assuming you are linking to your help using a URL, then you need to include the identifier name in the URL, and that identifier name can't include reserved characters like "." or "/".

So your app page might have a link to the help like this, where the identifier is in the part "cshid=xxx":
https://companyname.appname.com/help/Default.htm#cshid=companyname_appname_com_bookmark

But the link to your help can't use an identifier with invalid characters:
https://companyname.appname.com/help/Default.htm#cshid=companyname.appname.com/bookmark

What you use for the identifier names is whatever you agree with your developers.

[ktbCA57]

Thanks.. I'm just re-reading the info about headers vs alias in the Madcap CSH guide.. and it appears that the devs can set up to call either identifiers OR the value numbers... so I think for us that's the way to go so we don't have to deal with underscores or periods. Does that make sense?

[NorthEast]

Personally, I wouldn't ever choose to use values because they're not readable. Identifiers are readable, which makes a big difference whenever you have to deal with them. For example, it's way easier to check what topic the identifier "companyname_appname_com_bookmark" should link to, than it is to check what "1044567" should link to.

Also, in our apps, the identifier is generated by the app - as described in my first post.
Therefore, it just makes more sense for the app page companyname.appname.com/bookmark to have a CSH link that uses the identifier "companyname_appname_com_bookmark" rather than the value "1044567".

Dealing with underscores or periods shouldn't be a problem - it wasn't for us. It's also way easier than using a system of arbitrary numbers that have no correlation with your app pages.