Tour for Template Authors

...

Section

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

Section

level	2
title	The Essentials

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

Code Block

language	xml
title	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.

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

Section

level	2
title	A brief Aside: The real World

Info Box

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:

Code Block

language	xml

<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:

Code Block

language	xml

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

Tip Box

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.

Section

level	2
title	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.

Code Block

language	xml

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

Example Box

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.

Section

level	2
title	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 Confuence 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:

Code Block

language	xml

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

Section

level	2
title	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.

Code Block

language	xml

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

Section

level	2
title	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.

Code Block

language	xml

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

Section

level	2
title	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:

Code Block

language	xml

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

...

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 1

New Version 2

Key

About

Keep up-to-date!

Powered by