The following properties are mandatory to appear in the document properties table:
Doctype
Name
Short Description
Sort Key
Especially a missing Doctype property is reported immediately as an error.
This error is also shown, if the page is lacking a label that matches its doctype. Therefore, if the Doctype property is present (and in the correct language), check if the Confluence page is labelled with the document type's identifier.
Section
level
2
title
Language Problem
Each page is created based on the site language (more specific: the site locale). If the site language differs from that of the page, the macro is not able to find any document properties.
Info Box
This is really only relevant for properties that have meaning to the system. Only in this case the system has to translate the name of the property. Other properties are usually passed through without translation. Therefore users may add any number of properties without the need of providing localization bundles (these are resources that contain text for a specific language).
This problem occurs usually, if a space is imported from a site based on a different language. There is no workaround for this problem than translating the pages. This is a problem - to our knowledge - that is shared by all macros that display generated text resources.
Info Box
A page in Confluence containing generated text will contain this text regardless of any changes of the language after creation. This is similar to any user added text. The user (without the help of third-party plugins) writes text to a page in one language.
Section
level
2
title
Only one Version of the Macro
Please note that there must only be one instance of this macro on a page.
This macro is the working horse of projectdoc. It provides the basic information to transform a Confluence page into a projectdoc document. This allows users to employ automatic lists to display documents by their metadata.
The value of a property is stored in the database as an unlimited string (StringLength.UNLIMITED). It depends on the database of the Confluence installation how large this actually is.
Keep in mind that most clients assume that these values are typically small. The values are also cached for fast access.
Section
title
Static Values
The property value should either be text or have a macro that always returns the same value.
Caution Box
title
Dynamic Content as Property Value - think twice!
If the macro returns dynamic values, the value cannot be used in queries.
Values are stored in the Lucene Index at the time the document is stored. If the document contains dynamic content, changes in the content will not be reflected in the index until the page is stored again.
There is no guarantee that a dynamic value renders the same way in two different situations.
It is important to note that there are use cases where a dynamic property value is used, but these use cases (typically) must not include searching. Therefore the projectdoc Toolbox does not prevent the use of such macros as property values. If you ensure that the values are static in the context of the use case, then you may use a dynamic macro. For example:
Use a separate space with documents that do rarely change. On every change on documents of that space all depending spaces, that is a space where there a documents with property values that make searches, need to be reindexed.
It is save to use the dynamic content properties as long as the macros point to properties on the same page.
Tip Box
As a rule of thumb: The Name List Macro (and its relatives) provide static content, while the Display Table Macro or the Display Document Property Macro does not. Since the display property macros keep track of references they are in many use cases safe to use. Searches, like executed by the Display Table Macro and its relatives, should be avoided (and maybe will be forbidden in future versions of the projectdoc Toolbox).
Section
index
true
title
Related macros
Macros to define document properties.
Display Table
doctype
macro
select
Name, Short Description, Tags
sort-by
Tags, Name
where
$<Tags> = [Define Properties]
Macros related to the Document Properties Marker Macro.