Versions Compared

Old Version 1

changes.mady.by.user Almuth Boehme [Communardo]

Saved on

compared with

New Version 2

changes.mady.by.user Almuth Boehme [Communardo]

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Anchor
top
top
 
Status
colourGreen
titlesince version
2
3.
2
0

Note

In order to insert macros in Confluence, you need to possess editor permissions for the page.

There are several macros you can use to display metadata in Confluence or to select pages on the basis of their metadata. This page will show you how to use the Content by Metadata macro.

Introduction

The Content by Metadata macro is used to display the page metadata of multiple pages in a list according to a search criterion.

An example result can be seen in this preview:

edit mode of the content by metadata macro showing a preview of a simple list of page titles as linksImage 1: Content by Metadata Macro (click to enlarge)


The search criterion is defined by filtering for metadata fields and certain values of those fields or metadata sets. Details on using the CQL dropdown filters are described in Searching with Metadata (v 3.0) and the next section.

Insert excerpt
Macro "Metadata Overview" (v 3.0)
Macro "Metadata Overview" (v 3.0)
nopaneltrue

Parameters
Anchor
parameters
parameters

The following parameters are available for the Content by Metadata macro. To display all of the parameters, click "Show" next to the heading "Options".

ParameterDefaultDescription
FiltersNoneOptionalDefine metadata fields and metadata field values, and metadata sets to filter results displayed in the metadata overview macro. Can be left empty if expert filter criteria is used (see next parameter).
Expert filter criteriaNoneOptional

Define more comprehensive filter queries to filter results displayed in the Content by Metadata macro. Can be left empty if filters are used (see prior parameter).

Expert filter criteria are defined using the metadata sets and field keys and the Lycene search syntax. Please also see  Determining the Key of a Metadata Set/Field.

Placeholders are supported to make the output of the macro more dynamic.

The following parameters are available:

  • The current page object by using the placeholder $content
    • It is basically the data object used internally by Confluence please see the API Documentation for full capabilities

    • Example: to show all content with metadata links to the current page

      Code Block
      metadatafield.linkfield:$content.id
  • The current user object by using the placeholder $user

    • Example: Show all pages with the current logged in user defnined in a metadata field

      Code Block
      metadatafield.userfield:$user.name
  • The value of a certain field of the user's profile by using the placeholder upc.currentUser.<FIELDNAME>. This parameter works for all field types except multiselect and the About me field. The add-on User Profiles for Confluence needs to be installed.
Sort by
Page title ("title")OptionalDefines the metadata field whose values will determine the sort order of all entries.
Sort DirectionASCENDINGOptionalDefines the sort direction of the table entries according to the values entered in the "Sort by column" column.
Number of items to display20Optional

Defines the maximum amount of pages that are to be displayed in the macro. If the filter results contain more items, the output will be cut off. The parameter "Show more results" can be set (see below).

Show key of spaceUncheckedOptionalShow the space key of the space where the page is located. It will be displayed in brackets behind the title.
Show more resultsUncheckedOptionalDisplays a "load more" link at the bottom of the list.

Permissions

Note

Content 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".

The search results are filtered according to the permissions of the logged-in user. This means that you will only see pages you are allowed to access in the Content by Metadata macro.

If the page or space is not otherwise restricted, pages that can be accessed anonymously will appear for anonymous users.

Use Cases for Expert Filter Criteria

1) Example from the Metadata demonstration space "Product Directory" - show all pages with the metadata set "Product Info" (metadata set key "democaseproductinfo"), which are part of the space "Product Directory" (space key "DEMOCASEPRODDIR"):

Code Block
metadataset:metadataset.democaseproductinfo AND spacekey:DEMOCASEPRODDIR

2) Personalization of Confluence content with the help of upp - show an overview of all pages with the metadata set "Product Info" where the metadata field "Technology" equals the content of the user profile field "Technology" of the current user:

Code Block
metadataset:metadataset.productinfo AND metadatafield.technology:upc.currentUser.Technology

For further explanations of this use case, please see How to Get Started. Available options for placeholders are described in the section Parameters above.

You can find further details on basic and complex search queries as well as determining the correct field or set keys in Searching with Metadata (v 3.0).

 

Back to Top

Include Page
_Version Switch
_Version Switch