A macro is a type of Connect module that inserts dynamic content inside a Confluence page. You can use macros to display data from other systems, create specialized content such as diagrams or mathematical symbols, or display content contained within the macro itself.
You can use macros to build the following types of apps:
Macros enable you to integrate other systems into Confluence, either your own services or others that are available via APIs. Your macro may integrate aspects of a service's experience within a Confluence page, or create an experience that accesses the service's API.
Examples include integration with:
You can use macros to create content that meets a specialized use case. This could be content that's difficult or impossible for users to create using default types of content available in the Confluence editor.
Examples include:
Macros can display content contained within the macro itself, known as the 'macro body'. For example, the chart macro that's built into Confluence uses data in a table in the macro body to display a chart. In the editor, Confluence renders the macro as a container where users can add data for the macro to display.
Examples include:
You specify the parameters for a macro by adding either of the following elements to the app descriptor:
dynamicContentMacros
- dynamic content macros, which render asynchronously in an iframestaticContentMacros
- static content macros, which render synchronously by returning Confluence Storage Format to the Confluence pageMacros need to render within pages in order to be viewed. This is an easy first step to take after defining your macro following the getting started guide or the technical documentation. The tutorials show examples of how to use Handlebars to create views, but you can use whatever templating engine you like.
When creating your macro you need to decide between a dynamic macro and a static macro. Dynamic macros are rendered asynchronously within an iframe. Static macros are rendered synchronously.
When your macro is defined, default Confluence features will allow users to create instances of your macro on a page using the macro browser and related keyboard shortcuts.
If you are integrating an external service with a unique URL pattern, you may want to consider implementing an autoconvert extension also which dynamically matches the URL when pasting and converts it to a macro instance.
When users add your macro to a page, there are three ways they can edit and specify properties for it:
The property panel can also be extended to provide a shortcut to changing macro properties.
Get going by following these tutorials:
Rate this page: