Widgets

Overview

Widgets are re-usable blocks of markup - they can contain simple wiki content, macros, HTML and even Velocity templates.

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:

Widgets are easier to manage - each widget can be given a title and description to help with long-term maintenance
Widget Tokens allow you to easily insert useful values such as user names or labels in to their markup
Depending on settings, widgets can be "collapsed" by end-users to hide their content
Widgets are much easier to customise with style sheets
Widgets can be rendered individually (using the bubbles-widget macro) or in groups (using the portal macro)

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.

Managing Widgets

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:

Adding a Widget

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 `<div>` that gets wrapped around the widget. Separate multiple classes with spaces. For more information, see #Styling Widgets with CSS.
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: Wiki Notation – Allows you to use wiki notation and Macros in the content of your widget. Velocity with Raw HTML – The content will be rendered as a Velocity template. The default macro velocity context is available to the template, the result will be output directly into the page as HTML Velocity with Wiki Notation – Content will initially be treated as a velocity template, with the default macro context. It will then be run through the Confluence wiki renderer so you can include basic wiki syntax and macros. Raw HTML – The widget content will be output directly to the web page (after processing any tokens, of course). This is the fastest possible render mode, and is ideal for including third party widgets.

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.

Editing a Widget

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.

Deleting a Widget

Click the button to delete a widget.

Styling Widgets with CSS

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
`widget`	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: `expanded` – the widget is expanded, showing both it's title and content `collapsed` – the widget is collapsed, showing only it's title
$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:

Global CSS - unless disabled, this gets output wherever you render a widget or portal and is therefore a fairly trivial way to
Theme Builder's Custom CSS – defines the CSS at theme layout level (preferred approach)
style macro – allows you to specify styles for a specific page and therefore ideal for prototyping

Hints and Tips

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?

Page tree