This site has moved to the integrated Appfire documentation and information site for our apps.

From February 2024 this site is no longer updated.

Take a look here! If you have any questions please email support@appfire.com

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »


Overview

The {metadata-matches} macro totals up the number of matching pages which have a particular value for metadata. This result can be shown directly or can be used as input to another statistics macro.

In addition, this macro allows for another metadata value to be calculated for each matching page. If another metadata value name is specified the macro will display a calculation based on the values of this metadata on the matching pages rather than the count of the number of occurrences.

Parameters

ParameterRequiredDefaultNotesVersion
first parameter


The metadata value name whose values will be matched. This can include added metadata and internal metadata.

The value of the metadata to be matched is added to the macro placeholder (macro body).

If a value-name is NOT specified for a calculation in the value-name field, then the macro will return a count of the number of occurrences of this first parameter metadata value specified in the body of the macro placeholder.



function

sum

If a value-name is specified for a calculation, then the macro will use the specified function on the values taken from the matching pages and display the calculated value of this function.

  • sum - returns the sum of each non-empty value (default)

  • average - returns the average of each non-empty value
  • maximum - returns the minimum of each non-empty value
  • minimum - returns the maximum of each non-empty value

The metadata value that is compared includes any wiki markup for the value.


key
current space

Limits the content returned to be within the space with the given key.


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.


label

lImits the content to that with the specified label or labels. A comma separated list produces ANY pages that match.


type

Specifies which Confluence content types should be considered for a report.

This feature was based on the contentbylabel macro which has the same attribute.


value-name
sum

Second metadata value that can be used to generate a calculation - the default is sum. However it can also apply the same functions as used in the {metadata-calculate} macro.


Usage

To retrieve the number of pages with a particular value for metadata, choose the Metadata matches macro from the Confluence macro browser:

The macro editor requires the metadata value name to be added:

The value for the metadata is added to the macro placeholder

The value added to the macro placeholder must include all the value - here the value includes some wiki format.

In this example, the page where the macro is added will display simply the sum of the number of pages with matching metadata values for the Current Lifecycle status metadata value name:

This value can be used for other Confluence statistical macros such as the Confluence Chart macro.


Adding a metadata value-name for a calculation of the values on the matched pages

Adding a metadata value name to the value-name option in the macro editor adds the ability to perform calculations on the values of a specified metadata on the matching pages.

In our example above, the {metadata-matches} macro displays the count of the number of child pages where the Current Lifecycle status metadata has a value of |Active|.

If another metadata is added to the value-name field the macro will perform a calculation on the values of this second metadata for any occurrences on the matching pages.


In the example, in the macro editor:

  • adding an existing metadata name, Feb Hours 

  • choosing the function as sum

  • amends the macro placeholder to show the added value-name parameter

The macro body still contains the metadata value |Active|, the macro will only perform the calculation on the pages with this matching value.

The page display will show the sum based on the values of Feb Hours on the matching pages:

In the example, across the matching pages where the metadata Current Lifecycle status  has a value of |Active|, the sum of the metadata Feb Hours values is 84.


A simple example of use of the {metadata-matches} macro is to add multiple versions of the macro to populate a table, creating a dashboard of information from a group of pages

Multiple versions of the metadata-matches macro can also be added to the Confluence chart macro to visualise and present the collated data from each report.

Reference Markup

{metadata-matches:Current Lifecycle status}|Active|{metadata-matches}

The macro will retrieve the number of times the Current Lifecycle status metadata values for the child pages of the current page are equal to |Active|.

If there is any formatting as part of the  metadata value, this must be included in the body of the {metadata-matches} macro.

The report is displayed as a count of the number of pages that currently with this value for the metadata.


 If a calculation is required for a metadata value on these matching pages, an example of the markup required for the default sum of these values is:

{metadata-matches:Current Lifecycle status|value-name=Feb Hours}|Active|{metadata-matches}



Related Comala Metadata App macros

Related documentation


  • No labels