Gadget Macro
Gadgets are small applications that can offer dynamic content. They are typically served from a web application server and can be re-used in many other web applications. In Confluence, use the Gadget macro to add gadgets to pages or blog posts.
Confluence comes bundled with a few of its own gadgets that you can add to your pages or blog posts. However, you can access additional gadgets in this list if your Confluence Administrator has:
- Installed additional gadgets in Confluence (typically as a Confluence plugin) or
- Registered gadgets served from an external web application or website (such as those from a JIRA application).
Unlike other macros, the name of each gadget macro is unique and follows the convention "<gadget-name> macro", where <gadget-name> is the name supplied by the gadget itself.
Inserting gadgets into a Confluence page or blog post
To add a gadget to a page:
- Edit your page or blog post.
- Choose Insert > Other Macros.
- Click External Content to see a list of gadgets configured for use in your Confluence installation.
(Some Confluence macros like the JIRA Issues, RSS Feed, and Widget Connector macros also appear in this category because they can also access external content.) - Click the desired gadget to access its parameters and properties.
Almost all gadgets allow you to set basic parameters (listed below), which appear in the macro dialog. Some gadgets also have their own set of parameters, that can only be set in the gadget itself. You can use the preview in the macro browser to access them. - Set the parameters to your requirements.
- Click Refresh to preview your changes.
- Click Insert to add the gadget to the page.
Editing gadgets on a Confluence page or blog post
To edit an existing gadget on a page or blog post:
- Edit your page or blog post.
- Click the Gadget macro placeholder and choose Edit (or double-click the placeholder).
- Set the gadget's parameters to your requirements.
- Click Refresh to preview your changes.
- Save the gadget.
Standard gadget parameters
Almost all gadgets allow you to set basic parameters (listed below), which appear on the right of the macro dialog. Each gadget may also have its own set of parameters, which appear on the left of the macro dialog.
Parameter | Default | Description |
|---|---|---|
Width | 450 pixels | Set the width of the gadget, using one of the following conventions:
|
Border | true | Places a thin grey border around the gadget. |
Contents of a Gadget macro
In the addition to the standard parameters, the gadget macro contains 'parameter-like' content, which represents specific property settings that are particular to each gadget. Hence they are not documented here. Typically, this content would only be changed by customising the gadget's default properties using the macro browser.
Code examples
The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page.
Macro name: gadget
Macro body: None.
The following additional parameters are available in storage format and wikimarkup.
| Parameter name | Required | Default | Parameter description and accepted values |
|---|---|---|---|
url | Yes | (none) | This is the location of the gadget specification (XML file). |
preferences | No | (Gadget-dependent) | Specific property settings that are particular to each gadget. |
A note about editing a gadget's properties (preferences) in markup: It is possible to edit the values of these properties directly in the wiki markup or storage format. However, this will allow the entry of invalid values. If a gadget property supports a certain set of values, the macro browser will restrict the user to selecting only valid values for that property. For that reason, we recommend that you use the macro browser to edit a gadget's properties.
Storage format example
This example shows the Confluence Page gadget:
<ac:structured-macro ac:name="gadget">
<ac:parameter ac:name="width">500</ac:parameter>
<ac:parameter ac:name="border">false</ac:parameter>
<ac:parameter ac:name="url">rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-page-gadget/gadgets/confluence-page-gadget.xml</ac:parameter>
<ac:parameter ac:name="preferences">spaceName=Documentation&spaceKey=DOC&quickfind-space=Documentation&pageId=753666&pageName=Documentation%20Home&quickfind-page=Documentation%20Home&isEditable=true&isConfigured=true&refresh=15&showLink=false</ac:parameter>
</ac:structured-macro>
This example shows the Confluence News gadget:
<ac:structured-macro ac:name="gadget">
<ac:parameter ac:name="url">rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-news-gadget/gadgets/confluence-news-gadget.xml</ac:parameter>
<ac:parameter ac:name="preferences"/>
</ac:structured-macro>
Wiki markup example
This example shows the Confluence Page gadget:
{gadget:width=500|border=false|url=rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-page-gadget/gadgets/confluence-page-gadget.xml} spaceName=Documentation&spaceKey=DOC&quickfind-space=Documentation&pageId=753666&pageName=Documentation%20Home&quickfind-page=Documentation%20Home&isEditable=true&isConfigured=true&refresh=15&showLink=false {gadget}
This example shows the Confluence News gadget:
{gadget:url=rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:confluence-news-gadget/gadgets/confluence-news-gadget.xml} {gadget}