Make your App's Macros Display Properly in Exports

By default, Scroll Word Exporter will export most third-party macros without issue.

However, occasionally some third-party macros will not be exported correctly. Normally, this is because the macro has been designed to be displayed in Confluence which behaves differently from a Word file. Therefore, some macros can be displayed differently in the export because: 

• The dimensions do not match – a Confluence page is presented in a landscape format, whereas a Word file is normally in a portrait orientation. 
• The browser for a Confluence page displays scroll bars – a Word file cannot display this information. 
• The macro may lazy-load some data in the browser using a REST interface in order to speed up the original page loading times in Confluence, or because the user first needs to interact with it

This article describes how you, as an app developer, can make sure your macros display properly in Word exports.

Required steps

To avoid macros being displayed incorrectly, developers must ensure that macros are adaptable so that they are properly displayed in both the Confluence page view and the exported Word file. This can be achieved by the macro using context information provided by Confluence and Scroll Word Exporter in order to dynamically switch its output mode to the appropriate format.

Implement a different output mode

All Scroll Exporters render content in the PDF output mode. Therefore a macro can switch it's output like this:

@Override
public String execute(Map<String, String> parameters, String body, ConversionContext context) {
    if (ConversionContextOutputType.PDF.value().equalsIgnoreCase(context.getOutputType())) {
        // Render a static table that does not need to load data from a REST interface
        return "<table>...</table>";
    } else {
        // Render just a placeholder for the table that can load the data from some REST interface
        return "<div data-context-id='...'/>";
    }
}

Context information

In order to further differentiate exports done with Scroll Exporters from those done with Confluence's built-in exporters, we provide some properties in the macro's ConversionContext:

The following properties are currently available. Both key and values are always of type String. 

These properties can be used like this:

@Override
public String execute(Map<String, String> parameters, String body, ConversionContext context) {
    if ("com.k15t.scroll.scroll-office".equals(context.getProperty("com.k15t.scroll.product.key"))) {
        // Output content specific for Scroll Word Exporter
        return "<table>...</table>";
    } else {
        // Output generic content
        return "<div data-context-id='...'/>";
    }
}