Summary

projectdoc allows to replace placeholders at build time. Either before the blueprint wizard's form is rendered or after the author submitted the form. The replacement of placeholders is conducted at creation time of the page.

Template authors may use macros of the projectdoc Toolbox (that is Display Space Property Macro, the Display Space Attribute Macro, or the Display Document Property Macro or one of its cousins) to render space and document properties that are resolved at request time.

Replace in Wizard

Template authors may need to prefill the input fields of a wizard's form. For text fragments containing placeholders the projectdoc Toolbox provides a service to replace those placeholders with context or space property values.

The service is located at /plugins/servlet/projectdoc/toolbox/resolve. It provides the following parameters

The following context information can be accessed by specifying a placeholder in the template string and passing it to the service.

currentDate

The current date, formatted by the Confluence date formatter.

currentTime

The current time, formatted by the Confluence time formatter.

currentDateToken

The current date, formatted with yyyy-MM-dd.

currentUserId

The login name of the user creating the page.

currentUser

The full name of the user creating the page.

currentUserEmail

The email address of the user creating the page.

New report by ${currentUser} on ${currentDate}

To access space properties, simply specify the name of the property you need to be resolved.

New Release V${Version} for ${Product Name}

On success (code 200) the template's placeholders are replaced or removed, if no valid for them is found.

wizard.on('pre-render.page1Id', function(e, state) {
  var template = encodeURIComponent("New report by ${currentUser} on ${currentDate}");
  var url = AJS.contextPath()
             + "/plugins/servlet/projectdoc/toolbox/resolve?template="
             + template + "&spaceKey=" + state.wizardData.spaceKey;
  AJS.$.ajax({
    url: url,
    success: function(data, status) {
                if(status === 'success') {
                    state.soyRenderContext['name'] = data;
                }
            },
    async: false
  });
});

If a placeholder cannot be replaced, it is removed. The template author may define a scope by curly brackets. If at least one of the placeholder within such a scope is not replaced, the whole scope is not rendered.

New report{ (Version ${Version})}

Replace after Submit

To replace placeholders entered by the page author the template author may specify the fields to filter in the Soy template. The names of the fields are listed in a hidden field with the name projectdoc-replace-fields-request.

<input id="projectdoc-replace-fields-request" 
  type="hidden" 
  name="projectdoc-replace-fields-request" 
  value="projectdoc.doctype.common.name, projectdoc.doctype.common.shortDescription">

To activate the replacement process, the Context Provider is required to inherit from ProjectDocContextProvider. Please refer to add-on sources on Bitbucket for details.

Current Values in the Page

The first two examples set values to the page at creation time. It is also possible to reference space and document properties and have them replaced at request time.

Use the Display Space Property Macro, the Display Space Attribute Macro, or the Display Document Property Macro (or one of its cousins) to reference space properties, space attributes, or document properties.

<ac:structured-macro ac:name="projectdoc-space-property-display-macro">
  <ac:parameter ac:name="property-name">project-version</ac:parameter>
</ac:structured-macro>

Resources

More information for template authors.