×

You're using an outdated browser

For a better experience, keep your browser up to date. Check here for the latest version.

Manual

Make your app's macros display properly in exports

Thomas Rough

Thomas Rough Last update: Jan 22, 2018

By default, Scroll PDF 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 PDF 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 PDF file is normally in a portrait orientation. 
  • The browser for a Confluence page displays scroll bars – a PDF 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 PDF 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 PDF file. This can be achieved by the macro using context information provided by Confluence and Scroll PDF 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

KeyValue
com.k15t.scroll.product.keyThe full key of the exporter add-on, e.g. com.k15t.scroll.scroll-pdf
com.k15t.scroll.product.versionThe version of the exporter add-on, e.g. 4.0.6
com.k15t.scroll.exporter.template.nameThe name of the template that is being used for the current export

These properties can be used like this:

@Override
public String execute(Map<String, String> parameters, String body, ConversionContext context) {
    if ("com.k15t.scroll.scroll-pdf".equals(context.getProperty("com.k15t.scroll.product.key"))) {
        // Output content specific for Scroll PDF Exporter
        return "<table>...</table>";
    } else {
        // Output generic content
        return "<div data-context-id='...'/>";
    }
}
2x4.6
We use cookies to create a secure and effective browsing experience for our website visitors and to understand how you use our site (i.e. Google Analytics). For more information: click here.
Ok