projectdoc Toolbox

This is a tour through the documentation for users that want to design their own set of templates or just want to create one or two templates.

A template author's job is to define templates that help the team to create documents for a given type of information. Maybe there is already a template that the template author can use and adjust. But sometimes it is required to define a new set of templates or design a template for a new kind of information that is relevant for the project.

Writing templates is one of the great supporters for teams defining their way of documenting their project. projectdoc helps to make this task much easier.

This tour shows how to accomplish the task of writing a new template with projectdoc macros.

The tour assumes that the template author adds a new template to the project. This tour will not show the details on how to edit the atlassian-plugin.xml or where to place the template and the additional JavaScript et al. files.

This tour shows how to create the XML template file and link to the projectdoc macros that help you to define this template.

Basics for the projectdoc Toolbox

 

Before creating a new doctype, make sure that none of the existing doctypes really fits.

Doctypes Introduction is a gentle introduction to the core doctypes. The Doctypes page provides an overview of all doctypes provided by extension add-ons.

Tool Support

 

Since there is nothing special with projectdoc documents besides the need for properties and sections, you can probably use any tool to create your Confluence Blueprints.

The Doctype Maven Plugin provides an alternative approach to create your doctypes based on a model.

A single Template or a Blueprint?

First the template author has to find out, where the new template should be created. There are basically two options:

  • Define a new template with the Confluence server
  • Add the new template to a project of Blueprints

It is usually the job of the documentation architect to define the process of creating a new template. So template authors may have to consult their colleague for advice on how to start.

We find it easier to define a project of Blueprints to add page and space blueprints for a specific set of projects. This way we have a project stored in our source control and release changes from time to time.

 

Refer to the documentation provided by the Confluence team to get started with Confluence Blueprints:

Also have a look at Context Provider for information on useful context provider classes provided by projectdoc.

The Template

The template is an XML file. It is part of a page blueprint as defined by Confluence. What is specific to projectdoc is the basic structure it mandates. While Confluence puts no restriction on how your template looks like, projectdoc demands that the template author lists the properties and sections that are provided by a document type.

So this is the first task to accomplish: What are the document type's properties and sections?

Common Properties

projectdoc provides a couple of standard properties and standard sections that are useful for any document type. So we strongly recommend that you add them.

The Essentials

Basically the following properties are required for every document to work with projectdoc:

Document Type Essentials
<ac:structured-macro ac:name="projectdoc-properties-marker">
  <ac:rich-text-body>
    <div class="table-wrap">
      <table>
        <tbody>
          <tr>
            <th>Short Description</th>
            <td>
              <ac:placeholder>Add short description in about 1 to 3 sentences.</ac:placeholder>
            </td>
            <td> </td>
          </tr>
          <tr>
            <th>Doctype</th>
            <td>my-doctype</td>
            <td>hide</td>
          </tr>
          <tr>
            <th>Name</th>
            <td>
              <ac:placeholder>The unique name of the document within the doctype.</ac:placeholder>
            </td>
            <td> </td>
          </tr>
        </tbody>
      </table>
    </div>
  </ac:rich-text-body>
</ac:structured-macro>

The example shows the basic structure of a document. The projectdoc-properties-marker identifier refers to the Display Document Properties Macro. It defines all the properties that are relevant for the doctype. In the example there are only three properties

and no sections.

Note that the table shows three columns:

  • Name of the property
  • Value of the property
  • Controls

You may add the control hide to suppress the rendering of the column in the view mode. For an overview over valid controls, please refer to Document Property Controls.

 

You may use the properties in Lucene searches. For details, please refer to Search Tips.

A brief Aside: The real World

 

In a real template a page wizard will query for the name, short description, and probably for some other information. In this case the ac:placeholder element will be replaced with a at:var element.

In addition to that you may also want to internationalize your template. That is allow to create document instances for different locales. The resulting document will therefore more likely look like this:

<ac:structured-macro ac:name="projectdoc-properties-marker">
  <ac:rich-text-body>
    <div class="table-wrap">
      <table class="confluenceTable">
        <tbody>
          <tr>
            <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.shortDescription"/></th>
            <td class="confluenceTd"><at:var at:name="projectdoc.doctype.common.shortDescription"/></td>
            <td class="confluenceTd"></td>
          </tr>
          <tr>
            <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.doctype"/></th>
            <td class="confluenceTd">my-doctype</td>
            <td class="confluenceTd">hide</td>
          </tr>
          <tr>
            <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.name"/></th>
            <td class="confluenceTd"><at:var at:name="projectdoc.doctype.common.name"/></td>
            <td class="confluenceTd"></td>
          </tr>
        </tbody>
      </table>
    </div>
  </ac:rich-text-body>
</ac:structured-macro>

For the sake of simplicity for this introduction, we will stick to a mono-lingual version (English) and not bother with wizard data.

It also makes sense to add some additional formatting and to embed the properties table and the section into layout elements like this:

<ac:layout>
  <ac:layout-section ac:type="single">
    <ac:layout-cell>
      <ac:structured-macro ac:name="projectdoc-properties-marker">
        <!-- ... as seen above -->
      </ac:structured-macro>
      
      <!-- ... add the sections here (we will see this later) -->
    </ac:layout-cell>
  </ac:layout-section>
</ac:layout>

This way you get a valid XML element and may also add additional layout-cell elements to give your template more visual appealing structure.

 

Create your template as a page in your Confluence instance. This way you can use the features of the visual editor to create your tables, sections and other page elements.

Use the Confluence Source Editor to copy the XML in Confluence Storage Format and then add additional elements (like the at:var or ac:placeholder elements) to it.

For the reminder of this tour we will stick to the simple structure we started with above, but you now know the difference between our playground and the real stuff. (smile)

The usual Suspects

It is important to know the audience for a given document. Especially if the document type is quite general.

Therefore we add the following element to allow users to select the audience.

<tr>
  <th>Audience</th>
  <td><ac:structured-macro ac:name="projectdoc-name-list">
      <ac:parameter ac:name="doctype">role</ac:parameter>
      <ac:parameter ac:name="property">Audience</ac:parameter>
    </ac:structured-macro></td>
  <td></td>
</tr>

The Name List Macro will contain the name of a document of the specified doctype. If that document exists, the Name List Macro will render a reference to that document.

 

Say the audience are team members of the role Developer. Then you define a document of type role, with the name Developer (the title may be different to the space unique page title constraint - refer to Name and Title for details). Add the name Developer to the Name List Macro to create a link to the document.

Please note that changing the name of a document will not change the content of the macro as Confluence users are used to if they change the title of a page. The value stored in the macro is simple a "check-to-reference" approach.

By the way: The property parameter links to the name of the document property. This is relevant for some queries. Therefore it is good practice to specify these as a template author. Readers and document authors will usually do not bother with these values.

Tagging and Categorizing

To make it easier for readers and document authors to locate a document, document authors will add tags and categories to them. Both options are based on documents that define their meaning. This is often quite helpful since different authors may interpret a tag different (you may have already experienced that with Confluence labels).

Tags and categories are referenced with the Name List Macro, as you have seen before referencing the audience by its role. The XML snippet in your template looks like this:

<tr>
  <th>Tags</th>
  <td><ac:structured-macro ac:name="projectdoc-name-list">
      <ac:parameter ac:name="doctype">tag</ac:parameter>
      <ac:parameter ac:name="property">Tags</ac:parameter>
    </ac:structured-macro></td>
  <td></td>
</tr>
<tr>
  <th>Categories</th>
  <td><ac:structured-macro ac:name="projectdoc-name-list">
      <ac:parameter ac:name="doctype">category</ac:parameter>
      <ac:parameter ac:name="property">Categories</ac:parameter>
    </ac:structured-macro></td>
  <td></td>
</tr>

For more information on categorizing options with document properties:

Template authors and document authors may add additional properties to help categorizing documents. Examples are the type for a resource of topic or the domain of a term. Tags and categories have to define values that are meaningful for all doctypes, while doctype specific categorization properties only have to make sense in the context of their doctype. This is important for queries that fetch documents of different types.

Control the default Sort Order

Template authors and document authors will use the Display Table Macro and Display List Macro to automatically collect navigation links to other documents. Usually these authors will define their sort order by a macro parameter. But if no sort order is define with the query, the default sort order defined by the doctype will be enforced. To allow document authors to control this sort order, template authors should provide the Sort Key property.

<tr>
  <th>Sort Key</th>
  <td><ac:placeholder>Add a character sequence to support sorting documents.</ac:placeholder></td>
  <td>hide</td>
</tr>

Note that we added the hide control to not display this row in view mode of the page.

If no value is specified for the Sort Key property, the default sort order is specified by the lexicographical order of the document name.

The State of the Document

As a collaboration tool, the Iteration Macro allows to define the state of a document. Since documentation in a project is always worked on, the Iteration property makes it easy to see, in which state the document is in. This will set the expectation of the reader to the correct level and allow document authors to query for documents that are about to be finalized.

<tr>
  <th>Iteration</th>
  <td><ac:structured-macro ac:name="projectdoc-iteration">
      <ac:parameter ac:name="value">facade</ac:parameter>
    </ac:structured-macro>
  </td>
  <td></td>
</tr>

Categorized by the Parent

A parent of document is usually a  document of the same type. The property makes it easy to select all documents with a given parent by its document name.

To provide the Parent property, add the following snippet:

<tr>
  <th>Parent</th>
  <td>
    <ac:structured-macro ac:name="projectdoc-transclusion-parent-property">
      <ac:parameter ac:name="property-name">Name</ac:parameter>
    </ac:structured-macro>
  </td>
  <td></td>
</tr>

Which Properties to Choose?

If you question yourself, which of the standard properties you should choose: Use them all. Especially if other document types of your documentation already use them.

The essentials are required. No document instance must go without them. The others get more strength, if they are used by all document types.

Common Sections

 The following sections make sense in most documents.

Description

While the Short Description property is limited to the essentials with one to three sentences, the description may help readers in more detail what they can expect from the document.

<ac:structured-macro ac:name="projectdoc-section">
 <ac:parameter ac:name="title">Description</ac:parameter>
 <ac:rich-text-body>
   <ac:placeholder>
     Describe the content of this document so that readers are 
     able to decide whether to read further or not.
   </ac:placeholder>
 </ac:rich-text-body>
</ac:structured-macro>

Children

To enhance navigation for your readers, add references to your document. The Children section lists all documents that are children to this document. If you use the Display Table Macro, any documents you add as subdocuments, will be automatically listed.

<ac:structured-macro ac:name="projectdoc-section">
  <ac:parameter ac:name="title">Children</ac:parameter>
  <ac:rich-text-body>
    <ac:structured-macro ac:name="projectdoc-display-table">
      <ac:parameter ac:name="doctype">my-doctype</ac:parameter>
      <ac:parameter ac:name="select">Name, Short Description</ac:parameter>
      <ac:parameter ac:name="sort-by">Sort Key, Name</ac:parameter>
      <ac:parameter ac:name="render-no-hits-as-blank">true</ac:parameter>
      <ac:parameter ac:name="restrict-to-immediate-children">true</ac:parameter>
    </ac:structured-macro>
  </ac:rich-text-body>
</ac:structured-macro>

The render-no-hits-as-blank parameter helps to suppress the rendering of the section, if no children have been added.

 

Other than the Confluence Children Display Macros, the table macro will automatically list the short descriptions and may add further properties as additional columns.

But if you are used to the Children Display Macro, you may miss some features in the Display Table Macro. Especially the depth of children showing up.

If you want it really easy for document authors to add new children, add the Confluence Create From Template Macro to this section.

Notes

The Notes section is a tool for document authors to keep some information in the document that is useful for authors but should not be shown to readers.

<ac:structured-macro ac:name="projectdoc-section">
 <ac:parameter ac:name="title">Notes</ac:parameter>
 <ac:parameter ac:name="required-permissions">write-access</ac:parameter>
 <ac:rich-text-body>
   <ac:placeholder>
     Add project-private notes to the document. 
     This information is not intended to be 
     exported to other parties and is usually 
     only read-able by users with write access. 
     The information is NOT secured. The section 
     is for convenience of the reader. Do NOT 
     add any confidential information to this section!
   </ac:placeholder>
 </ac:rich-text-body>
</ac:structured-macro>

References

The References section lists resources that support the information provided by the document.

<ac:structured-macro ac:name="projectdoc-section">
 <ac:parameter ac:name="title">References</ac:parameter>
 <ac:rich-text-body>
   <ac:placeholder>
     List sources that back the information in the 
     document. This are references to the original 
     source of the information. May reference a 
     domain expert or/and some other documents. 
     Add hyperlinks, if possible.
   </ac:placeholder>
 </ac:rich-text-body>
</ac:structured-macro>

Usually this is a hand-crafted list. But you may add the Tour Macro to help to reference resources within the wiki and outside more easily.

Resources

The Resources section links to further information in other resources.

<ac:structured-macro ac:name="projectdoc-section">
 <ac:parameter ac:name="title">Resources</ac:parameter>
 <ac:rich-text-body>
   <ac:placeholder>
     Reference other resources that relate to this 
     document. May include further readings or 
     alternative information.
   </ac:placeholder>
 </ac:rich-text-body>
</ac:structured-macro>

Usually this is a hand-crafted list. But you may add the Tour Macro to help to reference resources within the wiki and outside more easily.

Which Sections to Choose?

Sections are not so relevant as properties to align over document types. While it provides some convenience if readers find descriptions as the first section and references and resources as the last sections, it may dependent on the type of project and the team, which common sections are useful.

We recommend to use all the sections we introduced.

Base Template

If you add all the recommended properties and sections, the final template to start with looks like this:

<ac:structured-macro ac:name="projectdoc-properties-marker">
  <ac:rich-text-body>
    <table>
      <tbody>
        <tr>
          <th>Short Description</th>
          <td>
            <ac:placeholder>
              Add short description in about 1 to 3 sentences.
            </ac:placeholder>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Doctype</th>
          <td>my-doctype</td>
          <td>hide</td>
        </tr>
        <tr>
          <th>Name</th>
          <td>
            <ac:placeholder>
              The unique name of the document within the doctype.
            </ac:placeholder>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Parent</th>
          <td>
            <ac:structured-macro ac:name="projectdoc-transclusion-parent-property">
              <ac:parameter ac:name="property-name">Name</ac:parameter>
            </ac:structured-macro>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Audience</th>
          <td>
            <ac:structured-macro ac:name="projectdoc-name-list">
              <ac:parameter ac:name="property">Audience</ac:parameter>
              <ac:parameter ac:name="doctype">role</ac:parameter>
            </ac:structured-macro>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Categories</th>
          <td>
            <ac:structured-macro ac:name="projectdoc-name-list">
              <ac:parameter ac:name="property">Categories</ac:parameter>
              <ac:parameter ac:name="doctype">category</ac:parameter>
            </ac:structured-macro>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Tags</th>
          <td>
            <ac:structured-macro ac:name="projectdoc-tag-list-macro">
              <ac:parameter ac:name="property">Tags</ac:parameter>
            </ac:structured-macro>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Iteration</th>
          <td>
            <ac:structured-macro ac:name="projectdoc-iteration">
              <ac:parameter ac:name="value">facade</ac:parameter>
            </ac:structured-macro>
          </td>
          <td> </td>
        </tr>
        <tr>
          <th>Sort Key</th>
          <td>
            <ac:placeholder>
              Add a character sequence to support sorting documents.
            </ac:placeholder>
          </td>
          <td>hide</td>
        </tr>
      </tbody>
    </table>
  </ac:rich-text-body>
</ac:structured-macro>
 
<ac:structured-macro ac:name="projectdoc-section">
  <ac:parameter ac:name="title">Description</ac:parameter>
  <ac:rich-text-body>
    <ac:placeholder>
      Describe the content of this document so that readers 
      are able to decide whether to read further or not.
    </ac:placeholder>
  </ac:rich-text-body>
</ac:structured-macro>
<ac:structured-macro ac:name="projectdoc-section">
  <ac:parameter ac:name="title">Notes</ac:parameter>
  <ac:parameter ac:name="required-permissions">write-access</ac:parameter>
  <ac:rich-text-body>
    <ac:placeholder>
      Add project-private notes to the document. This information is not 
      intended to be exported to other parties and is usually only 
      read-able by users with write access. The information is NOT secured. 
      The section is for convenience of the reader. Do NOT add any 
      confidential information to this section!
    </ac:placeholder>
  </ac:rich-text-body>
</ac:structured-macro>
<ac:structured-macro ac:name="projectdoc-section">
  <ac:parameter ac:name="title">References</ac:parameter>
  <ac:rich-text-body>
    <ac:placeholder>
      List sources that back the information in the document. This are 
      references to the original source of the information. May reference 
      a domain expert or/and some other documents. Add hyperlinks, if 
      possible.
    </ac:placeholder>
  </ac:rich-text-body>
</ac:structured-macro>
<ac:structured-macro ac:name="projectdoc-section">
  <ac:parameter ac:name="title">Resources</ac:parameter>
  <ac:rich-text-body>
    <ac:placeholder>
      Reference other resources that relate to this document. 
      May include further readings or alternative information.
    </ac:placeholder>
  </ac:rich-text-body>
</ac:structured-macro>

With internationalization and formatting, it will be like this:

 <ac:layout>
  <ac:layout-section ac:type="single">
    <ac:layout-cell>
      <ac:structured-macro ac:name="projectdoc-properties-marker">
        <ac:rich-text-body>
          <div class="table-wrap">
            <table class="confluenceTable">
              <tbody>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.shortDescription"/></th>
                  <td class="confluenceTd"><at:var at:name="projectdoc.doctype.common.shortDescription"/></td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.doctype"/></th>
                  <td class="confluenceTd">my-doctype</td>
                  <td class="confluenceTd">hide</td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.name"/></th>
                  <td class="confluenceTd"><at:var at:name="projectdoc.doctype.common.name"/></td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.parent"/></th>
                  <td class="confluenceTd">
                    <ac:structured-macro ac:name="projectdoc-transclusion-parent-property">
                      <ac:parameter ac:name="property-name"><at:i18n at:key="projectdoc.doctype.common.name"/></ac:parameter>
                    </ac:structured-macro>
                  </td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.audience"/></th>
                  <td class="confluenceTd"><ac:structured-macro ac:name="projectdoc-name-list">
                      <ac:parameter ac:name="doctype">role</ac:parameter>
                      <ac:parameter ac:name="property"><at:i18n at:key="projectdoc.doctype.common.audience"/></ac:parameter>
                    </ac:structured-macro></td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.categories"/></th>
                  <td class="confluenceTd"><ac:structured-macro ac:name="projectdoc-name-list">
                      <ac:parameter ac:name="doctype">category</ac:parameter>
                      <ac:parameter ac:name="property"><at:i18n at:key="projectdoc.doctype.common.categories"/></ac:parameter>
                    </ac:structured-macro></td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.tags"/></th>
                  <td class="confluenceTd"><ac:structured-macro ac:name="projectdoc-tag-list-macro">
                      <ac:parameter ac:name="property"><at:i18n at:key="projectdoc.doctype.common.tags"/></ac:parameter>
                    </ac:structured-macro></td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.iteration"/></th>
                  <td class="confluenceTd"><ac:structured-macro ac:name="projectdoc-iteration">
                      <ac:parameter ac:name="value">facade</ac:parameter>
                    </ac:structured-macro>
                  </td>
                  <td class="confluenceTd"></td>
                </tr>
                <tr>
                  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.sortKey"/></th>
                  <td class="confluenceTd"><ac:placeholder><at:i18n at:key="projectdoc.doctype.common.sortKey.placeholder"/></ac:placeholder></td>
                  <td class="confluenceTd">hide</td>
                </tr>
              </tbody>
            </table>
          </div>
        </ac:rich-text-body>
      </ac:structured-macro>

      <ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.common.description"/></ac:parameter>
        <ac:rich-text-body>
          <ac:placeholder><at:i18n at:key="projectdoc.doctype.common.description.placeholder"/></ac:placeholder>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.topic.children"/></ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:name="projectdoc-display-table">
            <ac:parameter ac:name="doctype">my-doctype</ac:parameter>
            <ac:parameter ac:name="select"><at:i18n at:key="projectdoc.doctype.common.name"/>, <at:i18n at:key="projectdoc.doctype.common.shortDescription"/></ac:parameter>
            <ac:parameter ac:name="sort-by"><at:i18n at:key="projectdoc.doctype.common.sortKey"/>, <at:i18n at:key="projectdoc.doctype.common.name"/></ac:parameter>
            <ac:parameter ac:name="render-no-hits-as-blank">true</ac:parameter>
            <ac:parameter ac:name="restrict-to-immediate-children">true</ac:parameter>
          </ac:structured-macro>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.common.notes"/></ac:parameter>
        <ac:parameter ac:name="required-permissions">write-access</ac:parameter>
        <ac:rich-text-body>
          <ac:placeholder><at:i18n at:key="projectdoc.doctype.common.notes.placeholder"/></ac:placeholder>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.common.references"/></ac:parameter>
        <ac:rich-text-body>
          <ac:placeholder><at:i18n at:key="projectdoc.doctype.common.references.placeholder"/></ac:placeholder>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.common.resources"/></ac:parameter>
        <ac:rich-text-body>
          <ac:placeholder><at:i18n at:key="projectdoc.doctype.common.resources.placeholder"/></ac:placeholder>
        </ac:rich-text-body>
      </ac:structured-macro>
    </ac:layout-cell>
  </ac:layout-section>
</ac:layout>

Selecting specific Properties and Sections

Selecting the properties and section is the main task for template authors.

Properties

Check which metadata is important for the document and add this as a document property to the properties table at the start of the document. Remember that document properties are used to select documents in queries.

Often there is a natural type property, such as a resource or media type. If this is the case, also design a type document type that is easily extensible for project teams.

Sections

Define the information that is relevant for the document type. The arrange the sections in a suitable sequence. Usually start after the Description section and keep the Notes, References and Resources as the last three sections. The Children section is usually expected after the doctype specific sections.

You may provided subsections within your sections to further structure your document type.

Navigation

Last consider which other document instances you want to link to. These instance may be of the same or different type as the document under design. For linking prefer using automatic lists (e.g. Display Table Macro).

projectdoc Macros for Template Authors

We have already seen many of the most relevant projectdoc macros for template authors.

Here is the complete list:

Name Short Description Categories
Render the property value of an ancestor of this document, for the first ancestor that matches the specified document type.
Renders document history information.
Renders a template with property references.
Renders the value of a document property as an image. The property value is required to an URL that points to an image.
Renders the value of a document property as a link with an alternative label.
Renders the list value of a document property.
Renders the value of a property of a 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.
Displays a document property from a referenced document.
Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
Renders a space attribute value.
Renders a space property value.
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
A table supplying additional document properties from an attached file.
Import properties from another projectdoc document.
A table containing additional document properties. Three columns: name, value and meta data (aka controls) to a property.
Renders a locale dependent link to an external resource. The body of the macro contains the link label.
Generic boxes help to easily define one's own boxes to apply certain CSS styles to them.
Hides a text fragment from an anonymous user.
Hides a page fragment from a user with read-only permissions.
Hides a text fragment from a user that has no edit permissions.
Renders transcluded content fetched from documents of a result set.
Renders a table of index entries.
Selects an iteration phase from a fixed set of stages.
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name hat is added to the body.
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name.
Renders the property of the parent document, if it has the same doctype.
Renders a name list while taking care of special role semantics. Confluence names of groups with view permissions are added to the list of values.
Lists macros that allow to select from a fixed set of values. These macros are used to define the range of document property values. So they are a tool for template authors.
Renders spaces with their attributes in a table or list.
Lists references to projectdoc documents. The rendering will add a link to a document, if there is a document with the given name hat is added to the body.
Renders a name list while taking care of special tag semantics. Confluence labels are added virtually to this list and displayed in the tags table row of the document properties table.
Renders a predefined list of documents in a table . Documents are selected by a document property. Allows to select document properties for columns. Also non-list representations are provided.
Renders a predefined list of documents in a table.
Renders transcluded content fetched from documents of a result set.