Variable in feedback e-mail subject line

[Tim Frost]

I wanted to put our build version, which is already in a variable when we build the help, into the subject line of the 'feedback' e-mail, so that I can tell whether the e-mail refers to an ancient or recent version. Just dropping a variable into the subject text worked fine, but it means that I have to upload all the topics every time the version changes, because the expanded variable is written into every topic HTML file.

Have I overlooked a better way of implementing this, so that I can go back to only uploading the changed topics?

[Tim Green]

Hi Tim,

I'm afraid that's the only way at the moment because Help & Manual can currently only parse variables on publishing if they are in the template or a topic. To have the change be global it would be necessary to parse them in an external file that was then referenced in all the templates or topics. This will be possible in Help & Manual 7, because then all user-defined variables will be written to an external file that can then be referenced everywhere.

To do this now you would have to set this up yourself:

1) First locate the hmTopicVars.js file in the baggage of your skin, and locate this line:

Code: Select all

mailsubject: "<%FB_SUBJ%> <%TITLE%> - <%TOPIC_HEADER_TEXT%>",

Change it to:

Code: Select all

mailsubject: customMailSubject + " <%TITLE%> - <%TOPIC_HEADER_TEXT%>",

2) Then create a file in a text editor containing only this line:

Code: Select all

customMailSubject = "The text you want to use globally goes here"

Save this file with the name "customUserVariables.js" and add it to the skin baggage. Make sure that both references to customMailSubject are EXACTLY the same!

3)Then open the HTML Topic Template > Default in the skin locate the following lines of code:

Code: Select all

<script type="text/javascript" src="jquery.scrollTo-min.js"></script>
<HMINCLUDE:hmTopicVars.js>

4) Now add the following line directly before the <HMINCLUDE:... line:

Code: Select all

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

The result will then look like this:

Code: Select all

<script type="text/javascript" src="jquery.scrollTo-min.js"></script>
<script type="text/javascript" src="customUserVariables.js"></script>
<HMINCLUDE:hmTopicVars.js>

Here too, make absolutely sure that the customUserVariables.js reference matches the name of the file you created EXACTLY. Once you have done this, you can change the text that appears at the beginning of the mail subject line globally by editing the definition in the customUserVariables.js file.

Important: You have to upload everything once after making this change, of course. Otherwise the old code will still be in the topics you didn't upload.

[Tim Frost]

As usual, a clear explanation and an excellent result!

[Tim Frost]

After a couple of weeks use I have noticed that the file in the skin baggage is not automatically copied to the output folder when I build. My FinalBuilder project writes a new file into the baggage folder, but the file in the outut folder is unchanged and no new customUserVariables.js has been uploaded since the first one. I did receive some feedback messages and saw an old version number, but assumed it was coming from a cache or the user's local help.

Is there a way to make the copy happen automatically in an H&M build if the baggage is newer? If not, I can easily add a couple of extra file writes in FB.

[Tim Green]

Hi Tim,

By default, all the files in the skin baggage are copied to the output folder when you publish. Make sure that you have not set any build options on the file that could prevent it from being exported. Right-click on the file and check the settings in Include in Builds.

I know this sounds silly, but also check that the skin referenced in your build script is the same copy as the one you are editing.

[Tim Frost]

Your 'silly' check led me to what I have misunderstood. My main project baggage files are listed as "Baggage (*.*)" and seem to consist of a folder-full of files, including the one I update each build. My skin shows the same files but without the "(*.*)". So I assumed that because my customUserVariables.js file appeared in both lists, it would pick up the same file. If there is a separate place for 'real' baggage files in a skin, where I could drop another copy, I have not yet discovered it! But it does not really matter because I have now changed the FinalBuilder project to drop the updated file in the output folder after the build, and that works just as well.

Nevertheless in either list of baggage files it would be nice to have a right-click or hover option which showed either the full pathname where the file is located, or in the case of skins some note of the fact that it is inherited from somewhere else and not a real file that will be copied (if that is what is the explanation!).

[Tim Green]

Hi Tim,

A skin is really a zip archive with the extension .hmskin instead of .zip. It contains everything it needs in that archive, including all the baggage files. To add a file to the baggage in your skin you need to open the skin in Help & Manual, just as you would open a project. Navigate to the Baggage section, then select Add File in the Project tab to add or update a file.

So I assumed that because my customUserVariables.js file appeared in both lists, it would pick up the same file.

No, absolutely not! The whole point of skins is that everything they contain replaces all matching resources in your project. If you do your editing in the copy of the customUserVariables.js file in your project and your skin contains a file of the same name, that will have no effect whatsoever. It will be just the same as if you had done no editing at all. You MUST edit the version in the skin if you want results. The reason for this is that the skin always has absolute priority: Everything in the skin overwrites any matching resources from your project. So your project version of customUserVariables.js does get written, but at the end of the publish process it then gets overwritten by the version from the skin. And if you haven't edited that, your edits are lost.

The same principle applies to the baggage generally: It is always written last. This gives you the opportunity to create your own version of any of the files that Help & Manual generates automatically, among other things. You just need to add your own version to the baggage, and it will then overwrite Help & Manual's version on publishing. By the same token, if you have versions in both your project baggage and your skin baggage, the skin version will win out and will be the version that gets used.

If there is a separate place for 'real' baggage files in a skin, where I could drop another copy, I have not yet discovered it! But it does not really matter because I have now changed the FinalBuilder project to drop the updated file in the output folder after the build, and that works just as well.

That's a good choice if you are changing the file often, because then you don't need to re-add it to the skin every time you change it.

[Tim Frost]

Thanks; this leads me to the source of my confusion. I have not used a project zip file (hmxz) for several years, but I still had firmly in my head that a project and a skin are just two congruent manifestations of the same concept, as you regularly remind us. So it is not that the skins operate as I did not expect, it is the HMXP project that is 'different' because the baggage files are not embedded in it, allowing me to drop new baggage files and have them published to the output folder automatically. If anyone else had the same mental issues that I did, I hope this conversation awakens them! However I will stick with dropping the file in the output folder: the version number changes every couple of weeks.

[Tim Frost]

I have just realized that my solution no longer works with HM7 in respect of building EXE books. Previously I could drop the customUserVariables.js file into the output folder before building the EXE, but now this is a temporary folder and I cannot update it at the right moment. Dropping the JS file into the html help output folder before uploading it is still fine, of course.

For the benefit of anyone else who needs to do this, and follows this thread, my solution is to update the JS file in the baggage folder in the skin from the FinalBuilder project that creates the JS file on each build, before running HM7. Finalbuilder can run 7Z.exe to update the hmskin file with the new JS file.
Unless there is a simpler or better solution I have missed, of course....