projectdoc Toolbox

A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.

Audience

Template Author

Categories

Transclusion / Marker

Tags

Type

Content Organization, Content Reuse, Properties Management

Since

1.0

This macro contains the document properties in a table. The first column contains the name of the property, the second column contains the value. The value may be a macro to be evaluated. The macro should return a static value. The third column contains controls.

It is very important to note that the property values are used in the Lucene index.

Therefore property values must not contain sensitive (secret) information!

If a page is accessible for a user, all properties of that page will also be accessible for that user.

Here is an example of the macro in edit mode:

Macro Body with a valid Document Properties Table

The following screenshot shows the macro with a valid document properties table:

Document Properties provides information about the standard properties of projectdoc.

The following controls are valid:

delegate: Signals that the property should be transcluded from the delegate document.
export: Exports the property as metadata.
export-schema: Exports the property as schema information.
hide: Prevents the property from being displayed. This allows to add properties to use for selection in queries, but hide them when displaying the document.
is-block: Prevents the property value from being disblocked.
is-no-template: Marks the value of a property as not being a template despite it may contrain a placeholder reference.
is-single-value: Prevents the property value from being split into a list of values.
mandatory: Tags a property to be mandatory.
noindex: Prevents the property from being indexed with Lucene. A property marked with this control will neither be added with a keyword nor added to the body of the document as text.
preserve: Prevents cleanup services from applying their changes to name, value, and controls of a property.
show: Renders a property even if the value is blank.
supplied: Marks a property as being imported from another projectdoc document.
supply: Marks a property as importable by other projectdoc documents.
unsupplied: Marks a property as being imported from another projectdoc document, but its supplied status overridden by a local configuration.
value-separator: Allows to specify an alternative value separator.

Note that the macro should be the first element of the document.

Properties within the table may refer to other properties, also long as the property has been defined earlier.

If you copy names and values for your properties table, there may be invisible elements that will prevent projectdoc to recognize your values properly. If for some reason you happen to not match a given value or your queries do not find a specific property, please check your code with the Confluence Source Editor!

See Cannot access Property from a Document for details.

Properties

Doctype

Specify the type of the document. Each document is required to have one and only one type.

The doctype may be overridden by the document property named Doctype. This is only supported to be backward compatible with documents that have been created where the doctype was specified by a property.

Since 4.2

This parameter is available as a default value for the document's type since version 4.2.

Override

If checked information passed from the space configuration will be overridden by this macro.

Note that every property will be overridden.

Hide

If checked the table containing the properties will not be rendered.

For some pages the metadata is irrelevant to the reader or may be rendered by other means. In this case set this flag to true.

The value may be set by the Space Property hide-metadata. If you want to override this, use Override.

Delegate Document

Allows to specify a document to delegate to in order to fetch properties and sections. The delegate document is consulted as a backup for properties and sections.

To transclude a property from the delegate document, use the delegate control.
To transclude a section, check the the delegate parameter of the Section Macro.

This feature makes it easy to annotate an existing document. If a document should not be edited, e.g. because it is imported after a release, the delegation parameter allows to transclude content from that document and add additional sections.

If you need to transclude parts of a section and also have to add to that section additional information, use the Transclusion Macro.

Available since version 1.10.

Render As

Select a rendering mode for the document properties.

The following values are valid:

Value	Description
table	The properties are rendered in a table. The first column is the property key, the second the property value. Controls are not rendered, since they are not important to the reader.
definition list	The properties are rendered as a definition list. The property key key is the definition term, the property value the definition value.
horizontal table	The properties are rendered with a heading (property key) in the first and the data (property value) in the second row. Available since version 6.0.4.

The value may be set by the Space Property render-metadata-as. If you want to override this, use Override.

CSS Class

This controls the formatting of the table. The CSS class applied to the table or definition list.

Extract Short Description

Renders the short description in front of the properties table.

The short description is displayed even if the properties table is set to hide.

Details

Mandatory Document Properties

The following properties are mandatory to appear in the document properties table:

Doctype - must be plain text
Name - optional if Nameless Documents are in use (note that space homepages cannot be nameless)
Short Description - optional if no overviews e.g. using the Display Table Macro using default selection is used

Especially a missing Doctype property – since version 2.4 also if the macro contains no table – is reported immediately as an error.

This error is also rendered if the language of the site differs from the language defined for the user. Please make sure that the browser's language (or locale) matches that of Confluence (users with write permission typically experience no trouble if their profile has the correct language set). See Language Problem below.

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.

The language for the whole site can only be configured by an admin.

Example Configuration for German (Deutsch)

Note that this has nothing to do with the Indexing Language of General Configuration. This is typically not changed from its original value (which is English even if the global default language is set to another value).

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.

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.

If a document has already been created with the wrong language, all property names and sections need to be replaced (for instance the macro is looking for 'Dokumenttyp' since the language is set to German, but the property in the document reads 'Doctype'). This is because a page in Confluence has no reference to the blueprint it has been created with. Often it is easier to create a new page with the blueprint wizard and copy the property values and section bodies from the old to the new document.

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.

Since version 1.11 authors may render groups of properties with the use of one or more instances of the Document Properties Supplier Macro.

Since version 1.15 authors may include properties from attachment files with the use of one or more instances of the Document Properties Supplier Attachment Macro.

Length of Property Values

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.

Static Values

The property value should either be text or have a macro that always returns the same value.

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.

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).

Links to Attachments

In case a link to an attachment is the value of a property, please consider to use the Attachment Link Macro. It allows you to link to an existing or not yet existing attachment on the same page.

If this macro does not suit your use case, you should use the control no-render-cache to not store the rendered representation of the attachment link. This control helps to update the rendered value in case the attached document is deleted.

Related macros

Macros to define document properties.

Name	Short Description	Tags
Document Properties Supplier Attachment Macro	A table supplying additional document properties from an attached file.	Document Structure Marker Property Value Transclusion Define Properties
Document Properties Supplier From Documents Macro	Import properties from another projectdoc document.	Document Structure Marker Property Value Transclusion Define Properties
Document Properties Supplier Macro	A table containing additional document properties. Three columns: name, value and meta data (aka controls) to a property.	Document Structure Marker Property Value Transclusion Define Properties

Macros related to the Document Properties Marker Macro.

Name	Short Description	Tags
Display Document Property As Image Macro	Renders the value of a document property as an image. The property value is required to an URL that points to an image.	Display Property Value Transclusion Autocomplete
Display Document Property As Link Macro	Renders the value of a document property as a link with an alternative label.	Display Property Value Transclusion Autocomplete
Display Document Property As List Macro	Renders the list value of a document property.	Display Property Value Transclusion Autocomplete
Display Document Property Macro	Renders the value of a property of a document.	Display Property Value Transclusion Autocomplete
Display Document Property Ref Concat Macro	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.	Display Property Value Transclusion Autocomplete
Display Document Property Ref Macro	Displays a document property from a referenced document.	Display Property Value Transclusion Autocomplete
Display Document Properties Macro	Renders a template with property references.	Display Property Value Transclusion Development Deep Link Autocomplete
Display Space Attribute Macro	Renders a space attribute value.	Display Property Value Transclusion Space
Display Space Property Macro	Renders a space property value.	Display Property Value Transclusion Space
Display List Macro	Lists references to projectdoc documents in a list. List contain names and optional short descriptions.	Dynamic List Query Deep Link Remote Control Context Control Autocomplete Remote Controller
Display List Template Macro	Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.	Dynamic List Query Deep Link Remote Control Context Control Autocomplete Remote Controller
Display Table Macro	Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.	Dynamic List Query Deep Link Remote Control Context Control Autocomplete Remote Controller
Index Entries Table Macro	Renders a table of index entries.	Dynamic List Query Glossary Remote Control Deep Link Context Control Autocomplete Remote Controller
Transclude Documents Macro	Renders transcluded content fetched from documents of a result set.	Dynamic List Query Transclusion Deep Link Remote Control Context Control Autocomplete Remote Controller
Index Card Macro	Renders transcluded content fetched from documents of a result set.	Dynamic List Query Transclusion Glossary Deep Link Autocomplete

Resources

Resources related to the Projectdoc Properties Marker Macro.

projectdoc Document - projectdoc is based on projectdoc documents. Creating a projectdoc document is easy: A projectdoc document is a Confluence page using document properties and sections.
Document Properties - Properties are metadata that can be added to every projectdoc document. If you require a set of metadata for each instance of a document type, you should write your own doctype.
Document Property Controls - Lists valid controls for properties to be used in document properties tables.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java