Oxygen XML Forum

In WebHelp generated by Oxygen XML Author 22.1, the following element in the publishing template:
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?

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

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

...so I thought I'd try an external fragment file:
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.

This:
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!

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.

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: 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

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: