Learn about the central most heavily used macros of your projectdoc Toolbox.

Background Information

 Show background information ...

The central macros of the projectdoc Toolbox are:

Document Properties Marker Macro
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
Section Macro
Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
Display Table Macro
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.

Document Properties Marker Macro

The Document Properties Marker Macro contains a three columned table with the document properties. Authors will rarely add this macro to a page since this is the job of the template author.

Nevertheless the author uses the macro by editing existing properties or adding new properties to it.

The three columns contain the

  1. name,
  2. the value,
  3. and controls

of the property. Every property is on its own line.

The most used property control is probably the hide control. It prevents the property from being rendered in the table. You may even opt to hide the whole table with the Hide parameter of the macro.

Section Macro

The Section Macro renders a section with a title and its content. The content is added to the macro's body.

If the content is empty, the section will not be rendered. This macro is an essential element for template authors. The structure of a template for a document type can be defined so that document authors have guidance which information to place where. But as long as no content is provided by the document author, the reader of the document is not distracted by empty sections.

Display Table Macro

With the Display Table Macro document authors display result sets of document queries.This allows to add references to documents on the the wiki that automatically expands when new documents are added that match the given search criteria.

The macro allows to select properties and section from the documents. The search result is filtered by a where clause in Lucene syntax. The macro also allows to sort the result set by properties.

Accessing a single Property

 

If you only need to access a single property value within text, have a look at the Display Document Property Macro.

Since 2.5

 

Wiki Markup is supported since version 2.5.

Transclusion Macro

The Transclusion Macro includes content from another page at render time. Transclusion supports single sourcing.

The content to be transcluded has to be marked as a section (Section Macro) or region content (Content Marker Macro).

 

Transclusion only works with plain Confluence pages since version 1.11 of the projectdoc Toolbox.

Before that version only transclusion from projectdoc documents was defined. Creating a projectdoc document is simple: add the Document Properties Marker Macro. No special properties required.

The body provides space for replacements of the form "placeholder=replacement", each on its own line. Specify a placeholder like this ${placeholderName}.

Hands-on Steps

Use the Document Properties Marker Macro

  1. Open the person document from a previous step for editing
  2. Go to the Team property you have added; in the last column type 'hide'
  3. Save the document

The line with the Team property is no longer shown.

Use the Section Macro

  1. Open the person document from a previous step
  2. Add a new Section after the Description section called 'Questions'
  3. Add a section within this section and name it 'Question One'
  4. Add some lines to the body of the Section Macro
  5. Add a second section 'Question Two' as a sibling to the section named 'Question One'
  6. Do not add text to the body
  7. Save the document

    The section named question and the sibling that contains text is shown.
  8. Open the person document again
  9. Remove the text from the section named 'Question One'
  10. Save the document

The question section with its two children contains no text and is therefore not rendered.

Use the Display Table Macro

  1. To run some tests we add a second person document to the index space
  2. Click 'Create'
  3. Put John to his sister's team
  4. Create a document of type 'Topic' in the 'My Workspace' space
  5. Send it to its homepage
  6. Add a new section called 'Members of the Team'
  7. Add a Display Table Macro to its body
  8. Select on doctype 'role' and display three columns: Name, Short Description, Team
  9. Save the macro
  10. Save the page

The page renders as follows:

  1. Click on 'John Doe', edit the page and change the team name to 'True Testers'
  2. Check the table on the 'My Team' page
  3. Edit the 'My Team' page
  4. Add a where clause to the Display Table Macro to select only on the 'JS Smurfs' team
  5. Save the macro
  6. Save the page

The result table contains only one hit.

For more information on search options,visit Search Tips.

Use the Transclusion Macro

  1. Go to the homepage of 'My Workspace'
  2. Edit the page
  3. Add the Transclusion Macro to transclude the section 'Members of the Team'
  4. Save the macro
  5. Save the page
  6. Put John to the 'JS Smurfs' team

     

    If you lost track of John, find the Person homepage: Go to the index space or your workspace homepage and click the link "Persons".

  7. Go to the homepage of 'My Workspace'
 

Note that the transclusions are not cached. If they were cached, the result my show a stale fragment. This is due to the fact that dynamic content does not match well with caching. Therefore you should either do not transclude dynamic content or you may select the transclusion to not be cached.

  1. Go to the homepage of 'My Workspace'
  2. Edit the page
  3. Add a section with title 'Test'
  4. Move the transclusion macro to the body of this new section
  5. Edit the transclusion macro
  6. Change the target level to '*'
  7. Save the macro
  8. Save the page

Note that the level of the transcluded section is automatically set to '2'. The section is originally at level '1'. We set the target level to '*' to request projectdoc to calculate the level of the transcluded section automatically to match that of the enclosing section plus one. Note that this feature only works with sections and not with pure headings.

Next Step

Continue with the next step: Categorization

Content


Next Step CategorizationPrevious Step Doctypes in Detail