Documentation

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. If you need to prevent any caching on the server, use


 Cache-Control: no-cache
 

Example

{
  "modules": {
    "staticContentMacros": [
      {
        "renderingMethod": "get",
        "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"
            ],
            "hidden": false
          }
        ],
        "autoconvert": {
          "urlParameter": "url",
          "matchers": [
            {
              "pattern": "https://www.example.com/maps/{}/{}"
            },
            {
              "pattern": "https://www.example.com/map-editor/{}"
            }
          ]
        },
        "editor": {
          "url": "/map-editor",
          "editTitle": {
            "value": "Edit Map"
          },
          "insertTitle": {
            "value": "Insert Map"
          }
        },
        "name": {
          "value": "Maps"
        },
        "key": "static-macro-example"
      }
    ]
  }
}

Properties

key

Type
string
Required
Yes
Description

A key to identify the macro. Keys must only contain alphanumeric characters and dashes, and must be globally unique. Prefixing it with the name of your add-on is the best way to ensure this.

name

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}&spaceid={space.id}&pageid={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 add-on. 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.id} parameter and use the Confluence REST api to call back to collect the body.
  • If you want, you can include, {macro.body}, {macro.id}, 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.id} and use the Confluence REST API to collect the body.

Here's an example:

Declare the variables that are later required to fetch the macro content in the URL:


 {
   "url": "/render-macro?pageId={page.id}&pageVersion={page.version}&macroId={macro.id}"
 }
 

Then use the Confluence REST API to collect the body, for example directly from the iframe:


 AP.require("request", function(request) {
     var pageId = getUrlParameter("pageId");
     var pageVersion = getUrlParameter("pageVersion");
     var macroId = getUrlParameter("macroId");
     request({
         url: "/rest/api/content/" + pageId +
              "/history/" + pageVersion +
              "/macro/id/" + macroId,
         success: function(response) {
             var macro = JSON.parse(response);
             process(macro.body);
         }
     });
 });
 

Preview Mode: If you use the {macro.id} 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.

Note: macro.body will not be truncated when renderingMethod field was set to POST in static content macro. Refer to the Static Content Macros for information on how to set this field.

Currently supported variables for macros are:

  • macro.hash: The hash of the macro body (deprecated, use the macro.id)
  • macro.id: The id of the macro
  • 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.

autoconvert

Description

URL patterns associated with this macro. If a URL matching a defined pattern is pasted into the editor, this macro will be created and will replace the URL string.

bodyType

Type
string
Defaults to
none
Allowed values
  • rich-text
  • RICH-TEXT
  • plain-text
  • PLAIN-TEXT
  • none
  • 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
    • media: Media
    • navigation: Navigation
    • reporting: Reporting
    • visuals: Visuals & Images

    description

    Description

    A description of the macro's functionality.

    documentation

    Type
    Description

    A link to the documentation for the macro.

    editor

    Description

    The configuration of a custom macro editor. This is useful if the parameter input field types are not sufficient to configure the macro.

    featured

    Type
    boolean
    Defaults to
    false
    Description

    Whether the macro should be "featured", meaning having an additional link in the "Insert More Content" menu in the editor toolbar.

    hidden

    Type
    boolean
    Defaults to
    false
    Description

    If set to true, the macro will not appear in the macro browser.

    icon

    Type
    Description

    A link to the icon resource (80x80 pixels) that will be shown in the macro selection dialog. The URL can be absolute or relative to the add-on base URL.

    imagePlaceholder

    Description

    The image rendered in the editor as the macro placeholder. It can only be used with bodyless macros and will behave just like a regular macro placeholder. Any parameter changes in the macro browser will cause the image to be reloaded - so that changes can be seen.

    outputType

    Type
    string
    Defaults to
    block
    Allowed values
    • block
    • BLOCK
    • inline
    • INLINE
    • Description

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

      parameters

      Type
      Description

      The list of parameter input fields that will be displayed.

      propertyPanel

      Description

      The configuration of a property panel. Specify a hidden iframe to be loaded in the macro's property panel.

      renderingMethod

      Type
      string
      Defaults to
      get
      Allowed values
      • get
      • GET
      • post
      • POST
      • Description

        HTTP method that will be used in the HTTP request.

        For example:
        If the rendering method was set to POST like this:

        
         {
             "renderingMethod": "POST",
             "url": "/macro-renderer?body={macro.body}"
         }
         

        Then Confluence will send a POST request to /macro-renderer like:

        
           POST /macro-renderer HTTP/1.1
           Authorization: JWT 
           Content-Type: application/x-www-form-urlencoded
           Transfer-Encoding: chunked
           Host: 
           User-Agent: Atlassian HttpClient  / Confluence- / Atlassian-Connect/

        body=&&pageVersion=&tz=&lic=&userkey=&xdme=&cp=&xdmc=&cv=&userid=

        Note: All the parameters will be sent via POST payload in application/x-www-form-urlencoded instead of url query parameters.
        The latest version of Atlassian Connect Express and Atlassian Connect Spring Boot have built-in support for verifying requests sent by POST. However you might need to implement the query hash verification if the framework you are using doesn't support it.