Filter news by metadata (like location, category)
Introduction
Metadata for Confluence allows you to assign and administer page metadata in Confluence centrally.
With the Metadata add-on, you can:
Assign metadata sets to single pages, part of or even the whole page tree of a space
Add metadata sets to Confluence page templates
Search metadata and display pages based on their metadata values
Why use the Metadata Add-on in combination with the Enterprise Theme?
As explained in the introduction, you can provide metadata for pages and blog posts, for example the target country or department for a blog post and use this metadata to define specific news listings etc.
If you use the Enterprise Theme News macros like the Blog Posts & Pages, you can list content based on exactly this metadata. If you use the User Profiles Add-on in addition, the Enterprise Theme macros can filter their content by dynamic Metadata queries, based on the information of the current logged in user.
Some examples what can be built with this?
Blog Post listings for a specific country
Blog Post or Pages listings about a specific topic
News for the department, the current logged in user is working for! (Combination of Enterprise Theme, Metada Add-on and User Profiles App)
Show all news for a specific department AND the global news
...
Which Enterprise Theme Macros can use Metadata Information?
Some macros can use the metadata information within their macro configuration. These macros are implementing the Lucene query parameter of the news macros. You can use the parameter in these macros:
How to use Metadata Information in the Enterprise Theme macros
All Enterprise Theme News macros provide an input field for a Lucene Query parameter. With this parameter you are able to enter every lucene query you like. A detailed documentation about this parameter can be found under the Lucene query parameter of the news macros.
The Communardo Metadata Add-on extends the search index with every metadata field value you create in that add-on.
To use the metadata field values with the news macros you need to follow these steps:
Use the name to build a valid Lucene query
Add this query to the news macro parameter Additional Lucene Query (The Lucene query parameter of the news macros)
Search Terms Based on Lucene Search Syntax
Search queries according to the Lucene search syntax necessitate knowing the keys of metadata sets and fields. Basic search queries look like this:
//search for space set
metadataset:KEY_OF_METADATASET
//search for space field
metadatafield:KEY_OF_METADATAFIELD
//search for metadata value for a space metadata field
KEY_OF_METADATAFIELD:VALUE_OF_METADATAFIELD
//search for global set
global.metadataset:KEY_OF_METADATASET
//search for global field
global.metadatafield:KEY_OF_METADATAFIELD
//search for metadata value for a global metadata field
KEY_OF_METADATAFIELD:VALUE_OF_METADATAFIELD
//do not allow an empty field
metadatafield.KEY_OF_METADATAFIELD:[* TO *]However, you do not have to guess the correct name. The following section describes how to determine the keys of metadata sets/fields.
Determining the Key of a Metadata Set/Field
As a User
Confluence users can determine the key of metadata fields or sets by moving the mouse over the metadata set or field title within the metadata overview.
Image 1: Metadata Set Key (click to enlarge)
To display the key, go to a page where the metadata field or set has been added. Open the metadata overview by clicking the colorful Metadata icon at the top-left. Now hover your mouse over the metadata set (displayed at the top) 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.
As a Space Administrator
For the following steps, you need Space Administrator permissions.
As a Space Administrator, you can additionally go to a page and open "Space tools" > "Metadata". To find the correct metadata field key, click the tab "Metadata fields" or open the tab "Metadata sets".
Space metadata fields are displayed at the top, global metadata fields at the bottom.
Image 2: Metadata Field Keys (click to enlarge)
Troubleshooting
When entering keys of metadata fields or sets in a macro or the Confluence search, make sure that:
There are no spaces
They are written completely in lowercase
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
Examples for the Syntax of a Lucene Query
All news macros of the Enterprise Theme provide an input field for a Lucene query parameter. You can enter any valid search query to filter the results.
The only thing you need is the correct syntax, to be able to filter by metadata information.
Basic search terms with Lucene search syntax are explained at the beginning of this section. Find more complex examples below.
1) Show all pages where the location (a space metadata field) is either "Stuttgart" or "Dresden":
// Lucene Query
metadatafield.location:Stuttgart OR metadatafield.location:Dresden2) Show all pages where the contact person (a global metadata field) is Katherine Smith and the location (a space metadata field) is "Dresden":
// Lucene Query
global.metadatafield.contactperson:ksmith AND metadatafield.location:Dresden3) Show all pages with the metadata set "projects"
// Lucene Query
metadataset:metadataset.projects
Advanced Usage
4) Filter by the User Profile
The Enterprise Theme allows you to combine more in our content macros 🙂 If you use the User Profiles Add-on by Communardo you can combine the User Profile information to use the profile information of the current user. This allows you to provide a very user specific content listing in the Enterprise Theme Macro.
// Lucene Query
metadatafield.city:upc.currentUser.LocationThe part upc.currentUser.Location will be replaced by the location of the user (if such field exists). More information about this feature can be found in Use the Communardo User Profiles app with the Enterprise Theme News Macros and in the macro documentation of the Top Stories Slider, Blog Posts & Pages and News Boxes macros.
Parts of this documentation were copied from the Metadata documentation.