Create Custom Template Placeholders

Scroll Word Exporter provides a variety of placeholders that can be used in templates to include dynamic data while exporting, such as the current space name or the page creator's name.

As an app developers you might want to contribute information from your app in exports as well. While you can always do this with macros, in order to make this available in a reusable export template, a custom placeholder is required.

Therefore, Scroll Word Exporter supports 3rd-party placeholders through a Velocity based API. The velocity-based approach ensures that your app has neither runtime nor buildtime dependencies to Scroll Word Exporter code.

Required steps

To create a custom placeholder you need to:

1. Create or extend an existing App
2. Add a new <velocity-context-item> plugin module
3. Add two Java methods matching our API signatures to this module, one for returning the placeholder's values and one returning the placeholder specification format for making it appear in the template designer

Example of custom placeholder

To see an example of a custom placeholder, you can visit our Bitbucket page.

Register the placeholder 

In order to be recognized as placeholder by Scroll Exporters the placeholder modules must fulfil these requirements:

• The placeholder must be implemented as a Velocity Context Item module: 

  CODE

      <velocity-context-item key="exp-my-placeholder"
                             name="Example Placeholder" context-key="exp-placeholder-example"
                             class="com.k15t.examples.ExamplePlaceholder"
                             global="true"/>

• The context-key attribute's value must be prefixed with exp-. The value after the prefix must be unique, and it should be readable and indicative of the placeholder's function. It is used to identify the placeholder when using it in a custom template (see below for examples).
• The global attribute must be set to true

• They must implement (at least) the following Java methods: 

  JAVA

  public class ExamplePlaceholder {
  
      public String render(Map<String, Supplier<String>> context) { ... }
  
  
      public String getPlaceholderSpec() { ... }
      
  }

• The getPlaceholderSpec method must return a valid placeholder specification format.

Java API

String render(Map<String, Supplier<String>> context)

String getPlaceholderSpec()

Available parameters

Placeholder specification format

{
    "version": "1",                                                 // Optional. Defaults to "1".
    "metadata": {
        "title": "My person placeholder title",                     // Used as display title for the placeholder
        "description": "Returns some information on some person",   // Optional. Displayed in the placeholder list and in placeholder dialog. Defaults to "".
        "display": "inline"                                         // Optional, either "inline", "block" or "user-defined", defaults to "inline"
    },
    "parameters": [
        {
            "key":"name",                                           // Used in the context map as part of the keys
            "title": "Full Name",                                   // Displayed in the placeholder dialog
            "description": "Enter the first and last name here",    // Optional. Displayed in the placeholder dialog. Defaults to "".
            "type": "string",                                       // Displays as a single-line input field
            "defaultValue": ""                                      // Optional, defaults to null if not specified
        },
        {
            "key":"age",
            "title": "Age",
            "description": "Enter the age in months here",
            "type": "int",                                          // Displays as a input field accepting numbers
            "defaultValue": "273"                                   // Optional, defaults to 0 if not specified
        },
        {
            "key":"gender",
            "title": "Gender",
            "description": "Enter the gender here",
            "type": "enum",                                         // Displays as a dropdown
            "defaultValue": "unspecified",                          // Optional, defaults to first allowed value, must match one of the keys in 'allowedValues'
            "allowedValues": [                                      // Only available for enums. Must not be empty.
                {
                    "key": "female",                                // Used in the context map as value for this parameter 
                    "title": "Female"                               // Displayed in the dropdown
                },
                {
                    "key": "male",
                    "title": "Male"
                },
                {
                    "key": "unspecified",
                    "title": "No indication"
                }
            ]
        },
        {
            "key":"newsletter",
            "title": "Send Newsletter",
            "description": "Send hourly newsletter?",
            "type": "boolean",                                      // Displays as a checkbox
            "defaultValue": "true"                                  // Optional, defaults to false if not specified
        }
    ]
}

User guide

Once you have followed the steps to create a custom template you can include either an inline or block placeholder in your Word template.

Inline placeholder

The following placeholder example will be executed in inline mode. In this mode all block elements will be removed and their inline content extracted. To do this, it requires building the placeholder using the following structure:

$scroll.custom.(<APP_KEY>,<PLACEHOLDER_KEY>,<PARAMETERS ...>), where

• <APP_KEY> is the key of the app providing the placeholder
• <PLACEHOLDER_KEY> is the value of the velocity-context-item module's context-key attribute without the exp- prefix.
• <PARAMETERS> is a comma-separated list of placeholder parameters, the order must match the order in the placeholder spec.

For example:

$scroll.custom.(my-addon-key,placeholder-example,my-first-param-value)

In this example the placeholder would be provided by an app with the key my-addon-key, would be registered with a context-key of exp-placeholder-example and would expect a single parameter.

Block placeholder

The following placeholder example will be executed in block mode. In this mode all block elements will be preserved. To do this, it requires building the placeholder using the following structure:

$scroll.custom.block.(<APP_KEY>,<PLACEHOLDER_KEY>,<PARAMETERS ...>), where

• <APP_KEY> is the key of the app providing the placeholder
• <PLACEHOLDER_KEY> is the value of the velocity-context-item module's context-key attribute without the exp- prefix.
• <PARAMETERS> is a comma-separated list of placeholder parameters, the order must match the order in the placeholder spec.

For example:

$scroll.custom.block.(my-addon-key,placeholder-example,my-first-param-value)

In this example the placeholder would be provided by an app with the key my-addon-key, would be registered with a context-key of exp-placeholder-example and would expect a single parameter.