Macro not expanded in webhelp.fragment.footer

Graham Hannington
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Macro not expanded in webhelp.fragment.footer

Post by Graham Hannington » Wed Sep 23, 2020 1:02 pm

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
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Macro not expanded in webhelp.fragment.footer

Post by Graham Hannington » Wed Sep 23, 2020 3:33 pm

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.
Last edited by Graham Hannington on Wed Sep 23, 2020 5:10 pm, edited 1 time in total.

Graham Hannington
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Macro not expanded in webhelp.fragment.footer

Post by Graham Hannington » Wed Sep 23, 2020 4:24 pm

...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
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Macro not expanded in webhelp.fragment.footer

Post by Graham Hannington » Wed Sep 23, 2020 4:36 pm

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
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Macro not expanded in webhelp.fragment.footer

Post by Graham Hannington » Wed Sep 23, 2020 5:02 pm

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
Site Admin
Posts: 181
Joined: Thu Dec 24, 2009 11:21 am

Re: Macro not expanded in webhelp.fragment.footer

Post by alin » Wed Sep 23, 2020 5:36 pm

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
Alin Balasa
Software Developer
<oXygen/> XML Editor
http://www.oxygenxml.com

Graham Hannington
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Macro not expanded in webhelp.fragment.footer

Post by Graham Hannington » Wed Sep 23, 2020 6:27 pm

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>

Post Reply