Versions Compared

Old Version 2

changes.mady.by.user Robert Alexander Marshall

Saved on

compared with

New Version 3

changes.mady.by.user Robert Alexander Marshall

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel3
minLevel2
absoluteUrltrue
excludeSee also
typeflat
separatorpipe

Overview

The metadata-report macro shows metadata from matching pages in a tabular report.

You can use the macro to display multiple pieces of metadata from a single page or a group of pages.

Any metadata created with the Comala Metadata App metadata or metadata-list macros can be displayed in the report. 

...

The macro will also retrieve values for any Confluence internal metadata, such as Page alongside metadata created with the Comala Metadata App.

The macro can be used to select: 

  • a selection of multiple metadata values from a single page

  • a selection of multiple metadata values from a group of pages in the same space or other named space

The macro can also be configured to calculate a sum of all the retrieved values for an individual metadata value name.

Parameters

Parameter

Required

Default

Notes

Version

Fields

(tick)


The list of fields (columns) to be included in the report. This can include added metadata and internal metadata.


label



Limits the content to only that which has the specified label(s).

A comma separated list produces ANY pages that match, while using + will give ALL pages.

Parentheses may be used to build up complex expressions, e.g |labels=(yellow,red)+fruit|


key



Specifies the space key from which the pages are listed.


root


current page (@self)

Use @self for the current page (the default), @parent for the parent page, or the name of any page, e.g MySpace:MyPage.

If this is specified and the pages option is not, then the report will run over only the pages listed here.


pages



Specifies a set of pages to grab from the root page(s).

Supports 

  • @children

  • @ancestors

  • @descendants

  • @identity

For example, |root=@self|pages=@children will give all children of the current page. This can be used in combination with the labels option to find all children with a particular label.


link



Specifies which columns in the report should link back to the content.


maxResults



Specifies the maximum number of results in a report. Default is 500.


order


descending

What order should results be sorted in?

  • ascending – A→Z

  • descending – Z→A

You can combine this with sort.


sort


modified

Specifies which column in the report should be sorted by.

You can also include a hint for the sort method before the sort direction. For instance "Name as istring asc" or "Name as istring" will apply a case-insensitive comparison, considering values as string.

Other choices include

  • "as date"

  • "as number"

  • "as string" (case-sensitive)

Default is case-insensitive comparison.


totals

Specifies a comma separated list of values to be totalled.

type



Specifies the content type to search within for the specified metadata value names.

  • page

  • blogpost


value-name

The metadata value that will be used for a calculation

Usage

Excerpt

To retrieve multiple metadata values from a page or pages, choose the Metadata report macro from the Confluence macro browser:

Image RemovedImage Added

The macro editor allows you to configure the macro before you Insert the macro to the page:

metadata report macro browser editor showing fields, space key and link options

The macro requires you to enter at least one metadata value name into Fields. Multiple metadata values can be retrieved by adding a comma separated list of metadata value names.

Adding the metadata value names and choosing to Insert the macro adds the macro placeholder to the page being edited.

This displays a table on the page of the metadata value names and their values from the child pages of the current page.

For example, the macro placeholder above would display the values for three pieces of metadata for each of the child pages:

Image RemovedImage Added

The retrieved metadata values for the metadata are displayed in a separate row for each child page.

If the metadata value names are not found, or there is no value has added, the table will display the metadata value names specified in the macro but with no value(s) added. The columns are in order of listing of the metadata value names in the macro editor.

Additional options in the macro editor allow you to customise the macro.

Customizing the metadata-report macro to select pages for the report

The choice of source pages for the metadata report can be customized as follows:

  • Space key determines the space or spaces for the page metadata to be listed

  • Content type - pages or blog posts

  • Root defaults to the current page and will report the metadata values on the child pages of the current page 

You can choose the root to be parent page of the current page using @parent or the specify the name of a page for the root page. If these are added then the source for the metadata report will be limited to the metadata on the specified root page. 

To retrieve the metadata from a related group of pages to a specified root page, you must use the Pages option.

Image RemovedImage Added

The Pages option can be used with the Labels option to select pages with a particular label from a group of related pages.

Macro Totals option

The report can provide totals for certain columns of metadata values using the Totals option. 

In this example two metadata value names are added to the Totals option as a comma separated list:

...

  • sort the retrieved metadata values in ascending or descending order.

  • display a set number of results.

Reference Markup

The basic format of the macro is:

Code Block
languagetext
{metadata-report:Name,Author(s),Versions}

...