Tutorials

Task-driven tutorials and recipes for PageSeeder

How to create a new document template

Document templates allow developers to pre-populate documents with fixed and variable content and structure.

Objective

PageSeeder documents are highly customizable. This tutorial will show how to setup a document type that follows a specific structure.

Overview

There is either zero or one document-template.psml file per document type and each one is composed of two possible components.

  • mandatory PSML content and variables contained in mutable and immutable document structures. This content is expressed inside a <section> element in the document-template.
  • potentially optional field and fragment variables that require user input are declared in the template namespace (http://pageseeder.com/psml/template usually expressed with t:) and expressed before the <section> element.

The following four t: elements are resolved when either the document or the fragment is created. 

  • <t:param> – used to declare and label a parameter plus optional characteristics.  
  • <t:value> – injects the parameter value into the document content as the value of an attribute or element.
  • <t:fragment> – declares an optional PSML <fragment> that can invoked by the user at any time. 
  • <t:fragment-ref> – refers to the <fragment> by @type, it is only valid inside a <section> element.

Outside the document-template, no further integration code is is required to process the combination of mandatory and optional, static and dynamic data components. Simply by declaring the objects correctly, they will be available in PageSeeder for all core stages of the document lifecycle; editing, search, publishing.

However, the other technologies accessible as part of the document type can improve productivity through custom editors or document display and data quality by consistent document names and locations or data validation

Simple Example

Following is a simple document-template created by using the Document config page located under the Dev tab in the Developer perspective.

 

 

 

After saving the document-template file, the document type will be available through the New Document menu. From the example code above, the following interface will be generated:

 

 

 

In turn, submitting the data above will generate the following document:

 

 

 

Looking at the fragment through the code editing interface, it is possible to see the PSML that has been resolved out of the template. Note that this code editing interface can be an efficient alternative to manually creating the boilerplate markup needed to populate the document-template. psml file. To ensure the PSML is valid, create and save the content using the normal editing interface. Then re-open the fragment in the code editor and cut / paste the PSML into the document-template. 

 

 

Note

This example allows for multiple event fragments to be added to a trial document. If only one fragment per document was required, the <t:fragment> wrapper and  <t:fragment-ref> would not have been needed. Instead the document-template would have had the <fragment> element inside the <section> element.

Document-template elements

Document types do not require a document-template. If document-template.psml is not found in:

/WEB-INF/template/[project]/psml/[documenttype]/

any new document for that type will be generated using the settings of the default template.

/WEB-INF/template/default/psml/default/document-template.psml

<t:param>

The <t:param> element allows the document to be populated with values generated at the time the document is created. 

If <t:param> is a child of <document> it will appear on the New Document page. If <t:param> is inside a <t:fragment> element it will appear on the Add Fragment dialog. It can have the following attributes:

AttributeDescription
nameThe parameter name (required)
titleThe title displayed in the user interface (optional).
If not specified then the parameter will NOT be displayed in the user interface.
defaultThe default value (optional)
type

The data type - text|integer|date|xml - default is text (optional).
If the value does not match the data type then the default is used.

When creating new documents PageSeeder will also create the following parameters:

NameDescription
ps.titleThe title from the user interface or as specified by the <creation> options
ps.filenameThe filename of the document
ps.descriptionThe the description entered in the user interface
ps.authorThe first name and surname of the user creating the document
ps.docidThe document ID from the user interface or as specified by the <creation> options
ps.groupThe current group for the document
ps.pathThe path of the document
ps.currentdateThe current date in ISO8601 format
ps.currentdatetimeThe current datetime in ISO8601 format including timezone information
ps.currenttimeThe current time in ISO8601 format including timezone information

<t:value>

 The <t:value> element can be used to insert parameter values into the content and can appear inside any element with text content. It has the following attributes.

AttributeDescription
nameThe parameter name

Inside attributes the value can be inserted using the format {$[name]}.

<t:fragment>

The <t:fragment> element can be used to define fragment types which can be added by users editing the document. Any defined fragment type can be added inside any <section> in the document unless the section has a @fragmenttype attribute which restricts it to one fragment type. It should appear before any <section> elements and have the following attributes:

AttributeDescription
typeThe fragment type
titleThe title displayed in the user interface

It must contain one of the fragment elements: <fragment>, <properties-fragment>, <xref-fragment>, <media-fragment>.

<t:fragment-ref>

The <t:fragment-ref> element can be used to insert fragment types. It must appear inside <section> and have the following attributes:

AttributeDescription
idThe fragment id
typeThe fragment type

 

For further information, see fragment examples or custom documents.

Example

Below is an example:

<?xml version="1.0"?>
<document xmlns:t="http://pageseeder.com/psml/template"
                                            level="portable">  

  <t:param name="difficulty" title="Difficulty" type="integer" />

   <t:fragment type="outcome">
     <fragment>
        <heading level="3">Outcome</heading>
        <para>Type description here</para>
     </fragment>
   </t:fragment>

   <t:fragment type="question">
     <fragment>
        <t:param name="question-id" title="Question ID" />
        <t:param name="question-content" title="Content"
                            default="Type content here"/>
            <para>Question ID:
               <inline label="question-id">
                  <t:value name="question-id"/>
               </inline>
            </para>
            <block label="richtext">Content:
                <block label="question-content">
                  <t:value name="question-content"/>
                </block>
           </block>
     </fragment>
  </t:fragment>

 <section id="title">
     <fragment id="1">
        <heading level="1"><t:value name="ps.title"/>
          </heading>
     </fragment>
  </section>

  <section id="metadata">
    <properties-fragment id="2">
      <property name="author"   value="{$ps.author}"/>
      <property name="created"  value="{$ps.currentdate}"
                                            datatype="date"/>
      <property name="difficulty" value="{$difficulty}"/>
      <property name="topics"   count="n"/>
    </properties-fragment>  
  </section>

  <section id="outcomes" fragmenttypes="outcome">
    <title>Learning Outcomes</title>
    <t:fragment-ref id="3" type="outcome" />
  </section>

  <section id="tutorial">
    <title>Tutorial</title>
    <fragment id="4">
      <para><t:value name="ps.description"/></para>
    </fragment>
  </section>

  <section id="related">
    <title>Related</title>
    <xref-fragment id="5"/>
  </section>

</document>

Simple Example

Following is a simple document-template created by using the Document config page located under the Dev tab in the Developer perspective.

To begin, select 'Project Files' from the Dev menu at the top right of the screen.

Click on the 'Import pack' icon.

import-pack.PNG

The following document types should now be available.

import-doc-types.PNG

Choosing to edit the Document template, Document config or Editor config of social_security_advice_request will display the below screens.

doc-template.PNG

doc-config.PNG

editor-config.PNG

After saving the document-template file, the document type will be available through the New Document menu. From the example code above, the following interface will be generated:

create-new.PNG

create-new2.PNG

The generated document will automatically populate the first name and surname fields (depending on what you enter in the create document interface), as well as the day called, time called, open date and worker fields.

text-test.PNG

testing-dob.PNG

testing6.PNG

document-template.psml

testing-date.PNG

testing1.PNG

document-template.psml

testing-gender.PNG

editor-config.json

editor-gender.PNG

date-time-called.PNG

document-template.psml

day-time-called.PNG

testing4.PNG

document-template.psml

*note - "<" is missing from start of property name in this screenshot

test-countn.PNG

editor-config.json

editor-review.PNG

editor-debt.PNG

testing-final.PNG

document-template.psml

testing-final2.PNG

facts.PNG

advice.PNG

related.PNG

test23.png

word.PNG

Word docx file

word2.PNG

Created on , last edited on