When a page author creates a page with a blueprint wizard, the template author may want to speed up page creation by providing some useful default values for the wizard or the generated page. The default texts may rely on information from the current context (such as the current date or user creating the page) or the space the page is part of (such as the name or the version of the product).

The PDAC1 supports to replace these placeholders.

This feature is available since version 1.11 of the projectdoc Toolbox.

The API is ot considered stable until version 2.0 of the projectdoc Toolbox. Incompatible changes may be rolled out on any minor change. Usually they will be reported in the release notes.

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.

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

currentTime

currentDateToken

currentUserId

currentUser

currentUserEmail

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 = "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})}

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.

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>

More information for template authors.