The Content by Label macro displays links to pages, blog posts and attachments that have been tagged with specific labels.

A working example

Below is a working example of the Content by Label macro, displaying content with the label 'LDAP'.

Using the Content by Label Macro

To add the Content by Label macro to a page:

Parameters

Parameter

Default

Description

Label(s)
(labels) 

None

Filter by label(s). The macro will display only the content tagged with the label(s) specified here. See also the Operator parameter below.

This parameter is required. Specify one or more labels, separated by a comma or a single space.

Author(s)
(author) 

None

Filter by author. The macro will display only the content created or updated by the author(s) specified here.

Specify one or more authors, separated by a comma.

Include this Content Type Only
(type) 

all

Filter by content type. The macro will display only the content of the type specified here.

Specify one or more content types, separated by a comma or a space.

Available values:

Show Labels for Each Page
(showLabels) 

true

Show or hide labels in the results.

Show Space Name for Each Page
(showSpace) 

true

Show or hide spaces in the results.

List Title
(title) 

None

Add a title or heading to the list.

Maximum Number of Pages
(max) 

15

Limit the maximum number of results to be displayed. Note that the results are sorted first, and then the maximum parameter is applied.

Display Excerpts
(excerpt) 

false

Include excerpts from each page listed. Note that you must have defined excerpts on each of those pages, by adding the excerpt macro to the page. Only the first few lines of the excerpt for each page are displayed.

Restrict to these Spaces
(spaces) 

@all

Filter by space. The macro will display only the content which belongs to the space(s) specified here.

Specify one or more space keys, separated by a comma or a space.

Special values:

Operator
(operator) 

OR

The operator to apply when matching content against the labels specified in the Label(s) parameter:

  • OR – Display content with any of the non-prefixed labels.
  • AND  – Display content with all of the specified non-prefixed labels.

    (info) Note that this parameter only modifies the behaviour of the Label(s) parameter and only affects label values without a plus (+) or minus (-) sign prefix.

Sort By
(sort) 

modified

Specify how the results should be sorted.

Values:

Note: If this parameter is not specified, the sort order defaults to descending, based on the last modification date (latest first). To change the sort order from ascending to descending, use the Reverse Sort parameter.

Reverse Sort
(reverse) 

false

Select Reverse Sort to change the sort from descending to ascending. Use this parameter in conjunction with the Sort By parameter. Reverse Sort is ignored if Sort By is not specified.

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

 

Macro name: contentbylabel

Macro body: None.

Storage format example

<ac:structured-macro ac:name="contentbylabel">
  <ac:parameter ac:name="spaces"/>
  <ac:parameter ac:name="author">admin,smaddox</ac:parameter>
  <ac:parameter ac:name="title">My labelled pages</ac:parameter>
  <ac:parameter ac:name="showLabels">false</ac:parameter>
  <ac:parameter ac:name="reverse">true</ac:parameter>
  <ac:parameter ac:name="sort">creation</ac:parameter>
  <ac:parameter ac:name="max">10</ac:parameter>
  <ac:parameter ac:name="excerpt">true</ac:parameter>
  <ac:parameter ac:name="labels">chocolate,cake</ac:parameter>
  <ac:parameter ac:name="showSpace">false</ac:parameter>
  <ac:parameter ac:name="type">page</ac:parameter>
  <ac:parameter ac:name="operator">AND</ac:parameter>
</ac:structured-macro>

Wikimarkup example

{contentbylabel:spaces=@personal,@self|author=admin,smaddox|title=My labelled pages|showLabels=false|reverse=true|sort=creation|max=10|excerpt=true|labels=chocolate,cake|showSpace=false|type=page|operator=AND}