Dashboard Macro

Last modified by Admin on 2024/12/11 00:07

cogDisplays the macro instances (gadgets) inside in a dashboard.
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

XWiki Platform >= 2.5M2

Installable with the Extension Manager

Description

You can use this macro to create dashboards in your wiki pages, to display an overview of wiki content in gadgets.

See also the Dashboard Application which uses this Dashboard macro to provide some already-made Dashboards (a Common Dashboard, a User Dashboard and a Space template Dashboard to name a few).

Creating a dashboard

In order to create a dashboard in a page, you just need to add the {{dashboard}} macro to that page (you can use the macro menu from the WYSIWYG editor in order to do this). Configure the parameters of the dashboard to adjust its style and data source.

Parameter definition

NameOptionalAllowed valuesDefault valueDescription
styleyesany stringempty stringThe style of the gadgets on the dashboard. Although any string is allowed, a predefined value is panels, which will display the gadgets in the same styles as panels, that is with a dashed border around the gadgets and a strong titlebar. If left empty, a default style will be used. Note that this string is used as the class name of the toplevel HTML element of the dashboard, so it can also be used to implement custom styling with skin extensions.
layoutyesany string, only 'columns' is implemented by default, for time beingnoneThe layout of the gadgets on the dashboard. In case this parameter is missing, the columns layout will be used. For the moment only columns layout is implemented. This parameter is for advanced usage, should be left empty for basic use cases.
sourceyesdocument namenoneThe page from where the objects defining the dashboard gadgets should be read. This is useful for reusing the definition of a dashboard, without duplicating the gadgets object definitions. This parameter is for advanced usage, should be left empty for basic use cases.

By default a dashboard is empty, there are no predefined gadgets, so saving the page will not show any specific content. See the section about editing a dashboard to get instructions about how to add content.

Editing a dashboard

To access the dashboard visual editor, just edit the page that contains the dashboard. Also, you need to have edit rights on the page where the dashboard gadgets are defined in order to be able to edit them.

In edit mode, a dashboard will look just the same as in view mode, with a few extra actions added.

dashboardEdit.png

dashboardInlineMode.png

Adding gadgets

To add a gadget, you need to click the "Add Gadget" button in the top right corner of the dashboard, and follow the wizard. The gadget will be added at the end of the last column, from where you can move it afterwards to the desired position.

dashboardAddGadget.png

Adding a gadget on the dashboard is automatically saved, in the current implementation.

Gadget's title

Since 8.1-milestone-2.
The default gadget's title is the gadget's id, which is used as translation key in order to have internationalized titles.
Before, if the user didn't choose a name, the id was displayed in the dashboard.

Adding Columns

To add a new columns, you need to click the "Add Column" button in the top right corner of the dashboard. If you have existing gadgets, you will see that the proportionality will change, denoting a blank new column has been added

Change gadgets positions

To change gadget positions, just grab them with the mouse from the title bar and drag them around the page, in the new positions.

dashboardDragAndDrop.png

Note that the positions changes must be saved manually after all the reorganization is done.

Adding a new column to the dashboard can be done by using the dedicated button in the top right corner of the dashboard. To decrease the number of columns in the dashboard, just leave the last column empty and save the page. You'll have to also reload the page to see less columns.

dashboardAddColumn.png

Editing the parameters of a gadget

To edit the gadget parameters, use the edit button in the gadget settings menu, which appears in the top right corner of the gadget when hovering the gadget. This will open a wizard similar to the one for adding a gadget. Also note that the parameters are automatically saved upon finishing the wizard.

dashboardEditGadget.png

Deleting a Gadget

In the same gadget settings menu, there is an option to remove the gadget. Note that, while there is a confirmation dialog before the actual delete, the action is automatically saved therefore not reversible by canceling the edit form.

Advanced Topics

Advanced gadgets editing

Since gadgets are saved as objects in the page, you can always use the objects editor for advanced actions. Note that, though the visual editor only provides the option to choose from a list of predefined gadgets (the macros in the wiki, actually), a gadget can contain any wiki syntax, so, in the objects editor, you can put any content in your gadgets.

dashboardEditObjectMode.png

Control Gadget Display

XWiki 8.4R A Dashboard now only displays a Gadget if that gadget's content is not empty when rendered. This allows Gadgets to control whether they should be displayed or not. For example, if you wish to display a Gadget only if the user has some permissions such as Admin rights, you can do that with an if in the Gadget's content. 

For example the Activity Stream Gadget is only displayed if the Activity Stream feature is enabled:

{{velocity}}
#if ($services.messageStream.isActive())
  ...
#end
{{/velocity}}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-dashboard-macro 16.10.1):

Get Connected