Page Properties Report Macro

The Page Properties and Page Properties Report macro work together to enable you to show summary information from one page on another page. You can see examples of these two macros in action on the Decision and Product Requirements blueprints.  

This macro was previously known as the Details Summary macro. 

Adding the Page Properties Report macro to a page

To add the Page Properties Report macro to a page:

  1. In the editor, choose Insert > Other Macros > Page Properties Report.
  2. Enter the Labels you want to report on - this is the label added to pages containing the Page Properties macro.
  3. Further narrow down your search by adding more fields, or specifying a Page Properties ID (more info on this below)
  4. Choose Insert.

Here's how the macro looks on your page:

And here's how you would set it up in the macro browser:

Reporting on specific Page Properties macros

It's possible to add multiple Page Properties macros on a page, and choose whether to include all or only specific macros in the report.  The Page Properties macro includes an optional ID parameter that can be used to identify specific Page Properties macros.

To show the contents of: 

  • Selected Page Properties macros in the report - specify the label for the page and the ID of the particular Page Properties macro (under Options)
  • All Page Properties macros in the report - specify just the label for the page - leave the Page Properties ID field blank.

Note: The Page Properties Report macro can only accept one ID.  

CQL fields

CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add filters to build up a search query, adding as many filters as you need to narrow down the search results.

Use the Add a filter link to add more filters to your query.
 

Use AND, OR, and NOT operators
  • For an OR search, specify multiple values in the same field.
    So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label field, like this:
  • For an AND search, add more than one filter and specify a single value in each.
    To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second Label field to the macro, and put 'label-b' in the second one, like this:

    Put simply, OR values are entered in the same filter, AND values are entered in different filter. 
    Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to add that filter more than once.  
  • For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.


You can use the following CQL filters to build your query:

FilterDescriptionOperators
Label*

Include pages, blog posts or attachments with these labels.

OR (multiple values in the same filter)

AND (multiple Label filters)

With ancestor

Include pages that are children of this page.

This allows you to restrict the macro to a single page tree.

OR (multiple values in the same filter)
Contributor**

Include pages or blog posts that were created or edited by these people.

OR (multiple values in the same filter)
Creator

Include items created by these people.

OR (multiple values in the same filter)
Mentioning user

Include pages and blog posts that @mention these people.

OR (multiple values in the same filter)
With parentInclude only direct children of this page (further sub-pages won't be included)EQUALS (one page only)
In space**Include items from these spaces.OR (multiple values in the same filter)
Including text**Include items that contain this text.CONTAINS (single word or phrase)
With titleInclude items that contain this text in the title.CONTAINS (single word or phrase)
Of type**Include only pages, blogs or attachments.OR (multiple values in the same filter)

* This field is required in CQL-powered macros.

** You can add these filters in CQL-powered macros but in search they're part of the standard search filters, so they don't appear in the Add a filter menu.

Macro display options

These options control how the macro appears on your page.

ParameterDefaultDescription
Page Properties IDBlankIf not specified, the report will show data from all Page Properties macros on a page, where there are multiple macros. Specify an ID to include only data from Page Properties macros with the same ID.
Title column headingTitleThe heading to display on the first column in the report table. This column contains links to pages displayed by the report. The default column heading is 'Title'.
Columns to show

If not specified, the report will show all columns. You can specify a comma separated list of columns to include.

If your column heading includes commas, use double quotes around the column name. If your column heading includes quotes, use double quotes. For example, A column, "My ""new"" column, yes", Third column

Number of items to display30

Number of items to display in the table before displaying pagination options for additional items.

The macro can display a maximum of 3000 pages. System administrators can increase or decrease this limit. It is a good idea to use pagination, rather than listing all your pages in one go.

Sort byModified

Sort the table by a specific column heading. Enter the column name, exactly as it appears in the corresponding Page Properties macro.

Select the Reverse Sort check box to sort the table in reverse order.

Show Comments CountNoDisplays the number of comments for each page in the table.
Show Likes CountNoDisplays the number of likes for each page in the table.

Troubleshooting

If your report is empty, check:

  • You have entered the label correctly and that the label does appear on pages containing a Page Properties macro.
  • The Page Properties macros on each page are configured correctly. 
  • Any other fields you have specified have not narrowed your search too far (for example there are no pages with that label under the Parent page you've specified).

Limitations

You can enter a maximum of 60 labels in the macro browser.

The macro can display a maximum of 3000 pages. System administrators can increase or decrease this limit using the pagePropertiesReportContentRetrieverMaxResult system property.

Last modified on Nov 29, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.