A Confluence macro that loads remote content as an iframe. Dynamic Content Macros render content on every page request and are suitable for add-ons that need to display content that changes over time, that calls for dynamic interaction, or that is specific to the authenticated user.
Since Dynamic Content Macros are rendered in an iframe, you are able to include your own style sheets and javascript. You can use these to create a rich, interactive experience for your users.
If the macro allows for arbitrary nested content and uses the Confluence content body conversion endpoint to render the nested content within the macro's iframe; then the macro must request the dependent web resources and inject them into the iFrame context before displaying the result. See the content body conversion API documentation for more details.
Example: rendering nested content
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
// app.js
httpClient.post(
{ url: '/rest/api/contentbody/convert/view?expand=webresource.uris.js,webresource.uris.css,webresource.superbatch.uris.js,webresource.superbatch.uris.css',
json: {...} }
).then(renderResponse -> {
var wr = renderResponse.body.webresource;
var jsDependencies = wr.superbatch.uris.js.concat(wr.uris.js || []);
var cssDependencies = wr.superbatch.uris.css.concat(wr.uris.css || []);
res.render("template", {
"body": renderResponse.body.value,
"css": cssDependencies,
"js": jsDependencies
});
});
// template.hbs
{{#each css}}
<link rel="stylesheet" href="{{this}}" media="all" />
{{/each}}
{{#each js}}
<script src="{{this}}" type="text/javascript" />
{{/each}}
When your macro is exported to a static format such as PDF or Word, you can use the renderModes
property to define
a mapping between a certain type of output device and a static macro implementation. This will allow you to create a
static view of your macro's data where an interactive model is not appropriate.
For most modules, you do not need to be concerned with iframe sizing. It's all handled for you. However, an exception exists for inline macros.
An inline macro is a type of macro that generates content within the text flow of a paragraph or other text element in which the macro appears, such as a status lozenge. To implement an inline macro, follow these general guidelines:
macro-page
declaration in the add-on descriptor, set the output-type
attribute to inline
. (Alternatively, if this value is set to block
, the macro content will appear on a new line in the page output.)data-options
attribute in the script tag for all.js to "resize:false
". This turns off automatic resizing of the iframe.AP.resize(w,h)
immediately after the DOM of your iframe is loaded.Example
The following macro example is an adaptation from the Google Maps add-on. The source is hosted on Bitbucket.1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
{
"modules": {
"dynamicContentMacros": [
{
"width": "200px",
"height": "200px",
"renderModes": {
"pdf": {
"url": "/render-map-pdf"
},
"default": {
"url": "/render-map-static"
}
},
"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,
"indexing": {
"enabled": true
}
}
],
"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": "dynamic-macro-example"
}
]
}
}
key
Type | |
Max length | 100 |
Required | Yes |
Pattern | ^[a-zA-Z0-9-]+$ |
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
Type | |
Required | Yes |
Description | A human readable name. Represents a string that can be resolved via a localization properties file. You can use the same Example1 2 3 4
|
value |
| ||||||||
i18n |
|
url
Type | |
Format | 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: 1 2 3 4 5
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
Note: If you include the Here's an example: Declare the variables that are later required to fetch the macro content in the URL: 1 2 3 4 5
Then use the Confluence REST API to collect the body, for example directly from the iframe: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Preview Mode: If you use the
Note: Currently supported variables for macros are:
- Context parameters for macros are also required in the URL. Please see the Macro Input Parameter documentation for details. |
aliases
Type | |
Description | Define aliases for the macro. The macro browser will open for the defined aliases as if it were this macro. |
autoconvert
Type | |
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. Autoconvert allows your macro to be inserted into the editor when a recognised URL is pasted in by the user. You define recognised URL patterns using 'matchers' which are registered in the editor when your add-on is installed. When the macro is created in the editor, the URL string that triggered the autoconvert will be captured and inserted as a parameter on the macro body. You must define the name of this parameter by providing a string value for 'urlParameter'. This allows you to access the URL that triggered the autoconvert. Example This example inserts a macro into the editor when a user pastes in certain simple Facebook links. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
|
urlParameter |
| ||||||||
matchers |
|
bodyType
Type | |||||||||||
Defaults to | none | ||||||||||
Allowed values |
| ||||||||||
Description | The type of body content, if any, for this macro.
|
cacheable
Type | |
Defaults to | false |
Description | Returns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and lack all additional query parameters:
|
categories
Type | |
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:
|
description
Type | |
Description | A description of the macro's functionality. Represents a string that can be resolved via a localization properties file. You can use the same Example1 2 3 4
|
value |
| ||||||||
i18n |
|
documentation
Type | |
Description | A link to the documentation for the macro. Represents a link, its optional title and alternative text. Example1 2 3 4 5 6 7 8
|
url |
| ||||||||
altText |
| ||||||||
title |
|
editor
Type | |
Description | The configuration of a custom macro editor. This is useful if the parameter input field types are not sufficient to configure the macro. Macro Parameters go a long way when it comes to macro configuration, but there are cases when a macro add-on needs more control over the UI. Defining a Macro Editor allows you to implement a custom UI for the macro, by specifying a URL to a page in your add-on which will be shown in the dialog iFrame. In order to persist custom data in your macro editor, use the Javascript Confluence API and the Dialog API. For example:
AP.require(["confluence", "dialog"], function (confluence, dialog) { function onSubmit() { var macroParams = { myParameter: value }; confluence.saveMacro(macroParams); confluence.closeMacroEditor(); return true; } dialog.getButton("submit").bind(onSubmit); });
In order to retrieve the custom data again when the editor is opened, use AP.require("confluence", function (confluence) { var macroData = confluence.getMacroData(function(macroParams) { doSomethingWith(macroParams.myParameter); }); }); Example 1 2 3 4 5 6 7 8 9 10 11 12
|
url |
| ||||||||
cacheable |
| ||||||||
editTitle |
| ||||||||
height |
| ||||||||
insertTitle |
| ||||||||
width |
|
featured
Type | |
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. |
height
Type | |
Max length | 10 |
Description | The preferred height of the macro content, e.g. |
hidden
Type | |
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. Defines an icon to display. Example1 2 3 4 5 6 7 8
|
url |
| ||||||||
height |
| ||||||||
width |
|
imagePlaceholder
Type | |
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. Defines a macro image placeholder to display in the Confluence editor. Example 1 2 3 4 5 6 7 8 9
|
url |
| ||||||||
applyChrome |
| ||||||||
height |
| ||||||||
width |
|
outputType
Type | |
Defaults to | block |
Allowed values |
|
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
Type | |
Description | The configuration of a property panel. Specify a hidden iframe to be loaded in the macro's property panel. Defining a Macro Property panel allows you to add a hidden iframe to your macro's property panel. The iframe is loaded as soon as the property panel is opened. In order to persist custom data using your property panel, use the Javascript Confluence API. For example: AP.require(["confluence"], function (confluence) { var macroParams = { myParameter: value }; confluence.saveMacro(macroParams); });
In order to retrieve the custom data again when the property panel is opened, use AP.require("confluence", function (confluence) { var macroData = confluence.getMacroData(function(macroParams) { doSomethingWith(macroParams.myParameter); }); });
Dialogs may also be created. Use AP.require('dialog', function(dialog) { dialog.create({ key: 'my-module-key', width: '500px', height: '200px', chrome: true }).on("close", callbackFunc); }); |
url |
| ||||||||
cacheable |
| ||||||||
controls |
|
refDataSchema
Type | |
Description | Defines what a dynamic content macro can consume and produce to interoperate with other macros. 1 2 3 4 5
This is useful to chain multiple macros with each other. For example a macro can provide adf table data which can be used to produce a chart with it. To use this feature, you need to define the input and output types of your macro, of which two are supported: "table-adf" and "table-json". The inputType of a macro is the type of data it consumes; and the outputType of a macro is the type of data it produces. The inputType of a macro must match the outputType of another macro to be able to chain them together. For example, if a macro produces "table-adf" data, it can be chained with another macro that consumes "table-adf" data. If a macro produces "table-json" data, it can be chained with another macro that produces "table-json" data. By default, a Confluence Native Table produces "table-adf" data and a Confluence Native Chart consumes "table-adf" data, allowing the Native Table data to be consumeable by the Native Chart. Other Connect macros can be created to produce and consume "table-json" data, allowing them to be chained together within the Editor. |
inputType |
| ||||
outputType |
|
renderModes
Type | |
Description | Since Dynamic Content Macros are rendered in an iframe, you are able to include your own style sheets and javascript.
When your macro is exported to a static format such as PDF or Word, you can use the Allows your dynamic content macro to provide different static macro implementations for different render modes. Dynamic Content Macros can include style sheets and javascript, allowing the development of rich interactive applications. When your macro is rendered in a web browser this can provide a modern, interactive web experience. When your macro is rendered to static formats such as PDF, or word, these interactive modes are often undesirable, or technically impossible. Macro Render Modes allow you to map a render mode to a static content macro. This allows you to provide an implementation of your macro for these formats, that will render safely to static formats. Example 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
|
default |
| ||||
email |
| ||||
pdf |
| ||||
word |
|
width
Type | |
Max length | 10 |
Description | The preferred width of the macro content. |
Rate this page: