Static Content Macro

A Confluence macro that returns XHTML in the Confluence storage format. Note, unlike most Connect modules, this content is not displayed in an iframe. Instead, your macro is responsible for returning valid Storage Format XML to the confluence page, which Confluence will render for you at view time.

Please consult Confluence Storage Format for additional information about how to construct valid storage format XML.

Use Caching

Because any calls to the macro rendering service happen synchronously during page load, we strongly encourage the implementations to take advantage of HTTP's caching mechanisms: Often, the rendered content only depends on the macro's body and parameters. A good approach for this specific case is to prevent Connect from retrieving the content again, unless the parameters or body have actually changed:

 res.setHeader('Cache-Control', ['max-age=3600', 's-maxage=3600']);

This response header tells the cache to use the response for an hour without asking the service again. Because we declare the macro hash and parameters as URL variables, the URL will automatically change when the macro is changed. This change will cause Connect to bypass the cache and to fetch the content from the add-on again. So doing non-conditional caching works very well for this case. If the content of the macro varies with other data, you could use ETag and If-None-Match to render the macro conditionally.

Also keep in mind that the calls are made from the Confluence server to the add-on host, and the cache is shared between users. If you need to prevent any caching on the server, use

 Cache-Control: no-cache

Example

{
  "staticContentMacros": [
    {
      "url": "/render-map?pageTitle={page.title}",
      "description": {
        "value": "Shows a configurable map"
      },
      "icon": {
        "width": 80,
        "height": 80,
        "url": "/maps/icon.png"
      },
      "documentation": {
        "url": "http://docs.example.com/addons/maps"
      },
      "categories": [
        "visuals"
      ],
      "outputType": "block",
      "bodyType": "none",
      "aliases": [
        "map"
      ],
      "featured": true,
      "parameters": [
        {
          "identifier": "view",
          "name": {
            "value": "Map View"
          },
          "description": {
            "value": "Allows switching between view types"
          },
          "type": "enum",
          "required": true,
          "multiple": false,
          "defaultValue": "Map",
          "values": [
            "Map",
            "Satellite"
          ]
        }
      ],
      "editor": {
        "url": "/map-editor",
        "editTitle": {
          "value": "Edit Map"
        },
        "insertTitle": {
          "value": "Insert Map"
        }
      },
      "key": "static-macro-example",
      "name": {
        "value": "Maps"
      }
    }
  ]
}

Properties

`key`

Type

string

Required

Yes

Description

A key to identify this module. This key must be unique relative to the add on.

All specified keys will have all special characters and spaces replaced with dashes and will be lower cased.

example: "My Addon Key" will become "my-addon-key"

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key. For example, an add-on which looks like:

{
    "key": "my-addon",
    "modules": {
        "configurePage": {
            "key": "configure-me",
        }
    }
}

Will have a configuration page module with a URL of /plugins/servlet/ac/my-addon/configure-me.

`name`

Type

i18n Property

Required

Yes

Description

A human readable name.

`url`

Type

string

uri-template

Required

Yes

Description

The link to the add-on resource that provides the macro content. This URL has to be relative to the add-on base URL.

Additional context parameters can be passed as variables in the URL.

"url": "/macro-renderer?body={macro.body}&space_id={space.id}&page_id={page.id}"

Since macro bodies can be of arbitrary size and may contain sensitive data, care must be taken as to how its passed to your connect addon. You have three options to gain access to the body:

If you can predict the size of your body and it is consistently less than 128 characters, you can include it in the GET request using the {macro.body} parameter.
If you know your macro contains a body that will often exceed the 128 character threshold (or is known to contain sensitive data), then you can include the {macro.hash} parameter and use the Confluence REST api to call back to collect the body.
If you want, you can include, {macro.body}, {macro.hash}, and {macro.truncated}. This way your plugin can call back to confluence only if {macro.truncated} is 'true'. This will allow you to skip the callback if it's not needed. This would be useful for macros that don't contain sensitive data of an unpredictable size.

Note: If you include the {macro.body} in your URL you are potentially leaking sensitive data to any intermediate host on the internet. This may result in the body being cached or indexed by a third party. If you are concerned about the security of your macro, you should always use the {macro.hash} and use the Confluence REST api to collect the body.

Preview Mode: If you use the {macro.hash} in your URL, the REST api will not return the macro body during a preview request, because the page has not been saved yet. You can use the {output.type} parameter to detect whether the macro is rendered in preview mode and adapt the response accordingly.

Currently supported variables for macros are:

macro.hash: The hash of the macro body
macro.body: The macro body, truncated to 128 characters
macro.truncated: True if the macro body was truncated, false of not
page.id: The page ID, e.g. 1376295
page.title: The page title, e.g. My Page
page.type: The page type, e.g. page
page.version: The page version, e.g. 6
space.id: The space ID, e.g. 65537
space.key: The space key, e.g. AC
user.id: The user ID, e.g. admin
user.key: The user key, e.g. ff80808143087d180143087d3a910004
output.type: The output type, e.g. display or preview

Context parameters for macros are also required in the URL. Please see the Macro Input Parameter documentation for details.

`aliases`

Type

[ string, … ]

Description

Define aliases for the macro. The macro browser will open for the defined aliases as if it were this macro.

`bodyType`

Type

string

Defaults to

none

Allowed values

rich-text

plain-text

none

Description

The type of body content, if any, for this macro.

`categories`

Type

[ string, … ]

Description

The categories the macro should appear in. A macro with no category will show up in the default 'All' category.

Currently, the following categories are supported by Confluence:

admin: Administration
communication: Communication
confluence-content: Confluence Content
development: Development
external-content: External Content
formatting: Formatting
hidden-macros: Hidden
media: Media
navigation: Navigation
reporting: Reporting
visuals: Visuals & Images

`description`

Type

i18n Property

Description

A description of the macro's functionality.

`featured`

Type

Allowed values

block

inline

Description

How this macro should be placed along side other page content.

`parameters`

Type

[ Macro Input Parameter, … ]

Description

The list of parameter input fields that will be displayed.