Using document and space properties as variables in the projectdoc Toolbox for Confluence.
Define a Property
Properties can be define on document and space level.
A projectdoc document is a Confluence page with properties defined by the use of the Document Properties Marker Macro.
A document property is define in a table row in the body of a the Document Properties Marker Macro. The name of a property is required to be a simple text string, but the value may also be macro.
A dynamic value is a value that is changed at request time. This is opposed to a value that is only changed once a page is saved.
The value of a property should not have a dynamic value since values are used with indexing and will only be updated when the document is saved.
A space property is actually a document property that is defined on the space homepage.
For more information on space properties, please refer to the tip Using Space Properties.
Using Properties
A variable has a value that may be changed. Document and space property values can also be changed. The following sections show uses cases where the change of a property value is reflected on a page that refers to it.
A property value may be simply be rendered or control what is rendered.
Property Reference
A property may simply be referenced with a Display Document Property Macro. Whenever the value of the property is changed, the value will change in the page using this macro is rendered.
The macro can also be used as a property values, since a page gets updated whenever a referenced page is.
There is a number of macros that allows user to render property values.
| Macro | Short Description |
|---|---|
Renders the value of a property of a document. | |
Renders a template with property references. | |
Displays a document property from a referenced document. | |
Displays a single property of a document that is referred by a property of another document and concatenates it with the value of a local property. |
Authors may also choose to render properties of a list of documents in tabular form using the Tour Macro. Each property is rendered in a column or multiple properties may be rendered in a table cell using a template.
Control Rendering Sections
With document and space properties authors can control whether or not to render a section (using the Section Macro) or a region (using the Content Marker Macro) on a page.
Authors may also check for a property for any value (i.e. require the property not to be empty).
The use case for the above example would be to show the section only if the document is authorized by a person. The authorization is provided by adding the name of the person who give the authorization.
This use case does not protect the authorization process. Any user with write access to a page may alter any property (remove it or change value).
List Documents
Document properties can be used to control which documents are shown in dynamic list. The Display List Macro and Display Table Macro provide a parameter named Where to specify queries. A Where clause looks like this:
The following shows the same query but with exact match. While the query above will also match types like "Great Tip" and "Lousy Tip", the query below matches only for "Tip".
Once the value of a property changes, the query will update the results the next time the page with the dynamic list is rendered.
For date values there is a normalized property to make it easier to match values despite of the formatting. So instead of "Creation Date" authors may want to use "Creation Date§".
In case dates or other property types need to be compared, check out Search Functions on Search Tips or read the tip Search Functions.
The Transclude Documents Macro transcludes sections from documents that are part of a result set. The query is also specified by a Where parameter as shown above.