Create One Document Macro

Document Properties Marker

override	false

Short Description

Renders template button to create a page. After the page is created, the macro renders a link to this page.

Doctype

macro

hide

Name

Create One Document Macro

Parent

Parent Property

property-name	Name

Audience

Name List

doctype	role
render-no-hits-as-blank	true
property	Audience

Tags

Tag List

names	Create Page, Experimental

Type

Name List

doctype	macro-type
names	Dynamic Navigation

Iteration


value	finished

hide

Since

1.4.0

Sort Key

hide

Section

index	true
show-title	false
title	Description

Renders template button to create a page. After the page is created, the macro renders a link to this page (or renders nothing - if Hide after Creation is selected).

Section

title	Properties

Section

level	2
title	Blueprint

The complete key of the blueprint to be used to create the page.

Info Box

A page blueprint key looks like this:

Code Block

language	text

de.smartics.atlassian.confluence.smartics-projectdoc-confluence:projectdoc-blueprint-doctype-blank

This example refers to the Blank Document.

The Doctypes Overview provides a list of doctype identifiers and blueprint keys.

projectdoc-box-version

since	2.0

Blueprint may be referenced by the plain doctype name.

projectdoc-section

level	2
title	Page Title

Specify the title of the new page.

Note Box
This feature is supported on Confluence 5.10 with projectdoc Toolbox 1.12.1 (or later versions).

Section

level	2
title	Hide after Creation

Check to hide the macro after the page has been created.

Section

level	2
title	Button Label

Specify the label for the button. Defaults to 'Create' if not specified.

Section

level	2
title	Space Key

Specify the key of the space the page should be created in.

Section

title	Mode

Select the rendering mode.

default	Handles button page title and page title equally.
subpage	Handles pages like Review or Retrospective to implicitly assume that the parent page's title is appended.

Version Box

since	2.0

Parameter is available since version 2.0.

Section

title	Details

Section

title	Basic Workflow

Section

title	Design the Document

The template author adds the macro to the page.

Section

Column

Define the title of the page
Decide if the button should be shown as a link or not be rendered after the document is created
Label the button

On the right you see the macro parameter options. Typically the macro is used at template design time, so the macro is added as XML (Confluence storage format).

Code Block

language	xml
title	Template Fragment (indentation changed for readability)

<ac:structured-macro ac:name="projectdoc-create-one-document-macro">
  <ac:parameter ac:name="blueprint-module-complete-key">
    de.smartics.atlassian.confluence.smartics-projectdoc-confluence
      :projectdoc-blueprint-doctype-blank
  </ac:parameter>
  <ac:parameter ac:name="title">Retrospective</ac:parameter>
  <ac:parameter ac:name="fade-on-creation">false</ac:parameter>
  <ac:parameter ac:name="button-label">Create Retrospective</ac:parameter>
</ac:structured-macro>

See whitebox example for details and source code.

Column

Section

title	Working with the Document

From the author's (or team member's) point of view, who is working with a document that contains the macro, the flow of work is as follows.

Section

Column

width	20%

Button in the view and
page does not yet exist

Column

width	60%

User hits the button
and creates the page

Column

width	20%

Button in the view
after the page is created

Hide on Creation controls if the button is rendered at all

Note Box

Note that the macro simply checks that a page with the given name exists. If the page is renamed, the button (instead of the link reappears).

Therefore it is not possible for the document author to change the title or the space. In either case the macro will conclude that the page does not exist and still render the create button.

If the blueprint is a projectdoc blueprint the wizard allows to change the name. That is the title of the page is set as provided by the template author, but the name is changed to the title provided by the document author. Macros of the projectdoc Toolbox typically work with the name of the document (e.g in the Display Table Macro the names and not the titles of the documents are listed).

Prior to Confluence 5.10 and projectdoc Toolbox 1.12.1 the wizard is not supported by the title information from the button. So the template must deal with determining the title on its own (see example below).

Section

title	Using in Templates

Template authors typically use this macro to create blueprint templates.

A typical use case employs the Wiki Link Macro and the Create One Document Macro.

Code Block

language	xml
title	Wiki Link Macro

<ac:structured-macro ac:name="projectdoc-link-wiki">
  <ac:parameter ac:name="page">@pageTitle - <at:i18n at:key="projectdoc.doctype.blackbox.whitebox"/></ac:parameter>
  <ac:parameter ac:name="empty-if-not-exists">true</ac:parameter>
</ac:structured-macro>

Code Block

language	xml
title	Create One Document Macro

<ac:structured-macro ac:name="projectdoc-create-one-document-macro">
  <ac:parameter ac:name="blueprint-module-complete-key">de.smartics.atlassian.confluence.smartics-projectdoc-confluence-arc42:projectdoc-arc42-blueprint-doctype-whitebox</ac:parameter>
  <ac:parameter ac:name="title">@parentPageTitle - <at:i18n at:key="projectdoc.doctype.blackbox.whitebox"/></ac:parameter>
  <ac:parameter ac:name="button-label"><at:i18n at:key="projectdoc.doctype.whitebox.create.label"/></ac:parameter>
  <ac:parameter ac:name="fade-on-creation">true</ac:parameter>
</ac:structured-macro>

Code Block

language	xml
title	Soy to set the Name of the Document

<div class="field-group">
  <label for="projectdoc.doctype.common.name">{getText('projectdoc.blueprint.form.label.name')}</label>
  <input id="projectdoc.doctype.common.name" class="text long-field" type="text" 
         name="projectdoc.doctype.common.name"
         placeholder="{getText('projectdoc.blueprint.form.label.name.placeholder')}" 
         value="@parentPageTitle - {getText('projectdoc.doctype.blackbox.whitebox')}">
</div>

The complete template is available as part of the add-ons for the projectdoc Toolbox on Bitbucket.

Note Box
The projectdoc Toolbox allows to use Page Wizard Placeholders. With this the template author may introduce a dynamic title based on the title of the parent page (as seen in the example above), the current date or the name of the space.

Section

index	true
title	Related macros

The following macros are often used together with or in place of the Create One Document Macro.

Tour

replace-title-with-name	true

Title	Short Description	Notes
Wiki Link Macro		A link may be rendered at another location once the document is created. This may be used to define a document property with the Document Properties Marker Macro.
Hide From Reader Macro			The button may only be visible for users with edit privileges. This macro allows to hide it for readers.
Create from Template Macro	Atlassian's Create from Template Macro displays a button on a page, linked to a specific template. When someone clicks the button, the macro opens the editor, ready to add a new page, and adds content to the page based on the given template.	The original button allows to create more than one page by launching the wizard of a given blueprint.
Page Wizard Placeholder		Use these placeholders to create dynamic titles.

...

Section

title	References

Section

title	Resources

Piwik Set Multiple Custom Variables

Name	Value
Department	projectdoc
Category	projectdoc-macro
Type	workflow

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 4

New Version Current

Key

About

Keep up-to-date!

Powered by