Dashboard Macro
 | Displays the macro instances (gadgets) inside in a dashboard. |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | XWiki Platform >= 2.5M2 |
Table of contents
Description
You can use this macro to create dashboards in your wiki pages, to display an overview of wiki content in gadgets.
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
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| style | yes | any string | empty string | The 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. |
| layout | yes | any string, only 'columns' is implemented by default, for time being | none | The 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. |
| source | yes | document name | none | The 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.
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.
Adding a gadget on the dashboard is automatically saved, in the current implementation.
Gadget's title
The default gadget's title is the gadget's id, which is used as translation key in order to have internationalized titles.
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.
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.
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.
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.
Control Gadget Display
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:
#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.8.0):
- org.xwiki.platform:xwiki-platform-rendering-macro-container 16.8.0
- org.xwiki.platform:xwiki-platform-rendering-macro-script 16.8.0
- org.xwiki.platform:xwiki-platform-skin-api 16.8.0
- org.xwiki.platform:xwiki-platform-oldcore 16.8.0
- org.xwiki.rendering:xwiki-rendering-syntax-annotatedxhtml 16.8.0
- org.xwiki.rendering:xwiki-rendering-syntax-annotatedhtml5 16.8.0
- org.xwiki.platform:xwiki-platform-security-requiredrights-api 16.8.0
