A short introduction on compiling projectdoc documents in dynamic lists using constraints.
Tagging a Document
To create a report on documents these documents need to have properties to select upon. Only documents that meet a given query constraint must be listed in the report. The act of adding properties for selection is called tagging.
A Confluence wiki page becomes a projectdoc Document by adding the Document Properties Marker Macro. This macro expects a table with three columns to specify the properties of this document. A Name or a Short Description is a property, but also Tags and Type. Authors may specify any property in this table since a property is simply
- a name (stored in the first column of the table),
- a value (stored in the second column), and
- an optional control (which goes into the third column, e.g. hide to not show the table row when rendered in the view).
As you can see the value for a property may be a simple text string (like "Reporting"), but may also be an image (not shown in this example), or a macro (like 
).
Reporting on Documents
Reports may have many forms. In this short tip we'll focus on the Display Table Macro. It allows to list a number of projectdoc documents (aka Confluence pages with our Document Properties Marker Macro) that match the given query constraint. The list of results is rendered in form of a table: each document of the result is rendered in a table row, each property of the document, in a table column.
| Name | Property 1 | Property 2 |
|---|---|---|
| Document 1 | ||
| Document 2 | ||
| Document 3 |
In the above table the empty cells will be filled with the "Property 1" / "Property 2" of the documents named "Document 1" to "Document 3".
The rendering may also be in other formats, but we'll keep it simple here. It is recommended to use this macro for tables and the Display List Macro or its cousin Display List Template Macro for lists. These macros may render trees of results, while the Display Table Macro renders the result list always flat.
The Display Table Macro has a couple of parameters, but for this short example we focus on two of them:
Select: Enumerate the properties you actually want to render in the columns – if not specified the Name and Short Description is rendered per defaultWhere: Specify the query constraint
Note that the name of a property you use as constraint must not contain spaces! Hence we type "LevelofExperience", which is not easy to read. We therefore recommend to use property name delimiters ($<Property Name>) so that projectdoc will do the translation for you.
The following screenshot shows the altered Where parameter.
One could argue that this is not really easier to read:
$<Type>=[Tip] AND $<Level of Experience>=[Novice]
But it comes with an additional feature! By using the square brackets on the side of the expected value you can make an exact match. While in the before mentioned query you may also find document with types having the string "Tip" in it (like "Favorite Tip" or "My Tip of the Month"), the second version only allows types that match this three letter word (> T i p <) and nothing else.
And to put more sugar on the ugly special syntax: you can use the property value of your current document in your queries as in
$<Type>=[${Type}] AND $<Level of Experience>=[Novice]
Note that we match type with an exact match to the same type our document is type of.
One important caveat: In case your document may have multiple values for a property (for instance for Tags), you would need to use the list constraint like this:
$<Tags>~(${Tags})
And just in case you are wondering: The left and right property need not to be the same. They are often, but not always as the following examples shows:
$<Authors>=[${Name}]
The example shows a Resource document that lists its authors. A document on a person may want to list all known resources. Note that we do not need to use the list operator here, since the document has only one name (splitting the list of authors and matching the values individually is done automatically for you by the projectdoc Toolbox).
For more information on constructing constraints, please refer to Search Tips!
No dynamic Property Values
Property values must not be dynamic. That is a property value must not be a value that changes on request time.
That said, to be more precise: You cannot search for a property with a dynamic value and expect consistent results. If consistency is not a problem or your information design will use a given property only for rendering, but not for searching, then use any macro you like. But a mantra that is easily to remember, and expecting users with a novice level of experience here, is this: No dynamic property values.
More background information to understand this better: Imagine a macro that renders the name of the current user. This macro would render a different value for different users. If Bob see the page it renders "Hello Bob!", when Alice visits the page the macro will greet with "Hi Alice!".
This is not a problem when rendering the page, but when searching the page. All properties are stored in the Lucene index of Confluence. This way the this document can be found in case a user is looking for all documents of type 'Tip'.
Assume a macro that renders the name of the current user would be saved as a value for property 'Current User' by Bob. All users would find this document by 'Current User'='Hello Bob!'. When Alice edits the page and saves it, from now on the document will be found by 'Hi Alice!'.
Just in case you'll think that this would be a cool feature for storing the name of the last author, don't! 
There is an Artificial Properties named Last Modifier that automatically provides this feature for you.
Note that a list of documents is also dynamic and therefore must not be used as a property value. You may use it, but you must not expect to find the property by the current values.
Novice Users
For novice users: Just keep in mind to be careful when selecting macros for property values. If the value is dependent on request time, your search result will not be consistent.
