Working with Properties

Compare the  Page Properties Macro / Page Properties Report Macro with the Document Properties Marker Macro / Display Table Macro

Users employ the Page Property Report Macro to query pages with properties and display them in a table. In order to work the Confluence pages to select have to contain one or more instances of the Page Properties Macro . In the Page Properties Macro users define the properties of the page as key-value pairs in a table.

Users of the projectdoc Toolbox use the  Display Table Macro to define the queries instead of the  Page Property Report Macro. The Document Properties Marker Macro replaces the Page Properties Macro to define the document properties.

So let's first have a look at the differences in specifying properties.

Compare Defining Properties

Confluence Page Property Report Macro

The sample used in this demo: Topic with Page Properties 1.

Here is a screenshot from the Page Properties Macro :

You may have several sets of properties identified by a unique ID (which is optional). The table with the properties is straight forward. First column contains the name, the second column the value.

Document Properties Marker Macro

The sample used in this demo: Topic with Document Properties 1.

Here is a screenshot from the Document Properties Marker Macro :

You may only have one definition of properties per document. Instead of two columns, you have three. Besides the name and the value for the property there is a third column for Property Controls. A very handy control is hide that allows users to prevent a line in the table from rendering.

The macro configuration has the following parameters:

Besides the already mentioned identifier users decided whether to show the table as a whole or not at all.

The macro configuration has the following parameters:

The macro also allows to hide the whole table. it also allows to render the properties as a definition list and to extract a special property called Short Description. This allows to render the properties more compact.

 The table with the properties is rendered on the page defining the properties as follows.

 The table with the properties is rendered on the page defining the properties as follows.

Definition List

Table

So this is the end of defining properties for a Confluence page. Now have a look on how to query from pages!

Compare Defining Queries

Confluence Page Property Report Macro

The macro allows you to define a query based on a predefined set of properties.

The selection process is elegant, supporting the user very nicely to select on the properties.

projectdoc Display Table Macro

The macro allows to define a query based on any property.

The query has to be specified with a simple text field. The user is not as well guided through the selection process as with the Confluence macro. The benefit is that the constraint can be based on any property the user specified as a property.

Furthermore the query can be defined using AND, OR, NOT and brackets. It is an enhanced version of a Lucene query.

To select the properties to be shown in the table for the result set the process is straight forward:

To select the properties to be shown in the table for the result set the process is straight forward:

So here is a live result of the Page Property Report Macro :

NameCategoriesIterationProperty 1
Topic with Page Properties 1
  • Cat 1
  • Cat One
Filled
Value 1
Topic with Page Properties 2
  • Cat 2
  • Cat Two
Focused
Value 2

So here is a live result of the Display Table Macro :

Name Categories Iteration Property 1
Content to Transclude
  • Cat 1
  • Cat One
Filled
Content with Placeholders to Transclude
  • Cat 1
  • Cat One
Filled
Topic with Document Properties 1
  • Cat 1
  • Cat One
Filled
Value 1
Topic with Document Properties 2
  • Cat 2
  • Cat Two
Focused
Value 2

More Use Cases

The Page Property macros provide some features that are don't provided by the macros from the projectdoc Toolbox. For instance you may define multiple sets of properties and identify them by an ID. We expect readers to know about the features of the Confluence macros quite well. Therefore we do not show them here and instead show features of the projectdoc Toolbox macros that are not supported by Confluence natively.

Name may be any Column

Macro Configuration

Rendered Result

Categories Iteration Name Property 1
  • Cat 1
  • Cat One
Filled
Content to Transclude
  • Cat 1
  • Cat One
Filled
Content with Placeholders to Transclude
  • Cat 1
  • Cat One
Filled
Topic with Document Properties 1
Value 1
  • Cat 2
  • Cat Two
Focused
Topic with Document Properties 2
Value 2
No need to have Name as a Column

Macro Configuration

Rendered Result

Property 1 Categories Iteration
  • Cat 1
  • Cat One
Filled
  • Cat 1
  • Cat One
Filled
Value 1
  • Cat 1
  • Cat One
Filled
Value 2
  • Cat 2
  • Cat Two
Focused
Constrain on ANY Property

Macro Configuration

Rendered Result

Property 1 Categories Iteration
Value 1
  • Cat 1
  • Cat One
Filled
Select Properties and Sections

Macro Configuration

Rendered Result

Name Description Section 1
Content to Transclude
Content with Placeholders to Transclude
Topic with Document Properties 1

A description one.

Section content 1.
Topic with Document Properties 2

A description two.
Show the Tables vertically

Macro Configuration

Rendered Result

Content to Transclude

Iteration
Filled

Content with Placeholders to Transclude

Iteration
Filled

Topic with Document Properties 1

Iteration
Filled
Description

A description one.
Section 1

Section content 1.

Topic with Document Properties 2

Iteration
Focused
Description

A description two.
Rename Columns

Macro Configuration

Rendered Result

Name MY PROPERTY
Content to Transclude
Content with Placeholders to Transclude
Topic with Document Properties 1
Value 1
Topic with Document Properties 2
Value 2
2-Column Results as Definition List

Macro Configuration

Rendered Result

Content to Transclude
Content with Placeholders to Transclude
Topic with Document Properties 1
Value 1
Topic with Document Properties 2
Value 2
2-Column Results as List

Macro Configuration

Rendered Result

  1. Content to Transclude - Provides content via the Content Marker Macro.
  2. Content with Placeholders to Transclude - Provides content using placeholders via the Content Marker Macro.
  3. Topic with Document Properties 1 - A short description 1.
  4. Topic with Document Properties 2 - A short description 2.
Constrain on ANY Property

Macro Configuration

Rendered Result

Name Short Description Iteration
Topic with Document Properties 1
A short description 1.
Filled
Topic with Document Properties 2
A short description 2.
Focused

The complete where clause looks like this:

($[Property 1]="Value 1" OR Categories = "Cat 2") NOT
                          Iteration=Facade

Summary

Confluence calls the properties page properties, while the projectdoc Toolbox uses the name document properties.

Page properties are easy to use, but up to version 5.7 of Confluence provide limited capabilities to select and display the properties. While document properties provide some additional features, people my consider specifying the where clause to constrain the search result as complicated.

If page properties is providing all you'll ever ask for, you should stay with it: it is free and is part of every Confluence installation.

If you are asking for more and paying for additional features that make you more productive is not a problem for you, check out document properties.

The following table lists features that are related to one of the macros discussed, but are implemented by different macros. In this case the macro providing the feature is listed. No extra cost is involved to use the mentioned macros, since all these macros are either part of Confluence or the projectdoc Toolbox Add-on.

Feature

Page Properties

<=5.7

Page Properties

>=5.8

Document Properties
Column Selection
YES
YES

YES

Page QueryBy Space and LabelBy Space and predefined PropertiesBy Space and any Property Value
Complex queries
NO

YES
Limited CQL (AND)

YES
Lucene Syntax with some preprocessing
Specify Sort Order
BY 1 COLUMN NAME
BY 1 COLUMN NAME
STABLE SORTING USING MULTIPLE COLUMNS
Rendering

Table
List
(Content by Label Macro)

Table
List
(Content by Label Macro)

Table
Vertical Table
Definition List
Bullet List
Numbered List

Change Column Heading
TITLE ONLY
TITLE ONLY
EVERY HEADING
Limit number of Hits
NO
YES
YES
Pagination
YES
YES
NO
Show Comment and Like Counts
YES
YES
NO
Multiple Sets of Properties
YES
YES
NO
Property Controls Supported
NO
NO
YES
(e.g. "hide")
Select Single Values
NO
NO
YES
Display Property Macro / Display Properties Macro
Control Hits
NO
NO
YES
Tour Macro
Access Section Content
NO
LIMITED ONE EXCERPT
YES
Transclude by Properties
NO

LIMITED ONE EXCERPT

YES
Transclude Documents Macro
Allows to Hide Properties Table
YES
YES
YES
Support Calculations
NO
NO
YES
numeric
Space Properties
NO
NO
YES
hierarchic
(delegate and search)
Control Properties Table Rendering
NO
NO
YES
Cost
FREE
FREE
STARTS WITH $10
see prices for more users
No Extra Installation required
YES
YES
NO
Supports Confluence Version4.x (limited features) and 5.x5.8+5.5+
VendorAtlassianAtlassiansmartics

Macro Parameters

Here are screenshots to compare the configuration options of the two query macros visually.

For detailed information please refer to 

For detailed information please refer to