projectdoc Toolbox

The standard context provider or templates to create subpages. The context provider basically deals with the title uniqueness (by adding the parent document's name as part of the page title) and sort order (first documents first).

Class
de.smartics.projectdoc.atlassian.confluence.blueprint.provider.ProjectDocSubdocumentContextProvider
Audience
Since
1.11
 

Prior to version 1.11 the name of the class has been de.smartics.projectdoc.atlassian.confluence.ProjectDocSubdocumentContextProvider.

Contents

Description

The main purpose of the context providers is to create subdocuments to a given document. It tackles the problem of page title unique within a space. The title is expanded by the name of the parent page, which in most contexts makes it unique.

 

For instance if you want to add an event to your developer journal with the name "Continuous Delivery" there may already be a page with this title in your page. Or you want to create a subpage with the name "Introduction", you may have applied this convention to other pages and the the title may collide.

By adding the parent page's title, the subpage's title will be unique:

  • Continuous Delivery - Jane Doe's events on 4th of May 2015
  • Introduction - Agile Testing Concept

Due to the Display Table Macro the title of the pages is less important than usual in you Confluence wiki. Within pages you can work with the name of the document, which is still "Continuous Delivery" or "Introduction".

The context provider also creates a sort key to help adding new pages at the end of the stack. The first page will have a sort key of 000100. Each additional page will increment by 10, allowing to insert additional pages later to the sort order. This is very convenient if you are adding excerpts to a resource document. If you create excerpts chapter by chapter, the natural sort order will be "Append at the end".

Use the context key projectdoc.doctype.common.sortKey to reference the generated sort key.

<tr>
  <th class="confluenceTh"><at:i18n at:key="projectdoc.doctype.common.sortKey"/></th>
  <td class="confluenceTd"><at:var at:name="projectdoc.doctype.common.sortKey"/></td>
  <td class="confluenceTd">hide</td>
</tr>

Provided Context Parameters

Page Title and Document Name Handling

If the targetLocation or  adjustTitleAfterMoveRequest is not set by the wizard (soy template), the placeholder @parentPageTitle be replaced with the parent page's name. The sort key property will also be set to the next higher number according to the current siblings of the new page, if at least one placeholder is used.

Otherwise the title of the page is set to the name of the document.

Add Space Information to Blueprint Context

The space key is accessible by the key spaceKey from the blueprint context.

Since it is sometimes convenient to render a complete XML tag, this XML fragment is also generated and stored by the key spaceKeyElement:

<ri:space ri:space-key="spaceKey" /> 

Here is an example on how to use the XML element with the Create from Template Macro:

<structured-macro name="create-from-template">
  <parameter name="blueprintModuleCompleteKey">someKey</parameter>
  <parameter name="buttonLabel">Some Label</parameter>
  <parameter name="spaceKey"><at:var at:name="spaceKeyElement" at:rawxhtml="true"/></parameter>
</structured-macro>

This example shows how the spaceKeyElement property is used to render the complete element.

Add Creation Metadata to Blueprint Context

The following properties are added to the blueprint context.

ParameterDescription
projectdoc.doctype.common.creationDateThe date of the creation formatted by the user's preferences.
projectdoc.doctype.common.creationTimeThe time of the creation formatted by the user's preferences.
de.smartics.projectdoc.creationDateInstanceThe date instance for access by the Java API.

Translate Placeholders in Short Description

The following placeholders are translated:

PlaceholderDescription
@parentPageTitleInserts the title of the parent page.
@pageTitle

Inserts the title of the current page. This is useful for template authors for use cases where a macro references a page by its title.

It cannot be used with the wizard, because the page has no title.

@spaceKeyInserts the key of the current space.
@spaceNameInserts the name of the current space.
@currentDateInserts the current date, formatted by the global formatter configuration.
@currentDateTokenInserts the current date formatted by yyyy-MM-dd (year, month, day).

If you add the placeholder @parentPageTitle by yourself, you can control the position of the parent page title within the subpage title.

Example Usage

The context provider is used for regular templates of your blueprint. It helps to map the wizard's input information to the page.

The following fragment registers your template as a Content Template Module:

<content-template
    key="my-template-key-template"
    i18n-name-key="projectdoc.my-template-key.template.title">
   <resource
       name="template"
       type="download"
      location="/my/path/to/my-template-key-template.xml" />
  <context-provider class="de.smartics.projectdoc.atlassian.confluence.ProjectDocSubdocumentContextProvider" />
</content-template>

The my-template-key is usually the name of the template (e.g. retrospective or user-character).