Configuration

Configuration manual for PageSeeder

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 does not exist, a document type will inherit 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:

ElementDescription

<title>

The title of this document type

<folder>

Constraints on the document location

<filename>

Constraints on the file name

<document>

Information related to the document created

<description>

Description of the document type

  • @disable – there are situations where the creation of new documents may be delegated to another application, say reports generated from a database then uploaded to a group. While the creation of these documents may be restricted, users may 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.

AttributeDescription
context

Defines a path the document can be created, when the actual context folder does not match this value, the document type cannot be selected. The path may contain wildcards (*) and may be absolute (starting with /) within the group or relative (starting with a character). Relative context will use a matching folder anywhere in the current location. For example in group my-doc the context:

  • /intro/tutorials matches /ps/my/doc/intro/tutorials
  • intro/tutorials matches /ps/my/doc/intro/tutorials or /ps/my/doc/book1/intro/tutorials
  • /intro/* matches /ps/my/doc/intro/tutorials or /ps/my/doc/intro/examples
  • intro/* matches /ps/my/doc/book1/intro/tutorials or /ps/my/doc/book1/intro/examples
path

Defines the folder where the document will be created relative to the context or current folder. The path can be absolute (= relative to group folder) or relative to the context. It may contain dynamic elements such as auto numbers, date parts (date, year, month, day, etc.) or UI parameters.

transform

A comma separated list of transformations that need to be applied to the @path attribute.

Transform options are evaluated in order and may include:

  • charfolding – to use character folding to replace characters that have diacritical marks by the character without the mark, (e.g. 'é' -> '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.

AttributeDescription
valueDefines the name of the file for the document. May contain dynamic elements
transformA comma separated list of transformations that need to be applied to the value of the file name (see above).
editableA boolean attribute to indicate whether the filename can be edited at document creation - if @value has been specified it is always "false", otherwise "true" by default.

<document>

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

AttributeDescription
titleDefines the title for the document if different from the title entered by the user. May contain dynamic elements.
labelsLabels to assign to the document when it is created 
docidDocument ID to assign to the document at creation. May contain dynamic elements.

<description >

The description is displayed to the user when choosing a document type. It may include basic HTML elements for formatting purposes (<code>, <i>, etc.).

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).

DateMDW
1 January 20002000111
1 July 200120017127
17 December 20132013121751

 

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.
  • If no context is specified it is a group wide 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). 

NP100Q100K
1010
99010
100120
9999100
100010111
100011001011

 

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
NumberX00XXXX
11001001
1212012012
123123123123
123412341234234

Summary

SymbolDescription
YYear of current date
MMonth of current date (January is 1)
WWeek of current date
DDay of current date within the month
NGenerated autonumber
PxGenerated autonumber divided by a x
QxGenerated autonumber divided by a x + 1
KGenerated autonumber divided 1000

Examples

Example 1: default

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

<creation>
  <icon src="default.png"/>
  <filename transform="charfolding,underscore" />
  <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:

#PathDocument TitleDocID
1/tutorials/00/001-tutorial.psmlTutorial #1T00001
999/tutorials/00/999-tutorial.psmlTutorial #999T00999
1000/tutorials/01/000-tutorial.psmlTutorial #1000T01000
1001/tutorials/01/001-tutorial.psmlTutorial #1001T01001
12345/tutorials/12/345-tutorial.psmlTutorial #12345T12345
99999/tutorials/99/999-tutorial.psmlTutorial #99999T99999 
100000/tutorials/100/000-tutorial.psmlTutorial #100000T100000

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:

#DateTitlePath
12 Jan 03Hello World!/articles/2003/01/03/1-hello-world.psml
210 Sep 09Café?/articles/2009/09/10/2-cafe.psml
327 Oct 12Yes or No/articles/2012/10/27/3-yes-or-no.psml
427 Oct 12The end.../articles/2012/10/27/4-the-end.psml

Created on , last edited on