This page last changed on Jan 05, 2010 by smaddox.

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.

Confluence comes bundled with a few of its own gadgets which can be added to your pages or blog posts using the gadget macro via the macro browser. Refer to Confluence Gadgets for more information. However, you can access additional gadgets in this list if your Confluence Administrator has:

  • Installed additional gadgets locally within your Confluence installation (typically as a Confluence plugin) or
  • Registered gadgets served from an external web application or website (such as those from a JIRA installation or iGoogle) via the External Gadgets page.

Contact your Confluence Administrator if you wish to use additional gadgets within your Confluence installation.

Unlike other macros in the macro browser, the name of each gadget macro in the macro browser is typically unique and follows the convention " '<gadget-name>' macro", where <gadget-name> is the name supplied by the gadget itself.

On this page:

Inserting Gadgets into a Confluence Page or Blog Post

To insert a gadget into a page using the Macro Browser,

  1. Open your desired Confluence page or blog post, then click the 'Edit' button. The page or blog post opens in edit mode.
  2. Click the Macro Browser icon on the toolbar. The macro browser window opens in the middle of the screen in 'macro selection' mode.
  3. Click 'External Content', which contains a list of your gadgets configured for use in your Confluence installation.
    Some Confluence macros like the Edit in Word Link, JIRA Issues, JIRA Portlet, RSS Feed, Tasklist and Widget Connector macros also appear in this category because they can access external content too.
  4. Click on the desired gadget to access its parameters and properties and preview any changes to these values. (The macro browser is now in 'preview' mode).
    Almost all gadgets allow you to set basic parameters (listed below), which appear on the right of the macro browser. Each gadget may also have its own set of modifiable properties. Depending on the gadget, these may appear on the right of the macro browser (below the basic parameters) or on the gadget itself (in the 'preview' area on the left of the macro browser).
    The properties of most Atlassian gadgets appear on the gadget itself.
  5. Set the gadget's parameters and properties to your requirements.
    • If you have made changes to any properties on the gadget itself, click the 'Save' button on the gadget to update the gadget's content with these modifications.
    • Click 'Refresh' to update the gadget with any changes to:
      • Parameters or properties on the right of the macro browser
      • Data used in the gadget, which is retrieved from the gadget's server.
  6. Click 'Insert' to put the gadget into the page or blog post.
    The gadget is added as a gadget macro in wiki markup.

Editing Gadgets on a Confluence Page or Blog Post

To edit an existing gadget on a page or blog post using the Macro Browser,

  1. Open your desired Confluence page or blog post, then click the 'Edit' button. The page or blog post opens in edit mode.
  2. Place the cursor anywhere within the gadget macro's first set of curly braces (of the wiki markup) and click the Macro Browser icon on the toolbar. The macro browser window opens in 'preview' mode with the gadget's existing parameter and property values displayed.
    Almost all gadgets allow you to set basic parameters (listed below), which appear on the right of the macro browser. Each gadget may also have its own set of modifiable properties. Depending on the gadget, these may appear on the right of the macro browser (below the basic parameters) or on the gadget itself (in the 'preview' area on the left of the macro browser).
    The properties of most Atlassian gadgets appear on the gadget itself.
  3. Set the gadget's parameters and properties to your requirements.
    • If you have made changes to any properties on the gadget itself, click the 'Save' button on the gadget to update the gadget's content with these modifications.
    • Click 'Refresh' to update the gadget with any changes to:
      • Parameters or properties on the right of the macro browser
      • Data used in the gadget, which is retrieved from the gadget's server.
  4. Click 'Save' to update the gadget on the page or blog post.

Parameters

Parameters are settings for Confluence gadgets that allow the user to control basic aspects of their presentation. The table below lists the parameters for this macro, which will appear within the first set of curly braces in the wiki markup. Parameter names used in the macro browser are indicated in Bold text, while their equivalents in wiki markup are indicated in (bracketed) text.

Parameter Required in Wiki Markup? Default Description
Width
(width)
No 450 pixels Expands or shrinks the size of the gadget to match the specified width. The width can be specified in pixels (using px or no suffix, for example, 500px or 500, respectively), as a percentage of the page width (using %, for example, 50%), or automatically resized to fit 100% of the page width (using the value 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.

Contents of a Gadget Macro

The body of a 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 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 will restrict 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 or blog post respect Confluence's page editing permissions and consequently, cannot be edited when viewing the page or blog post. You can only edit a gadget's properties when the page or blog post is in edit mode.

Viewing the Gadget Contents in Wiki Markup

When you have added a gadget to a page, its wiki markup will look something like this:

{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}

The value of the url parameter (beginning http://....xml) refers to the gadget URL. In this example, the width parameter has been set to 600 pixels.

While it is fine to modify the gadget macro's parameters by editing the wiki markup directly, for the reasons described above it is not recommended that you modify the body of a gadget macro in this manner.

RELATED TOPICS

The big list of Atlassian gadgets

Document generated by Confluence on Mar 16, 2011 18:23