This page focusses primarily on the central management of widgets. If you're looking for information on how to display widgets in your site, please refer to the bubbles-widget macro or portal macro documentation.
At first glance, widgets may seem similar to the "User Macros" feature in Confluence, however they are far more advanced than user macros:
The last item, in particular, is one of the most powerful aspects of widgets. By grouping widgets in to Portals you can rapidly deploy custom, centrally-managed dashboards throughout your wiki with the portal macro.
There is one feature of user macros which you can't currently do with widgets which is supply macro parameters for replacement inline. If you need to do this you are best to stick with user macros for now.
Note: In order to create and edit widgets, you'll need to be a Confluence Administrator.
From the Confluence Administration Console choose "Widgets" from the "Community Bubbles" section:
Click on the imaginatively titled "Click here to add a new Widget" link to add a new widget. A form will be displayed with following fields:
Field | Required | Notes |
---|---|---|
ID | The unique identifier for this widget, used when adding the widget to Portals and also in the bubbles-widget macro. | |
Display Title | The title shown above the widget when it's being rendered in Portals using the portal macro. You can use Widget Tokens in this field. Leave blank to omit the title (which will also remove the ability to collapse the widget). | |
Description | A description of what this Widget actually does, shown when configuring portals. | |
Class | One or more CSS classes to add to the | |
Content | The content or "template" for your widget. How it looks on the page will depend a lot on the render mode used (see below). You can use Widget Tokens in this field. If there is no content in a widget, including after rendering the content, the entire widget will not be rendered. | |
Render | Defines how the content of the widget is rendered:
|
Once you've defined your widget, click the "Add" button to save it. You'll then be able to display the widget with the bubbles-widget macro or add it to Portals.
For an example of a widget, see Forum Widget Example.
To edit a widget, either click it's hyperlinked ID or the
icon. You'll see the same form that was displayed when adding a widget and can change any of the fields with the exception of the ID field.When you edit a widget, the changes will be reflected wherever that widget is used throughout the site.
Click the button to delete a widget.
Depending on settings (either in the portal definition or the bubbles-widget macro), the rendered widget will be wrapped in a <div>
element which will have various CSS classes defined:
<div class="widget $widgetid $expanded $class"> ... rendered widget goes here ... </div>
The possible classes are described below:
Class | Notes |
---|---|
| A static class, "widget" allows you to easily style all wrapped widgets. |
$widgetid | Replaced with the ID of the widget, making it easy to apply specific styles to a specific widget. |
$expanded | If the widget can be expanded or collapsed, this class will indicate the current state of the widget:
|
$class | Replaced with he class(es) you enter in the widget definition. |
As you can imagine, these classes make it really easy to style your widgets. There are several ways to define the style sheets to use for widgets:
Widgets that have no content will not be displayed - this subtle feature is really useful! For example, if you wanted a widget that is only shown to users in a specific group you could define the content as something like this:
{builder-show:group=confluence-administrators} This widget will only be shown to users in the {{confluence-administrators}} group! {builder-show}
In the example above, we're using the builder-show macro (requires the Theme Builder plugin) in such a way that it will only render it's contents if the user is in a specified group.
Widgets can be exported or imported using the Backup & Restore functionality. Anyone want to help set-up a repository of widgets?