- Created by Almuth Boehme , last modified on May 24, 2016
You are viewing an old version of this content. View the current version.
Compare with Current View Version History
« Previous Version 2 Next »
Content
Macros
There are several Confluence macros you can use to display metadata or select pages on the basis of their metadata in Confluence.
In order to insert any of the macros, you need to possess editor permissions for the page.
Display Metadata Macro
The Display Metadata macro shows metadata of a specified Confluence page.
Image 6: Display Metadata Macro (click to enlarge) Überarbeitung notwendig!
You can display all metadata or only certain sets or fields according to your specifications. Please refer to the following section for the available settings.
Parameters
Parameter | Default | Description | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Page | None | Optional | Enter a page whose metadata you want to display. By default, the parameter is empty, which means the current page is selected. Options:
| ||||||||||||
Render mode | Table | Optional | Display metadata as "name: value" pairs (table) or only the value. Several metadata field values will be printed one after the other. Options:
| ||||||||||||
Metadata fields filter | None | Optional | Choose the metadata field to filter which fields you want to display from a multiselect dropdown. | ||||||||||||
Metadata sets filter | None | Optional | Choose the metadata set to filter for a set you want to display from a dropdown.
| ||||||||||||
Show hidden metadata fields | None | Optional | Tick the checkbox to show all metadata fields that have been defined as hidden. | ||||||||||||
Checkboxes (Author, Last Modifier,...) | None | Optional | If you tick a checkbox, the respective metadata value will appear as a row in the overview. Available boxes:
|
If both filters (metadata fields and metadata sets) are empty, all metadata (except hidden fields) will be displayed.
Use Cases
(1) Display all page metadata in a table.
(2) Keep your site up-to-date using metadata. By choosing the render mode "value" and entering a specific field key, you can display single metadata values wherever you need the information.
Metadata Overview Macro
The Metadata Overview macro is used to display the page metadata of multiple pages in a table according to a search criterion.
An example result can be seen in this preview:
Image 7: Metadata Overview Macro (click to enlarge) Überarbeitung notwendig!
The search criterion is defined by filtering for metadata fields and certain values of those fields.
Image 8: Darstellung Filterabfragen
CSV Export
Metadata can be exported as a CSV file. To export metadata, go to a Confluence page whose metadata you want to export and add the Metadata Overview macro to the page. The export option can be found as the following symbol under the Metadata Overview macro:
Image 8: CSV Export Symbol (click to enlarge)
The exported CSV file includes the content of all metadata fields that are displayed in the Metadata Overview macro. By using the macro option "Metadata fields filter" you can define which metadata fields should be displayed and, consequently, exported. The page title of each page is included in the export by default.
Paging of the Metadata Overview does not change the number of results. If you click the export symbol on the first of several pages, you will still export the complete table.
In the next section, you will find an overview of the available settings for the Metadata Overview macro.
Parameters
Parameter | Default | Description | |
---|---|---|---|
Filters | None | (Required) | Define metadata fields and metadata field values to filter results displayed in the metadata overview macro. Can be left empty if expert filter criteria is used (see next parameter). |
Expert filter criteria | None | Required | Define more comprehensive filter queries to filter results displayed in the metadata overview macro. It is defined using the metadata sets and field keys and the Lycene search syntax. Please also see Determining the Key of a Metadata Set/Metadata Field and #Search. Placeholders are supported to make the output of the macro more dynamic. The following parameters are available:
|
Metadata fields filter | None | Optional | Define metadata fields to be displayed in the overview from a multiselect dropdown. If the filter is empty all metadata (except hidden fields) will be displayed.
|
Show space key | Unchecked | Optional | Display the space key for each page. |
Show hidden metadata fields | Unchecked | Optional | Display hidden metadata fields as well. |
Checkboxes (Author, Last Modifier,...) | None | Optional | If you tick a checkbox, the respective metadata value will appear as a row in the overview. Available boxes:
|
Sort by column | Page title ("title") | Optional | Defines the metadata field whose values will determine the sort order of all entries. |
Sort direction | ASCENDING | Optional | Defines the sort direction of the table entries according to the values entered in the "Sort by column" column. |
Number of items to display | 20 | Optional | Defines the maximum amount of pages that are to be displayed as rows in the macro per page. If the overview contains more items, the output will be paged. |
Pages will be found across all (permitted) spaces. This means that search results are not limited to the current space unless you filter for a space within the parameter "Expert filter criteria".
Use Cases for expert filter criteria
(1) Show the metadata of all pages whose metadata sets contain the field "Category":
// Search criteria metadatafield:metadatafield.category
(2) To get an overview of her own projects and their status, Katherine Smith might show the metadata of all pages where the contact person (a global metadata field) is Katherine Smith:
// Search criteria, using the login name of a user global.metadatafield.contactperson:ksmith
For the syntax of basic search queries, please refer to the beginning of this section. To determine the correct field or set keys, please refer to the section Determining the Key of a Metadata Set/Metadata Field below. To find out how to design more detailed search queries, please refer to the section Search.
Metadata History Macro
The Metadata History macro displays the metadata history of the current page:
Image 9: Metadata History Macro (click to enlarge)
Parameters
Parameter | Default | Description |
---|---|---|
Number of items to display | 10 | Number of displayed entries |
If the metadata of the page never changed before (after beeing published), the macro will show no history entries.
Determining the Key of a Metadata Set/Metadata Field
Confluence users can determine the key of metadata fields or sets by moving their mouse over the metadata set or field title within the metadata edit panel.
To display the key, go to a page where the metadata field or set has been added. Open the metadata edit panel in edit mode. Now hover your mouse over the metadata set (in the column colored in blue) or the metadata field (entries below) whose key you want to know. A small tooltip containing the respective key will be shown.
If you cannot find the metadata field, check if you have selected the correct metadata set.
Image 10: Metadata Set Key (click to enlarge) Überarbeitung notwendig!
As a Space Administrator, you can find the correct field key in the tab "Metadata fields", set keys in the "Metadata sets" tab respectively, as described in the Administrator Guide.
Image 11: Metadata Field Keys (click to enlarge) Überarbeitung notwendig!
Troubletshooting
When entering keys in a macro, make sure:
- There are no spaces
- They are written completely in lower case
- Words are only divided by "." (full stop) or ":" (colon) respectively, if you are searching
# capital letters used global.metadatafield.contactPerson:ksmith
# spaces in the search query global.metadatafield.contactperson : ksmith
# correct search query global.metadatafield.contactperson:ksmith
- No labels