This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Macro Placeholders and Transformation Templates

This article describes how macro placeholders work and how you can modify them with transformation templates.

1: Macro Transformation Template Samples

Note: Macro transformation templates are available as of WikiTraccs v1.20.6.

Note: Macro transformation templates got more powerful with release v1.26.1. Make sure to use a current version.

What are Macro Placeholders?

Macro placeholders are text replacements for macros and look like this:

🚧👇 Replaced ‘xyz’ macro, its content follows below (atlassian-macro-output-type==‘INLINE’)

🚧☝️ End of content of replaced ‘xyz’ macro

When migrating wiki pages from Confluence to SharePoint, WikiTraccs has to transform macros to something that SharePoint understands.

If there is no equivalent to a macro in SharePoint (which is the regular case), WikiTraccs often applies a generic transformation that replaces the macro in SharePoint with a text note.

Macro Placeholder Example

Let’s take the div macro as example. It is part of Adaptavist’s Content Formatting Macros offering.

How does the div macro look before and after having been migrated to SharePoint?

The div macro allows to apply formatting to Confluence page content, like setting the text color.

The following configuration applies a blue text color to the macro content when the macro is shown on the Confluence page:

Macro in edit mode, applying the 'color:blue' CSS style to its content, plus some other things.

Macro in view mode, displaying blue text in the Confluence page.

When migrating this macro to SharePoint, WikiTraccs discards the macro container, pulls its content out, and puts that on the page. A text placeholder highlights that this happened:

So, the result of this transformation is:

all content of the div macro has been migrated
formatting is gone with the macro container
a text placeholder highlights that a former div macro has been removed, but the content retained

Now, sometimes you want to get rid of that 🚧 placeholder text. You can create a custom placeholder to do that.

How to Create a Custom Macro Placeholder?

Advanced Topic

This and the following sections cover macro transformation templates which are designed to change how migrated pages look in SharePoint Online.

Originally, they were thought as a simple way to replace the default placeholder texts that WikiTraccs generates. But over time they got so powerful that WikiTraccs now by default uses a combination of built-in transformation logic and customizable transformation templates when adding support for new macros.

WikiTraccs allows to replace many of its built-in macro transformations using transformation templates. This can be used to replace generic macro placeholders with something different.

Note

There might be macros that are handled in such a way that their transformation logic cannot be replaced. One example is the code macro, which is transformed to a code snippet web part.

You can use Handlebars templates to describe how the placeholder for a macro should look. Handlebars is a markup language and templating system commonly used in web development.

Note

Refer to the Handlebars documentation to learn how Handlebars templates work. It is out of scope for this article to cover this.

Let’s say we want to remove the placeholder text for the transformed div macro, just migrating its body content.

The Handlebars template to do that looks like this:

{{!-- Don't add placeholder text, just render body --}}
{{Body}}

Some facts about above template:

{{Body}} is a variable, referencing the macro body; this tells WikiTraccs to just render the macro body, without additional placeholder text
{{!-- --}} marks a comment in the template; this is ignored by WikiTraccs

Using above transformation template, the transformed macro looks like this in SharePoint:

The 🚧 note is now gone.

Where to Put the Transformation Template File?

Custom transformation templates are stored as files in a folder.

When using WikiTraccs.GUI (the blue window), find WikiTraccs.GUI.exe and starting there, find the Templates\Transformation folder. Save your template file there.

When solely using WikiTraccs.Console (this most likely is not the case), find WikiTraccs.Console.exe and starting there, find the Templates\Transformation folder. Save your template file there.

The Transformation folder alreads contains files and should look like this (note that this can change in future WikiTraccs releases):

Each of those .hbs files contains a transformation template.

Note

The .hbs file extension is mandatory.

The transformation templates can apply to either

a single macro type (like div, or rw-ui-tabs-macro), OR
multiple macro types (like english,belarusian,bulgarian,canadian-en,…)

Transforming a Single Macro Type

When you want to transform a single macro type (like div), you save the transformation template in a file that carries the internal macro name in its filename and has the .hbs extension.

The file containing the transformation template for the div macro would thus be named div.hbs.

To reiterate, the steps to create a transformation template for a single macro type are:

identify the internal macro name
- you can see macro names in the storage format XML
- note: for our div macro we see ac:name="div" in the storage format XML
create a Handlebars template that describes how the custom placeholder should look
save the Handlebars template in a file, in the Templates\Transformation folder
- the filename follows the pattern MACRONAME.hbs where MACRONAME is the name of the macro
- the file extension must be .hbs for WikiTraccs to recognize the file

Transforming Multiple Macro Types With a Single File

You can also put a special comment as first line into your .hbs file to apply the template to multiple macros, saving you the hassle to create identical files for each of those types.

Here is an example:

{{!-- applyto:english-us,english,belarusian,bulgarian,canadian-en,canadian-fr,catalan,chinese,croatian,czech,danish,dutch,estonian,finnish,french,german,greek,hindi,hungarian,icelandic,indonesian,irish,italian,japanese,korean,latvian,lithuanian,malay,maltese,norwegian-nb,norwegian,polish,portuguese,portuguese-br,romanian,russian,serbian,slovak,slovenian,spanish,swedish,thai,turkish,ukrainian,vietnamese --}}

This tells WikiTraccs to use the template for all the macros listed after the applyto: marker (internal macro names, separated by comma).

The filename doesn’t matter, as long as it has the .hbs ending.

Which Variables Are Available in Templates?

Note

Templates are written in the Handlebars markup language that uses double and triple pairs of curly braces to encapsulate logic and variables. So, any of below variables might need to be enclosed in curly braces - look at existing templates or the Handlebars documentation on how the syntax looks exactly.

The following variables are available in transformation templates:

Variable	Data Type	Meaning
`Body`	n/a	the macro body (if the macro has one)
`HasBody`	boolean	true, if the macro has a body
`HasNoBody`	boolean	true, if the macro has no body
`Details.InternalName`	text	internal macro name (for example “bgcolor”)
`Details.DisplayName`	text	macro display name (for example “Background Color”)
`TypeAsString`	text	‘macro’ for macros, ‘ADF extension’ for ADF extensions, ‘unknown embedding’ otherwise
`IsMacro`	boolean	true, if the macro is a macro
`IsMacroEmpty`	boolean	true, if the macro is empty; a macro that only consists of whitespace and line breaks is considered empty as well; note that body-less macros may be considered not empty, if they are known to convert to content (like a `date` macro which seems empty, as it has no body content, but transforms to the current date and is therefore not empty)
`IsAdfExtension`	boolean	true, if the ‘macro’ is an ADF extension (so, not really a macro, but covered by macro transformation nevertheless)
`HasParameters`	boolean	true, if the macro has parameters
`HasNoParameters`	boolean	true, if the macro has no parameters
`ParameterCount`	number	the number of macro parameters
`Parameters`	collection	macro parameters, if the macro has any; each parameter has a `Name` and `Value` property; there is also a `Links` property that is populated with links parsed from the parameters
`MacroXml`	text	contains the raw macro XML as defined in the page’s storage format; note that you most likely need the triple brace syntax (like `{{{MacroXml}}}`) to work with that variable to prevent escaping
`@CanTransformToTable`	boolean \| null	internal indicator of WikiTraccs if the macro can be transformed to a table; sometimes set to false to prevent nested table structures, sometimes set to true if nesting is unlikely; might be null
`DefaultPlaceholder`	n/a	generates the generic macro placeholder that is output by WikiTraccs if it doesn’t know a macro; this will output a placeholder text, macro parameter values, and the body (if there is any)
`RandomGuid1`	text	a randomly generated GUID value; the variable has the same value during one macro transformation, even if used in multiple places of the template file; this can be useful if you need a random GUID at multiple places in the same template; there is also `RandomGuid2` and `RandomGuid3` available, providing up to 3 random GUIDs
`Parameter`	object	special variable granting access to macro parameters; see section Accessing Macro Parameters below

The following commands are available as well:

Command	Meaning
`{{Exit}}`	Cancels processing of the current transformation template; can be used to fall back to the built-in transformation logic of WikiTraccs
`{{RemoveMacro}}`	Removes the current macro without replacement

There are also helper functions available like String.Equal (which can be used to compare two text values for equality). Those are sometimes used by WikiTraccs’ own templates and are documented via their usage in those templates.

WikiTraccs brings some transformation template files along. In the Templates/Transformation folder, have a look at the unknown.hbs.sample file for an advanced usage example, or any of the other files.

Note

WikiTraccs more and more transitions to using transformation templates instead of hard-coded macro transformation logic.

Working with Macro Parameters

Macro parameters can be accessed via the Parameter variable.

For example the value of the macro parameter title is available via Parameter.title.Value. The parameter name (here title) is always written lowercase, even if the original macro parameter is not.

To get the value of a macro parameter (as text), you use the Parameter.paramname.Value syntax.

To get the raw XML representation of a macro parameter (as text), you use the Parameter.paramname.Xml syntax.

If the macro parameter contains links, those are accessible via the Parameter.paramname.Links collection. Each of the links can have a Title and Href property. The unknown.hbs.sample sample transformation template file shows how to enumerate links.

Sometimes WikiTraccs injects additional macro parameters mainly for internal use in its own transformation templates:

Parameter.wikitraccs-targetreference - added (for example) to Excerpt Include and Multiexcerpt include macros; this parameter contains an ac:link element, pointing to the page the snippet is included from; it’s used to generate a link to the source page

Multi-Pass Transformation

Multi-pass transformation has been introduced for internal use by WikiTraccs but might pose useful for you as well. Nevertheless, it’s tailored to WikiTraccs’ immediate needs and you’ll probably hit limitations.

Macro transformation is done in three phases for each macro:

prebuiltin
builtin
postbuiltin

Prebuiltin can be used to decorate a macro before the built-in transformation logic kicks in.

Builtin executes the built-in transformation logic for a macro. Macro transformation templates can replace this logic.

Postbuiltin is used internally by WikiTraccs where a macro is not yet fully transformed in the builtin stage, but will be in postbuiltin.

Macro transformation templates by default are applied in the builtin stage (and replace the builtin transformation logic), unless marked otherwise.

A transformation template can be marked for a specific stage like this:

expand[prebuiltin].hbs - executed in prebuiltin stage
excerpt-include[postbuiltin].hbs - executed in postbuiltin stage
excerpt.hbs - no marker, builtin stage by default

Templates for SharePoint Web Parts

Have a look at the Convert Macros to SharePoint Web Parts to learn about web part generation.

Templates that generate web parts have a specific structure and the <div data-wikitraccs-webpart-template="true"> element plays a key role. It acts as marker for WikiTraccs to trigger web part generation.

Important Notes About Macro Transformation Templates

A macro transformation template completely replaces the internal transformation logic of WikiTraccs for that macro. If you want some of the results of the internal logic back, you need to replicate it in the macro template.

There are limits to what can be done in macro transformation templates. It will not be possible to replace all of WikiTracc’s internal transformation logic with a custom transformation template.

Only one transformation template per macro template can be registered. Registering multiple templates per macro type leads to undefined behavior.

Troubleshooting

If your template is not recognized check for the following issues:

the template file is in the wrong folder
the template file doesn’t have the .hbs file ending
the filename doesn’t have the right pattern
the macro is already handled by a built-in transformation rule and thus no generic placeholder is being generated (note: there is nothing you can do about that; please get in touch and give feedback)
the template is malformed

Note

When starting WikiTraccs.GUI it will process all transformation templates it can find and log the result to the common log files. If there is an error, it will show an error dialog.

So, after editing template files, start WikiTraccs.GUI and if nothing pops up, at least the syntax is correct.

Note: this behavior is new as of release v1.26.1.

Check the console log output or common log files to see if WikiTraccs loads your template.

This is how the log looks if a template could be successfully loaded:

Found 3 transformation template files in folder '<path>/Templates/Transformation', will handle one by one: ch.bitvoodoo.confluence.plugins.language.hbs div.hbs rw-ui-tabs-macro.hbs
Trying to load transformation template from file 'Templates/Transformation/div.hbs'
Compiling and registering transformation template for 'div'

Any issues should be visible here as well. You can also look at the logs to learn about the path WikiTraccs loads templates from, if you are unsure where to put them.

1 - Macro Transformation Template Samples

This article shows sample templates.

Note: Macro transformation templates got more powerful with release v1.26.1. Make sure to use a current version.

Note

Macro transformation templates replace internal transformation logic of WikiTraccs.

Simple Body Replacement

Remove Macros without Body

The following template replaces the macro by its body content, for a list of macros. If the macro has no body, it will be removed.

{{!-- applyto:style,auibuttongroup,auibutton,div,bgcolor,alert,align,bibtex-reference,bibtex-display,center,clickable,auidialog,span,fancy-bullets,footnote,display-footnotes,highlight,auihorizontalnav,htmlcomment,img,table,tr,th,td,thead,tbody,iframe,latex-formatting,ol,li,ul,lozenge,auimessage,p,pre,privacy-policy,privacy-mark,auiprogress,auiprogressstepstatic,roundrect,search-box,span,tooltip,strike,copyright,reg-tm,sm,tm, --}}
{{#if HasBody}}
    {{Body}}
{{else}}
    {{RemoveMacro}}
{{/if}}

This preserves the macro body, even if it only consists of whitespace or line breaks.

Remove Macros without Body, or with Empty Body

If you want to remove such empty macro bodies as well, use the following approach, which also removes macros with empty body:

{{!-- applyto:style,auibuttongroup,auibutton,div,bgcolor,alert,align,bibtex-reference,bibtex-display,center,clickable,auidialog,span,fancy-bullets,footnote,display-footnotes,highlight,auihorizontalnav,htmlcomment,img,table,tr,th,td,thead,tbody,iframe,latex-formatting,ol,li,ul,lozenge,auimessage,p,pre,privacy-policy,privacy-mark,auiprogress,auiprogressstepstatic,roundrect,search-box,span,tooltip,strike,copyright,reg-tm,sm,tm, --}}
{{#if HasBody}}
    {{#unless IsMacroEmpty}}
        {{Body}}
    {{else}}
        {{RemoveMacro}}
    {{/unless}}
{{else}}
    {{RemoveMacro}}
{{/if}}