This page last changed on Dec 07, 2009 by ggaskell.
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, gadgets can be added to pages or blog posts via the gadget macro.
For a gadget to appear in the macro browser, it must first be registered by your Confluence Administrator in your Confluence server's External Gadgets page. Once this has been done, the gadget will appear in the macro browser.
Unlike other macros in the macro browser, the name of each gadget macro is typically unique and in the macro browser, follows the convention " '<gadget-name>' macro", where <gadget-name> is the name supplied by the gadget itself.
On this page:
Usage with the Macro Browser
To insert a gadget macro into a page using the Macro Browser,
- Open your desired Confluence page, then click the 'Edit' button. The 'Edit Page' mode opens.
- Next, click the Macro Browser icon
on the editor toolbar. The Macro Browser will open in the middle of the screen.
- In the Macro Browser, type the name of your desired macro into the search box at the top right of the window. Macros with a matching name will appear in the centre pane. Click on the desired macro to see its options screen. Here, you can set the macro parameters then click 'insert' to put the macro into the page.
Once you've found the required gadget macro, click ' insert' to add it to your page.
Usage with the Wiki Markup Editor
{gadget:url=http://jira.atlassian.com/rest/gadgets/1.0/g/com.atlassian.jira.gadgets:pie-chart-gadget/gadgets/piechart-gadget.xml|width=600}
projectOrFilterId=project-11291&statType=statuses&isConfigured=true&refresh=false
{gadget}
Where the value of the url parameter (beginning http://....xml) refers to the gadget URL registered with the Confluence server through the External Gadgets page. For further information about:
- Valid parameters that can be used with this gadget, refer to the parameters section below
- Understanding the contents associated with this gadget, refer to the gadget contents section below
Parameters
Parameters are settings for Confluence macros that allow the user to control their content or presentation. The table below lists relevant parameters for this macro.
Parameter names are displayed differently in the macro browser interface and in wiki markup. Below, parameter names used in the macro browser are indicated in Bold text, while their equivalents in wiki markup are indicated in (bracketed) text. If the latter is not shown, then in wiki markup, the parameter's name should be omitted and only its value should be added immediately after the colon symbol (:).
Parameter |
Required in Wiki Markup? |
Default |
Description |
Width
(width) |
No |
300 pixels |
Expands or shrinks the size of the gadget to match the specified width. The width can be specified in pixels (using px, for example, 500px), as a percentage of the page width (using %, for example, 50%), or automatically resized to fit 100% of the page width (auto). |
Border
(border) |
No |
false |
Places a thin grey border around the perimeter of the gadget. Select the check box in the macro browser (or use the value of true in Wiki Markup) to add this border or clear the check box (or optionally use the value of false) to remove it. |
Gadget Contents
The 'parameter-like' content (that is, body) of a gadget macro contains the property settings, which are specific to each gadget. Hence they are not documented here. Typically, this content would only be added to or modified by customising the gadget's default properties using the macro browser.
 | Editing a gadget's properties in wiki markup
If a gadget's properties appear within the body of a gadget macro in wiki markup, then it is possible to use this wiki markup to edit the values of these properties directly. However, this is not recommended as it permits the implementation of invalid values. If a gadget property only supports a certain set of values, the macro browser restricts the user to selecting only valid values for that property. Hence, it is strongly recommended that you use the macro browser to edit a gadget's properties.
A gadget's property may not necessarily appear within the body of its gadget macro until after it has been modified from its default value via the macro browser. |
 | Important note about gadgets on pages and blog posts
The properties of a gadget on a page respect Confluence's page editing permissions and consequently, cannot be edited when viewing the page. This is in contrast to gadgets on dashboards, which can be edited directly on a dashboard. Hence, you can only edit the properties of a gadget on a page when the page is in edit mode. |
|