Macro not expanded in webhelp.fragment.footer

[Graham Hannington]

In WebHelp generated by Oxygen XML Author 22.1, the following element in the publishing template:

Code: Select all

<parameter name="webhelp.fragment.footer" value="&#xA9; ${timestamp([Y0001])} XYZ Software, Inc."/>

results in a footer with that text, but with the macro call as-is, unexpanded.

Am I doing something wrong? Or are macros supported only in external fragment files, not strings specified in the publishing template?

[Graham Hannington]

After doing more reading, I realize I was probably wrong to expect that macro to work without a <whc:macro> wrapper. Even so, this:

Code: Select all

<parameter name="webhelp.fragment.footer" value="&#xA9; &lt;whc:macro value='${timestamp([Y0001])}'/> XYZ Software, Inc."/>

results in the error:

The prefix "whc" for element "whc:macro" is not bound.

[Graham Hannington]

...so I thought I'd try an external fragment file:

Code: Select all

<parameter name="webhelp.fragment.footer" value="html-fragments/webhelp_fragment_footer.html"/>

where html-fragments is a directory that is in the same directory as the publishing template (.opt) file. And, yes, that webhelp_fragment_footer.html file exists in that html-fragments directory.

The footer in the generated WebHelp contains the "as-is" value of the value attribute:

html-fragments/webhelp_fragment_footer.html

Not what I had in mind.

I've tried specifying an absolute path, rather than a relative path, for the value attribute. Nope. Similar result.

I've tried <html-fragments> instead, but I've run into a blocker there, too. I might save that for a later post.

[Graham Hannington]

This:

Code: Select all

 <html-fragments>
            <fragment placeholder="webhelp.fragment.footer" 
                file="html-fragments/webhelp_fragment_footer.html"/>
 </html-fragments>

causes the following error while editing in Oxygen XML Author (22.1):

The resource associated with the HTML fragment does not exist: file:/C:/ ... /html-fragments/webhelp_fragment_footer.html.

even though that file exists in the appropriate (sub)directory. That is, I have:

c:\path\my-publishing-template.opt
c:\path\html-fragments\webhelp_fragment_footer.html

Argh!

[Graham Hannington]

I've hit a dead stop here. I want to specify HTML fragments, including WebHelp macros, for the "placeholder" areas. But I can't seem to do that: not via <parameter> or <fragment>, regardless of whether I use an absolute or relative path.

Clutching at straws, I wondered whether specifying type="filePath" on the <parameter> might make a difference. Nope.

[alin]

Hello Graham,

If you are setting your fragment directly as parameter value, then that fragment should be a well-formed XML fragment. In your case you should have declared the XML namespace for the whc prefix, that is:

Code: Select all

xmlns:whc="http://www.oxygenxml.com/webhelp/components"

If you are using an HTML Fragment file, then that file should be XML well-formed. In your case, the content should have a single root element and it should also contain the namespace declaration mentioned above.
You can read more about HTML Fragment Extension Points here https://www.oxygenxml.com/doc/versions/ ... aid-title6

There are two possibilities for using macros:

1. Directly in attribute values - For example, if you want to reference a JavaScript file from the Publishing Template directory, you can use the following construct:

   Code: Select all

   <script type="text/javascript" src="${path(oxygen-webhelp-template-dir)}/"></script>

2. In text content - Using the <whc:macro> template component:

   Code: Select all

   <script type="text/javascript" xmlns:whc="http://www.oxygenxml.com/webhelp/components"> 
     var outDirPath = '<whc:macro value="${path(oxygen-webhelp-output-dir)}"/>';
     console.log("The output directory path is:", outDirPath);
   </script>

...so I thought I'd try an external fragment file:
<parameter name="webhelp.fragment.footer" value="html-fragments/webhelp_fragment_footer.html"/>

When referencing an HTML Fragment file inside the Publishing Template's descriptor file (.opt) I would recommend to use the dedicated section (inside the <html-fragments> element).
If you want to use the <parameters> section you should instruct the Publishing Template that the parameter's value represents a relative file path by setting the @type="filePath" attribute on the <parameter> element.

I've tried specifying an absolute path, rather than a relative path, for the value attribute.

I would not recommend referencing absolute file paths in the descriptor file because the Publishing Template is considered to be a self contained customization package that can be shared with others.

Regards,
Alin

[Graham Hannington]

Hi Alin,

Thank you so much for the quick response!

As per your advice, declaring the whc namespace in the root element of the fragment fixed the problem for me:

Code: Select all

<div xmlns:whc="http://www.oxygenxml.com/webhelp/components">&#xA9; <whc:macro value="${timestamp([Y0001])}"/> XYZ Software, Inc.</div>