Document config <creation>

Overview

Documentation for the <creation> element is expressed in two sections. The first details the actual structure of the element. The second explains how dynamic values can be used to determine the name and location of a new PSML document. 

If the <creation> element is not specified or the document-config.xml doesn’t exist, a document type inherits all applicable values from the default document.

Element structure

The <creation> element has the following structure:

<creation [disable="true"]>
  <title> ... </title>?
  <folder ... />?
  <filename ... />?
  <document ... />?
  <description> ... </description>?
</creation>

 All the following elements are optional:

• @disable – there are situations where the creation of new documents might be delegated to another app, for example, reports generated from a database then uploaded to a group. While the creation of these documents might be restricted, users might require the rest of PageSeeder’s functionality to behave as normal. In this situation, set the boolean value to true on the @disable attribute.

Details

<title>

The title is used by the PageSeeder UI to provide a user-friendly name of the document type which does not have the restrictions imposed on the name of the document type, by allowing any character.

It defaults to the name of the document type.

<folder>

The folder can be used to determine where the documents must be created. It can also be used to specify a path to create to store the document.

Transform options are evaluated in order and can include the following:

• charfolding – to use character folding to replace characters that have diacritical marks by the character without the mark, (for example, ‘é’ -> ‘e’).
• lowercase –  to transform all characters to lower case.
• uppercase – to transform all characters to upper case.
• underscore – to replace non-ASCII and space characters by an underscore ‘_’ .
• hyphen – to replace non-ASCII and space characters by a hyphen ‘-’ .
• trim – removes leading and trailing space, ‘_’ or ‘-’ in value.

The default transform value is charfolding,lowercase,underscore,trim.

<filename>

The <filename> element allows better control of how the name of the file where the document is stored is generated.

<document>

The <document> element can be used to override any value entered by the user so that it can include dynamic elements such as a date or auto number. These values are also passed to the document template when it is instantiated.

<description>

The description is displayed to the user when choosing a document type. It currently only supports plain text. It is recommended that every document type have a description.

Dynamic parameters

Dynamic parameters are prefixed by a dollar sign $, can be inserted in some attribute values and are wrapped in curly brackets ‘{ }’.

UI parameters

Any parameter coming from the user interface is available as $ui.[name]. The following built-in UI parameters are supported, plus any defined in the document template:

• $ui.title – the title entered by the user.
• $ui.docid – the document ID entered by the user.

Dynamic numbers

Dynamic numbers are represented as a single letter symbol. They can be inserted in some attribute values and are wrapped in curly brackets ‘{ }’. They include date parts and generated numbers and are all integers.

Dates

Date parts can be extracted using the values Y (year), M (month), D (day), W (Week).

Autonumbering

A number can be automatically computed from the context. It is found by incrementing a counter for the document type which is stored on the folder context (see above) in the current group.

• So for a different group, document type, or context, it is a different counter.

It can be referenced as N (number itself), Px (= N divided by x), Qx (= N divided by x + 1), K (= N divided by 1000 = P1000). 

Number formatting

There are three possible formats for a number:

• Symbol by itself = the value.
• Symbol preceded by zeros = the value with padded zeros with overflow.
• Repeated Symbol = the value with padded zeros with NO overflow.

Summary

Examples

Example 1: default

The PageSeeder default documents have no restrictions imposed on their location and directly inherit the values from what the user enters in the UI.

<creation>
  <filename transform="charfolding,lowercase,underscore,trim" />
  <description>Default PageSeeder document</description>
</creation>

Example 2: tutorial

Tutorial documents must be created in the tutorial folder, organized by DocID.

<creation>
  <title>Tutorial</title>
  <folder context="/tutorials" path="{0P1000}"/>
  <filename value="{NNN}-tutorial" editable="false"/>
  <document title="Tutorial #{N} {$ui.title}"
            docid="T{0000N}" />
  <description>A tutorial to include in the guide<br/>
   Tutorials are stored under the <code>/tutorials/XX</code>
   folder of the group and named automatically.
  </description>
</creation>

The files would be created as follows:

Example 3: article

Articles organized by date of creation.

<creation>
  <title>Article</title>

  <folder context="/articles" path="{YYYY}/{MM}/{DD}"/>

  <filename value="{N}-{$ui.title}"
            transform="charfolding,lowercase,hyphen,trim"/>
  <description>Articles organized by date.</description>
</creation>

The files would be created as follows: