Pagesetter 6.1 manual

Jørn Lind-Nielsen

DocBook conversion: Axel Guckelsberger

Version 6.1-1

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation, with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license can be obtained from the Free Software foundation

Abstract

This manual documents how the web publishing tool Pagesetter for PostNuke works. Pagesetter is a publishing module that allows the PostNuke users to create web pages from structured data, with the data structure and output templates defined by the PostNuke administrator.


Table of Contents

1. Introduction
Introduction
Features
Installation
Organizing Publications
Printing This Manual
2. Tutorial
Tutorial
Creating a Publication Instance
Templates
Putting the News on the Frontpage
3. Permissions
Permissions
Topic Based Permissions
Permissions for Single Publications
4. Editing Publications
Editing Publications
Publish information
Location
Author Information
Setting Editor Defaults
5. Publication Types
Publication Types
Field Types
Upload handling
Publication Setup
Categories
6. Linking
Linking
Sorting
Filtering
Indirect Operands
Setting Defaults for Editor
Setting Default Topic
7. Templates
Templates
Template Variables
Using Categories
Using Pageable Fields
Using upload fields
Showing Hit Counts
Showing "Edit This" Link
Single and Multiple List Templates
Single Template
Multiple Templates
Theme Specific Templates
Template Operations
Auto Generated Templates
pnRender Plugins
Folder Templates
8. PostNuke Features
Waiting Block
List Block
Old Stories Block
Publication Block
Category Based Menu Block
PostNuke Hooks
PostNuke Searching
Short URLs
Caching in pnRender
Organizing Publications
9. Extra Features
RSS Feeds
Title-Hack
FEProc Integration
FEProc Integration
Pagesetter FEProc Handler
Example - An Event Registration Setup
10. Extra Tools
Importing Data
Importing From PostNuke News
Importing From ContentExpress
Importing From PostCalendar
Importing Pagesetter Publication Types
Exporting Pagesetter Publication Types
11. Workflows
Definition
Standard workflows
12. Customisation
Style Sheets
Input Forms Layout
Input plugins
HTMLArea Editor
Internal templates
Post Submit Handler
I. Appendix
A. Useful Hints
B. Credits
C. GNU Free Documentation License
PREAMBLE
APPLICABILITY AND DEFINITIONS
VERBATIM COPYING
COPYING IN QUANTITY
MODIFICATIONS
COMBINING DOCUMENTS
COLLECTIONS OF DOCUMENTS
AGGREGATION WITH INDEPENDENT WORKS
TRANSLATION
TERMINATION
FUTURE REVISIONS OF THIS LICENSE
ADDENDUM: How to use this License for your documents

List of Figures

1.1. Screenshot illustrating a News item constructed with Pagesetter
4.1. Editing publications - user data
4.2. Editing publications - meta data
5.1. Publication type editing.
5.2. Editing categories
6.1. Example categories used for books
6.2. Indirect operands used in input formular
8.1. Example menu block based on a category setup
10.1. Various import tools.

List of Tables

3.1. Permission levels
3.2. Examples for permission setups
3.3. Permission setup for access to a single publication item.
6.1. URL parameters
6.2. Template overview by URL function

List of Examples

2.1. Example template for News item.
6.1. Ordering by core fields
6.2. Ordering by category fields and category field properties
6.3. Filtering
6.4. Filtering by category fields
7.1. Example template with upload field (named "document").
8.1. Example of search form taken from the standard PostNukeSilver theme.
12.1. Adding a CSS class selector to HTMLArea's right-click context menu.

Chapter 1. Introduction

Introduction

Pagesetter is a publishing module that allows the PostNuke users to create web pages from structured data, with the data structure and output templates defined by the PostNuke administrator. The goal is ultimately to be able to define all the kinds of publications that normally require different PostNuke modules. The list includes:

  • News items with a headline, teaser text, news text, and an associated image.
  • FAQ items consisting of a question and an answer.
  • Recipes with a title, a list of ingredients, and instructions.
  • Task lists
  • Course descriptions
  • Music collections
  • … and so on.

Figure 1.1. Screenshot illustrating a News item constructed with Pagesetter

Screenshot illustrating a News item constructed with Pagesetter

See the readme.txt for installation instructions.

Features

  • User defined publication types with a variable number of input fields of many different kinds.
  • Templatable output lets the adminstrator layout the publications in almost any way he want using PostNuke's pnRender system.
  • The what-you-see-is-what-you-get (WYSIWYG) editor htmlArea simplifies input—no need for knowing HTML codes.
  • Multiple nested categories can be created and used for input fields.
  • Multi-page entries.
  • Flexible workflow system with plugins to extend it.
  • Revision control—Pagesetter stores the complete history of all changes to any publication.
  • File uploads can be associated with all publications. With this feature you can design your own document management system, complete with workflows and revision control, or just upload images with your News items.
  • Dates can be selected with a built-in date picker.
  • Top performance with cached output.
  • Two level approval control of publishing.
  • Publications can be timed with a start and end date.
  • PostNuke homepage can be set to show any list of publications you want.
  • Pagesetter is PostNuke hooks compatible which means you can enable comments, scoring, Auto-links and many other features with just a few clicks.

Installation

Please read the "install.txt" file for instructions.

Organizing Publications

Pagesetter publications can be organized in a folder structure with the help of another module "Folder" from www.elfisk.dk. Without this module you can browse through linear lists of publications with Pagesetter itself.

Read more in the PostNuke Features chapter.

Printing This Manual

The CSS styles in the HTML version has been carefully selected to generate a nicely formatted printout. This has although only been tested on the Internet Explorer 6.0. If you choose to print the manual then please remember to set the paper format to A4 portrait. You should have left and right margins set to 5mm.

Chapter 2. Tutorial

Tutorial

Let us start with a quick tutorial showing how to setup your very first Pagesetter publication. For this we use a News type as an example. With this publication type we will be able to write News with a title, a short header, full text, and an associated image selected from Photoshare.

Make sure you have admin rights on your PostNuke site and then goto the Pagesetter administration page. Here you will see an empty list of publication types. Except for the publication named "PN-News" it should look like below:

Now click "New Publication Type" which will bring you to this window were you define your publication setup:

Here you must fill out the name of the publication and add your input fields—these are the input fields that end user will be able to enter data in. The field description is accessible as a "on-mouse-hover" hint when editing your publications.

Use the green and red +/- symbols to add and delete fields. Make sure you name everything exactly as you see it in the image (description text is unimportant).

Important

The sorting keys will be empty until you have committed some fields. Do not press "Commit" before you are satisfied with the result!

The title radio button indicates which field to use as title field in the various Pagesetter lists. The multiple pages checkbox allows you to define which field the user may insert page breaks in. Only one field may be selected for multiple pages, but none need to be so. Page breaks can be inserted using the editor button for it or inserted manually with a <hr class="pagebreak"/> tag. The templating system then ensures the field is split into pages separated by that tag.

The "List Setup" settings specify sorting order and such like for this publication type when an overview is requested—for instance when Pagesetter is chosen as the frontpage module in PostNuke's admin settings. The sequence of the fields does also define the sequence in which they are presented when creating a new publication instance. Now you are ready to submit the publication type to the database. Press "Commit" and you are done.

Creating a Publication Instance

Now that we have a publication type available (News) we should start publishing something. Select the "New" link in the publication types window:

This will bring you to the "Publication Edit" window:

Entering the text should be straight forward. The image URL can be selected from Photoshare (if installed) by clicking the "..." button. Now press "Save" and you are done and will be brought to the publication list:

If you have named all your fields correctly then you should be able to view your new publication through the pre-installed templates. Click the view action and you should see:

Important

You must enable images (with attributes!) and other HTML tags in PostNuke's setup before you can display any images. If you forget this then you will only see the text "<img ...>" instead of the actual image.

You must also enable popups for your site if you have any popup blockers installed, otherwise HTMLArea and previewing won't work.

You must also have EZComments installed to get the News example running with the templates in the examples directory.

Templates

The template used to display your data is named PN-News-full.html and is located in the pntemplates directory. As you can see the name consists of the publication name concatenated with a dash and a template format name (in this case "full"). If you open the file you will see something like:

Example 2.1. Example template for News item.

// (the html presented is not the most correct with respect
// to accessibility and xhtml compliancy)
<div style="width: 500px;">

<div class="pn-title"><!--[$title]--></div>
<div class="pn-sub">By: <!--[$core.author]--> 
(<!--[$core.creator]-->) 
<!--[$core.lastUpdated|date_format:"%Y.%m.%d"]--></div><p>

<table>
 <tr>
  <td valign="top">
   <!--[$text[$core.page]]--><br>
   <!--[if $core.pageCount > 1 ]-->
    Page: <!--[pagesetter_pager]-->
   <!--[/if]-->
  </td>
  <td valign="top">
   <!--[if $image != "" ]-->
     <img src="<!--[$image]-->" width="200" 
          alt="<!--[$imagetext]-->" 
          title="<!--[$imagetext]-->"><br>
     <i><!--[$imagetext]--></i>
   <!--[/if]-->
  </td>
 </tr>
</table>

<p>

<table width="100%"><tr>
<td><!--[$core.printThis]--> | <!--[$core.sendThis]--> 
| Hits: <!--[nocache]--><!--[$core.hitCount]--><!--[/nocache]-->
| <!--[nocache]--><!--[$core.editInfo]--><!--[/nocache]--></td>
<!--[if $core.pageCount > 1 ]-->
 <td align="right">(Page <!--[$core.page+1]--> 
 of <!--[$core.pageCount]-->)</td>
<!--[/if]-->
</tr></table>

</div>

The <!--[ ]--> HTML comments contain code for the pnRender templating system. Basically you can put $fieldName into them to show your publication fields, but more complex stuff like switching statements and for-loops can be added too. The variable name $core is predefined by Pagesetter and contains core information about the publication like author and creation date. Do not edit the template directly. Copy it instead to a theme specific template and put it into your themes directory as described in the template chapter. Read more about templates in the Template chapter.

Putting the News on the Frontpage

If you want to show your News items on the frontpage of your PostNuke installation, you need to find the admin section of PostNuke and then go into the settings section. Here you find a dropdown somewhere where you can select Pagesetter as the frontpage module. But before that you need to tell Pagesetter which publication type to show on the frontpage. Go to the general settings of Pagesetter:

and select the News publication type for the frontpage:

If everything goes as expected you should be able to see the News list on the frontpage (thanks to www.postnuke.dk for design inspiration):

Chapter 3. Permissions

Permissions

Pagesetter works with five different access levels:

Readers
Users who are allowed to read Pagesetter publications.
Authors
Users who are allowed to submit new publications but do not have access to the list of existing publications.
Editors
Users who are allowed to submit new publications and have access to the list of publications.
Moderators
Users who are allowed to submit and delete publications, as well as moving them back and forth to the depot.
Administrators
Users who are allowed to create new publication types as well as performing other administrative Pagesetter tasks.

On top of the raw PostNuke permission system, Pagesetter adds it's own workflow system. Through this it is possible to specify who has access to what and when. The workflow system is able to handle such diverse setups as a Wiki framework (well, something that simulates it to a certain degree) and an enteprise level workflow with authors, editors and moderators. Read more in the workflow chapter.

The Pagesetter permission levels are mapped into the PostNuke permissions like this:

Table 3.1. Permission levels

GroupComponentInstancePermission
readerspagesetter::tid:pid:Read
authorspagesetter::tid:pid:Edit
editorspagesetter::tid:pid:Add
moderatorspagesetter::tid:pid:Delete
adminspagesetter::tid:pid:Admin

In the table tid is used as the publication type ID and pid as the publication (instance) ID. You can use these to give access to specific subsets of the publications. The special instance is '::' which matches both all publications and the generic test for access to the Pagesetter module. Here is a few examples:

Table 3.2. Examples for permission setups

GroupComponentInstancePermissionResult
All groupspagesetter::::ReadRead access for all groups to all publications.
Unregisteredpagesetter::4::NoneDeny access for unregistered users to all publications of type 4
Group Apagesetter::3::EditEdit access to publication type 3 for all in group A
Group Bpagesetter::2:(1|5|19):EditEdit access to publications 1,5 and 19 of type 2 for all in group B
My page adminpagesetter::1::AdminAdmin access for "My page admin" group to publication type 1

Caution

Remember that the order of the permission items is significant. PostNuke reads permissions from the top and downwards until it finds a match. Permission instances are specified with regular expressions!

Topic Based Permissions

Pagesetter supports topic based access control through the stand-alone module "TopicAccess" which you can download from www.elfisk.dk. The TopicAccess module lets the administrator define read/write access to Pagesetter based on the topic selected for a publication.

Topic based permission control follows these rules:

  • Users can only select from those topics they have write access to when writing a new publication.
  • Users can only edit a publication if they have write access to the topic it is associated with.
  • Users can only view a publication if they have read access to the topic it is associated with.

Permissions for Single Publications

The way that Pagesetter (and most other modules) uses the permission system can in some instances make it quite difficult to figure out a way to grant access to one single publication. For a publication ID P of type T you would expect to be able to match "pagesetter::" and "T:P:" for read and then follow it by a "pagesetter::" and "T::" for none, meaning "grant read access to specific publication and deny access to the remaining". This could for instance be a News publication (item 7 og type 1) where you want a specific welcome message on the front page available for all unregistered users. But you do not want them to be able to read the rest. For this one would think of the following:

GroupComponentInstancePermission
Unregisteredpagesetter::1:7:Read
Unregisteredpagesetter::1::None

But this would not work! Pagesetter first checks with an empty publication item for access to the publication type as a whole. This means it tries to match "pagesetter::" and "1::" before any thing else. This does not match the first line, so access is denied even before we check for access to the single item. What you must do is:

Table 3.3. Permission setup for access to a single publication item.

GroupComponentInstancePermission
Unregisteredpagesetter::1:7:Read
Unregisteredpagesetter::1:.+:None
Unregisteredpagesetter::1::Read

The third line ensures access to the publication type as a whole. The second line denies access to all item specific checks (those with something in between the colons). The first line grants access to the specific item.

Chapter 4. Editing Publications

Editing Publications

Instances of a publication type, for instance News items as shown in the tutorial, are created and edited in the Edit window. This window consists of two main parts—the publication specific fields, as defined by the system administrator, and the meta data defined by Pagesetter. The publication fields part looks somewhat like this:

Figure 4.1. Editing publications - user data

Editing publications - user data

What you see is three different fields defined by the administrator of the web site. It is up to you to write whatever you find fitting for your kind of publication—in this case a News item describing some of the pleasantries of hiking Bornholm.

The meta data fields looks like below.

Figure 4.2. Editing publications - meta data

Editing publications - meta data

Publish information

Approval state
The approval state is an information about where the publication is located in the associated workflow. The possible states depends on the workflow setup, but the standard workflows uses states like "Preview" and "Approved" to denote the fact that the publication is ready for preview (by an editor) or actually approved by the moderator. The approval state can only be changed by one of the workflow actions available at the bottom of the page.
Online setting
This field indicates whether the publication is online or not, and thereby if it is visible on any of the publication lists or can be found by searching.
Publish Date

This setting specifies the first day a publication goes online. Normally this value is left empty, but you can get Pagesetter to insert the current date for you. This feature is enabled in the general configuration section ("Auto fill publish date").

Expire Date

This setting specifies the day a publication goes offline (it will not be available at the specified day).

Location

These settings categorizes the publication and defines where to find it.

Topic

The PostNuke topic in which the publication belongs.

Show in lists

Specifies whether or not the publication should be shown in the general list of this publication type. This can be usefull if you want some publications to be accessible through a menu or handcrafted URL only.

Language

The language in which the publication is written. The language influences when the publication shows up in the various lists and menus. The language must match the user's language in order to show up—or be set to "All".

Author Information

These settings holds who has written the publication and when.

Publisher

The PostNuke user name of the user who created the publication. This name cannot be changed.

Author

The name of the publication author. The creator's real name is inserted here - but may at any later time be changed to something else.

Created

The date of creation.

Last updated

Last updated date.

Setting Editor Defaults

It is possible to assign defaults for new publications via the URL as shown in the linking chapter.

Chapter 5. Publication Types

Publication Types

Everything in Pagesetter begins with the declaration of a publication type. The publication type defines the set of fields that a publication may have, the name of the publication type, and a bunch of other things.

Pagesetter comes without any publication types pre-installed, so you will have to create your own. But a set of output templates for a News type is supplied—see the tutorial.

The publication type setup window looks like this:

Figure 5.1. Publication type editing.

Publication type editing.
Publication type editing.

The upper part lets you configure various things about the publication type as a whole. The lower part lets you add one or more fields to store publication data in. The fields in the upper part are:

Publisher
The name of the user who created this publication type.
Title
The name of this publication type.
Template
The template base name for this publication type. It is used to locate output templates that contains the name as part of the template file name. For this reason you must select a name that can be used as a file name. It will default to the publication type title.
Form name
Name of the directory to look into for customized input forms. Leave it empty if you do not expect to create your own forms. It will default to the publication template value. See the customization chapter for further information.
Description
A short description of the publication type. It is not used for any but a note on this window.
Enable PN-Hooks
Checking this checkbox will force Pagesetter to run it's output through PostNuke's hooks system. This enables commenting, scoring and other hook based features. Unfortunately you cannot specify which hooks to apply.
Workflow
The workflow configuration lets you define how complex a process you need for proof reading and approval of your publications. Pagesetter comes with three predefined workflows: "None", "Standard", and "Enterprise". The "None" workflow has no proofing or anything—publications are simply approved immediately upon submission. The "Standard" workflow is a two-step procedure with a moderator, and the "Enterprise" workflow is a three-step procedure with both editors and moderators. You can read more on workflows in the workflow chapter.
Number of publications to show in list
This lets you define how many publications you want to show up when this publication type is displayed on your PostNuke frontpage. It also applies to various blocks used by Pagesetter.
Sorting keys
These lets you define the default sorting order and direction of the publication lists. You must have committed your choice of fields before they are available in the key selections.
Default filter
This is a filter expression to be used when no other filter is supplied on the URL. For instance "category:eq:5" to display all items with the field "category" set to category item ID 5. Se Filtering.
Default folder
To use this field you must first install the "Folder" module separately. This field indicates where new publications should be located in the folder structure. If you do not select a folder then Pagesetter won't use the Folder module.
Default sub-folder

To use this field you must first install the "Folder" module separately. If you want more control over the location of new publications then specify a sub-folder name here. The name may include references to values in the publication which means you can create sub-folders on the fly by, for instance, including either topic name, created date or even both in the sub-folder name!

The syntax is whatever Smarty uses (just like the templates) except that you must use curly braces to indicate Smarty variables. Besides that you can refer to any publication data in exactly the same way as you would do in a template. The sub-folder name can include slashes to indicate sub-sub-...-sub-folders. None of the sub-folders need to exist prior to creating a publication.

Example: to create a sub-folder based on the topic name and current year and month you could write {$core.topic.name}/{$core.created|date_format:"%Y/%m"}. In this case you would get a sub-folder named Linux/2005/06 for a publication created in June 2005.

Default topic
This is the topic which will be assigned to any dynamically created sub-folders.

Field Types

Each field in a publication must have a type associated with it. Field types can be any of the following kinds:

string
A simple text string with no formatting. Text is entered in a one-line input field.
text
A simple text string with no formatting. Text is entered in a multi-line input field.
html
An HTML formatted text input. Text is entered via a what-you-see-is-what-you-get editor (on the Internet Explorer and Mozilla).
image (url)
The URL to an image. The URL may either be entered manually or selected from any of Photoshare's albums.
bool
A checkbox.
int
Text field with validation for integers.
real
Text field with validation for real numbers.
time
Text field with validation for time (HH:MM).
date
Text field with validation for dates (YYYY-MM-DD). Uses a JavaScript date picker.
User defined category
Dropdown field with the items from the category.
Image (HTML)
The complete HTML for an image. The HTML may either be edited manually or inserted from Photoshare with a popup button.
Image upload
Field for uploading an image. Pagesetter automatically generates thumbnails and download/display links for use in the templates.
Any upload
Field for uploading of any kind of file (also images). Pagesetter automatically generates download links for use in the templates.
E-Mail
Text field with validation for E-mails and "mailto:" link in input formular.
Hyperlink
Text field with facilities for verifying URL when editing.
Currency
Text field validation for numbers (identical to "real" but future versions may add more semantics to this type.

Some examples of fields could be a headline (text), some instructions (html), payment (real), the starting date of some event (date) and so on. There is no restriction to how many fields you may choose to use.

Upload handling

Upload fields are just, from an abstract point of view, data fields like all the other ones—you can have as many upload fields you want in one publication and uploads are also handled correctly by the revision control system.

When editing a publication with upload fields, you only need to upload your files once—even when editing and previewing your input. Any uploaded file is stored temporarily until you submit your publication, after which the uploaded file is permanently stored with the publication.

Uploads are stored as files on the web server and only references to these files are stored in the upload fields. You must configure the location of the files in Pagesetter's admin panel (goto administration::configuration::general). The upload directory must be writable by the webserver for this to work.

Uploaded files are accessed via PostNuke's standard index.php file and thereby through Pagesetter. This has two implications 1) files are always subject to the same access control as the publication it is stored with, and 2) data must be streamed through PHP, generating a performance overhead comparing to linking directly to the files. It is the developers opinion that complete access control is more important than performance in this case.

Caution

You should never store your uploads in a directory accessible through the web server since this makes it possible to download the files without access control. Unfortunately this cannot be avoided in some hosting environments, in which case you should name your upload directory something unguessable.

Changing or deleting upload fields

Pagesetter does not automatically delete uploads associated with a publication type when an upload field is either changed to another type or deleted.

Therefore you must manually delete the uploaded files when you decide they are not in use anymore.

Uploaded files are named TxPxRxF.dat where T is publication type, P is publication ID, R is revision and F is field name. So if you remove field "document" on publication type 5 then you should delete all files named 5x*document.dat.

Publication Setup

See the tutorial.

Categories

It is possible to define categories to be used as dropdown elements in the input. An example of a category could be a selection of music media, for instance "CD", "DVD", "Tape", or "LP". A categorization could also be book genres: "Fiction", "Art", "History", and so on. Categories can even be nested, so for instance you can define sub-genres for books "Fiction:Science Fiction" and "Fiction:Fantasy". The categories are defined in this window:

Figure 5.2. Editing categories

Editing categories

It should be relatively simple; create a new category and then add the items you want in it. When all is as expected you commit the setup to the database. The category fields are:

Title
A displayable value that can be shown to the user.
Value
Any text string for your own use. The value field need not to be used, but can for instance help with sorting or selecting category items.
Description
Help field which can be displayed as extra information about the category. Currently not used, but may in a future version of Pagesetter be used to generate automatic online help.

The category can afterwards be used for one or more fields in the publication types. Just select the category from the field type dropdown in the publication setup window.

Chapter 6. Linking

Linking

Here is a list of the various Pagesetter URLs you can use:

List: .../index.php?module=pagesetter
The basic link used for Pagesetter on the frontpage. This link shows the Pagesetter default publication list.
List: .../index.php?module=pagesetter&tid=T&topic=P&lang=L
The same as the above link but with various extra modifiers. You can specify which publication type you want to show the list for by setting tid to the type ID. In the same way you can specify the topic ID as well as language (otherwise the current language is used to filter the list). All the modifiers are optional and can be mixed as necessary.
View: .../index.php?module=pagesetter&func=viewpub&tid=T&pid=P
This is the link for viewing a specific publication of a specific type. You need to set tid to the publication type ID and pid to the publication ID.
Print: .../index.php?module=pagesetter&func=printpub&tid=T&pid=P
This is the link for showing a publication as "printable"—which means without the PostNuke frameset and with a special template. The tid and pid parameters works as above.
Edit: .../index.php?module=pagesetter&func=pubedit&tid=T
This is the link for the creation of a new publication of the publication type specified in tid. You can use this link for a "Submit Publication" menu entry like the standard PostNuke "Submit News" link.
Edit: .../index.php?module=pagesetter&func=pubedit&tid=T&goback=1
Edit link as above but redirect user to refering page after edit is completed.
Edit list: .../index.php?module=pagesetter&func=pubList&tid=T
This is the link for the editor's list of publications and is used for managing all the publications. As usual the tid parameter identifies the publication type ID.
Inline display of uploaded file: .../index.php?module=pagesetter&type=file&func=get&tid=T&pid=P&fid=F
This is the link for inline display of an uploaded file or image. Use T and P for type ID and publication ID as in the previous examples, and F for the field name of the upload field. With this URL Pagesetter utilizes the Content-Disposition HTTP header for marking the data as "inline".
Download of uploaded file: .../index.php?module=pagesetter&type=file&func=get&tid=T&pid=P&fid=F&download=1
This is the link for download of an uploaded file or image. Use T and P for type ID and publication ID as in the previous examples, and F for the field name of the upload field. With this URL Pagesetter utilizes the Content-Disposition HTTP header for marking the data as "attachment".

Here is a short description of the various URL parameters:

tid
Publication type ID.
pid
Publication instance ID.
topic
PostNuke topic ID.
lang
PostNuke language ID.
fid
Pagesetter field name for display of uploaded file.
download
Request download of uploaded file instead of displaying it inline.
tpl
Template format for overriding default. Use for instance "tpl=RSS" to access a template file named News-RSS.html. The template name "News" is always derived from the publication type and cannot be changed. If used with a list display then Pagesetter will look for News-RSS-header.html and News-RSS-footer.html also. If News-RSS-header.html cannot be found then News-RSS.html is assumed to be a single template list without header/footer.
pubcnt
The number of publications to show on one page. If left out then the publication type default is used. If set to zero then all publications are shown.
goback
Used to redirect the user back to refering page after editing. Set it to 1 to enforce this redirection. If this parameter is not set the user is redirected to the editors list of publications.

Here you can see which parameters you can use for the different functions (with less used functions included):

Table 6.1. URL parameters

FunctiontidpidtopiclangtplpubcntDescription
Nonex xxxxNormal publication list
viewpubxx  x Full publication display
printpubxx  x Full publication display, no frames
dumppubxx  x Full publication display, no surrounding html tags
xmlpubxx  x Full publication display, adds content-type text/xml
pubeditxx    Edit publication
publistx     Editor's list of publiations
printlistx xxxxDisplay list of publications, no frames
dumplistx xxxxDisplay list of publications, no surrounding html tags
xmllistx xxxxDisplay list of publications, adds content-type text/xml

Here is a list of the templates required for the various options:

Table 6.2. Template overview by URL function

FunctionHeader / footerDef. TemplateDescription
NonexlistNormal publication list
viewpub fullFull publication display
printpub printFull publication display, no frames
dumppub printFull publication display, no surrounding html tags
xmlpub xmlFull publication display, adds content-type text/xml
pubedit -Edit publication
publist -Editor's list of publiations
printlistxlistDisplay list of publications, no frames
dumplistxlistDisplay list of publications, no surrounding html tags
xmllistxlistDisplay list of publications, adds content-type text/xml

Sorting

With Pagesetter you can sort the various lists of publications via restrictions in URL. To do so you specify "orderby=field-list". The list of fields is separated by commas and you refer to the field names as you would do in a template. Either as fieldName or as core.fieldName. The default sorting direction is ascending, but descending can be specified with a ":desc" appended to a field name.

Example 6.1. Ordering by core fields

orderby=core.author,title
Order by author and title.
orderby=core.hitCount:desc
Order by hitCount descending, neat for displaying a "most read articles" box.

Example 6.2. Ordering by category fields and category field properties

orderby=category
Order by the sequence defined in the category list.
orderby=category.value
Order by the value defined in the category list.
orderby=category.title
Order by the title defined in the category list.
orderby=category.fullTitle
Order by the full title (e.g. Books:Art:Painting).
orderby=category,core.created
Order by the sequence defined in the category list and by the date and time the publication was created.

Filtering

It is also possible to filter the various lists of publications via restrictions in the URL. To add a filter you simply specify "filter=expr" in the URL where expr is a filter expression. Filter expressions are written as comma-separated lists of filter terms where each term consists of a field name, an operator, and an operand separated by colons or hats (^). A single filter combines all it's expressions using an AND-operator (making it a conjunction). The possible filter operators are:

eq
Equal.
ne
Not equal.
lt
Less than.
le
Less than or equal.
gt
Greater than.
ge
Greater than or equal.
like
Using database's LIKE operator to match operand as '%operand%'.
null
Test for field being NULL. Should be used without an operand—like filter=FieldName:null.
nottnull
Test for field being NOT NULL. Should be used without an operand—like filter=FieldName:notnull.
sub
Test for a list field being equal to or an descendant of the operand. Only valid for category fields.

The right hand side operands in a filter expression may contain "@now" which will expand to the current date. This may although not be that usefull since there is no support yet for plus or minus operators.

Caution

Beware that URL variables are separated with ampersands "&". Ampersands are therefore also used to separate different filters on the URL. But multiple filters are OR-ed together which is opposite the usual interpretation of the ampersand!

Multiple filters can be combined on the URL using "filterN=expr" where N is an integer starting from 1. Multiple filters are combined using an OR-operator (putting the whole filter language in a disjunctive normal form).

Example 6.3. Filtering

filter=title:like:pagesetter
Find all the publications where the title field contains the word "pagesetter".
filter=age:ge:18
Find all the publications where the age field is greater than or equal to 18.
filter=age:ge:18,country:eq:DK
Find all the publications where the age field is greater than or equal to 18 and the country is equal to "DK".
filter1=age:ge:18,country:eq:DK&filter2=country:eq:NO
Find all the publications where (1) the age field is greater than or equal to 18 and the country is equal to "DK", or (2) the country is equal to "NO".

Now assume we have a book category as shown in the following image and use this in a book review publication with a field named "category" (using the category type of course).

Figure 6.1. Example categories used for books

Example categories used for books

Then we can select various sub-sets of the reviews with the following examples.

Example 6.4. Filtering by category fields

filter=category:eq:8
Find all the reviews of category "Fiction"—but not sub-sets of that. The value to compare with is the category ID!.
filter=category:sub:8
Find all the reviews of category "Fiction" and any sub-sets of that (Science Fiction and Classics). The value to compare with is the category ID!.
filter1=category:sub:11&filter2=category:eq:23
Find all the art(11) and drinks(23) reviews, but not non-alcoholic drinks (since we use the eq operator instead of sub operator). The value to compare with is the category ID!.

It is furthermore possible to match all items using the special list value "top", for instance in a filter like "filter=category:sub:top".

Indirect Operands

The above setup is fine as long as you are using hard-coded URLs. But when you want to let the user enter something in a form and then filter by that, you need to refer to other URL variables in the filter. Assume for instance you want to filter a keywords field using the like operator based on something the user enters in a form. The user input is entered in a HTML input field named "keyword". Now we can refer to the URL variable as "$keyword" in a filter like "filter=keywordField:like:$keyword".

Figure 6.2. Indirect operands used in input formular

Indirect operands used in input formular

An example template using this feature could look like this for the list-header template of a knowledge base:

<div class="pn-pagetitle">Knowledge Base</div>

<form action="<!--[pnmodurl modname="pagesetter" tid=$core.tid]-->" method="POST">
 <table>
  <tr><td>Keyword:</td><td><input type="text" name="keyword"></td><tr>
  <tr><td><input type="submit" value="Update"></td><tr>
 </table>
 <input type="hidden" name="filter"
        value="keywordField:like:$keyword">
</form>

<ul>

Setting Defaults for Editor

You can assign default values to the editor when creating a new publication. Simply add "set_xxx=yyy" to the URL and the user defined variable xxx will be set to the default value yyy instead of being empty. Use category ID for category fields. Example: assume you have a News publication and a Project publication. The News publication can be categorized by some category. The same goes for your projects. On each project page you can now add a "Submit Related News" link that presets the category of the News item to that of the current project. To do so your Project template must contain something like this:

<div class="pn-pagetitle">Projects</div>

...

<a href="<!--[modurl module=pagesetter func=pubedit tid=T
                     set_category=$category.id]-->">...</a>

...

Setting Default Topic

The default topic is, for no really good reason, handled specially. You can set the topic via the URL variable topicid. The value must be a topic id.

Chapter 7. Templates

Templates

The output templating system uses a set of template files for each publication type and depends on the PostNuke .75 pnRender system (see installation guide).

Note

You can read a lot more about the Smarty templating system (that pnRender builds on, and thereby Pagesetter) on smarty.php.net.

The template files are stored in pagesetter/pntemplates/... and they are named after the publication template name like "template-format.html" where template is specified in the publication setup and format depends on the situation.

Pagesetter uses the following formats in various situations (here an example filename is shown in the parenthesis):

list (News-list.html)
The compact view of a publication when shown in a list.
list-header (News-list-header.html)
A template shown before a list.
list-footer (News-list-footer.html)
A template shown after a list.
list-single (News-list-single.html)
This single template takes the place of list, list-header, and list-footer in case no list-header template is found. This kind of list templates gives you more control over the layout, but disables caching of the list output.
full (News-full.html)
The full view of a publication.
print (News-print.html)
The full view of a publication when shown as "Print this" without PostNuke frames.
xml (News-xml.html)
Full view of publication as XML. Used for the xmllist and xmlpub functions that adds a "Content-Type: text/xml" to the HTTP header.

Important

1) Remember to make pagesetter/pntemplates writeable by the webserver if you want to use Pagesetter automatic generation of templates.

2) You always specify a format (like "RSS") when asked to supply a template in a block or URL. You do not specify a full filename!

3) If a list display cannot find a template header, for instance News-list-header.html then it assumes a single template list is used and looks for the format "list-single" instead, for instance News-list-single.html.

Template Variables

The templates may refer to all of the user defined fields and most of the core meta data (author etc.). Template variables are inserted using {$name} or <!--[$name]--> where "name" is the name of a variable. The braces can be used for simplicity but the best solution is to use the HTML comments style since this is compatible with various HTML editors. The user defined fields are simply refered to by their field name, whereas the meta data is refered to through the "core" object as {$core.name} where "name" may be any of the following core fields:

id
A unique integer value identifying the publication.
tid*
The publication type ID.
format*
The template format name, e.g., "list" in News-list-header.html.
author
Name of the author as set in the publication editor.
title
Copy of the value from the specified title field.
topic
Associated topic description. This is a struct with the following fields: id, name, text, and image. Use for instance like <!--[$core.topic.name]-->.
creator
Name of the person who actually created the publication.
created
The time stamp of when the publication was created. Time stamps are stored as seconds since 1970 (or what ever internal format the SQL servers uses) and needs to be formatted for printing. For this you can write <--[$core.created|date_format:"%d/%m/%Y"]-->. as an example format that generates DD/MM/YYYY.
lastUpdated
The time stamp of when the publication was last updated. Check created for a description of time stamps.
fullURL
The URL to the full display of the publication.
printThis
A complete link to "Print this" with description.
printThisURL
The URL to "Print this".
sendThis
A complete link to "Send this" with description.
sendThisURL
The URL to "Send this".

The items marked with * are also available in list headers and footers.

Using Categories

When refering to a category item you must further specify which property of the item you want. You can choose between the title, the qualified title (with parent items prefixed), the value, or the description. The properties are accessed as sub-values of the field (just like the properties of the core variable or a topic field). The possible category properties are:

title
Item title.
fullTitle
Qualified item title. The parent item titles are prefixed with colon as separator. For instance Fiction:Fantasy.
value
Item value.
description
Item description.

For instance, say you have a category field in your publication type called bookType. It is defined as a category called typesOfBooks. To add the title of the category field to your template use <!--[$bookType.title]-->.

If you need to generate a select-box for a specific category field then you can use the pagesetter_listSelector Smarty plugin like this:

<form action="...">
 Select Category: <!--[pagesetter_listSelector 
 name="categoryInput" field="category"]-->
 ...
</form>

This will produce an HTML "select" input with the name "categoryInput" based on the field "category". The select input will show item titles and use item IDs as values.

Using Pageable Fields

A field that has been enabled for multiple pages is accessed as an array of pages, so you will have to specify which page to show. The page number is passed in the URL as the query variable page which can be accessed like $core.page. You can get the number of pages as $core.pageCount. The template system offers a "pager" generator function named pagesetter_pager. The pnRender module already offers different kinds of pagers, but I never got them to work with Pagesetter. Besides that this one is easier to use with Pagesetter items. To insert the pager you add <!--[pagesetter_pager]--> to the template. The function accepts the following parameters:

page
The current page number—zero based for look-up in page array. If left out then $core.page is used.
pageCount
The number of pages available. If left out then $core.pageCount is used.
baseURL
The base URL of the view (link to page). If left out then $core.baseURL is used.
next
A piece of HTML to insert as the "Next page" link. Default is ">"
prev
A piece of HTML to insert as the "Prev page" link. Default is "<"
separator
A piece of HTML to insert as the separator between page number. Default is &nbsp;
pageClass
A CSS class name to include in the anchors of the prev/next links.
thisPageClass
A CSS class name to put the current page number into using a <span> tag.

Example template:

Page <!--[$core.page+1]--><br>
<!--[pagesetter_pager]-->

and a bit more advanced example:

Page <!--[$core.page+1]--> of <!--[$core.pageCount]--><br>
<!--[pagesetter_pager prev="<img src='leftArrow.gif'>"
                      next="<img src='rightArrow.gif'>"]-->

Using upload fields

When refering to upload fields you must specify one of the following properties:

url
Complete URL for inline display of document/image.
downloadUrl
Complete URL for downloading of document/image.
thumbnailUrl
Complete URL to thumbnail of image (only available for image uploads).
size
Size of document in bytes.
type
MIME type of document.

Example 7.1. Example template with upload field (named "document").

        
<dt>
  <a href="<!--[$document.url]-->"><!--[$core.title]--></a>
  (<!--[$document.size]--> bytes)
</dt>
<dd>
  <!--[$description]-->
  <span class="pn-sub">
  [<a href="<!--[$core.fullURL]-->">details</a>]</span>
</dd>
        
        

Showing Hit Counts

Hit counts can be displayed in your publications by inserting <!--[$core.hitCount]-->. But you need to do something to avoid caching of the output, otherwise the value would always stay the same (even though the actual hit count is incremented anyway). For this purpose Smarty adds the "nocache" tag. So the complete piece of code you need to insert is:

    <!--[nocache]--><!--[$core.hitCount]--><!--[/nocache]-->
    
    

Showing "Edit This" Link

Such a link can be added by inserting <!--[$core.editThis]--> or <!--[$core.editInfo]-->, where the first one takes you directly to the edit page, whereas the second adds a little popup with some publication info and links to editing and creation of new publications. As with the hit counts you must add a "nocache" tag around the code:

    <!--[nocache]--><!--[$core.editThis]--><!--[/nocache]-->
    
    
or
    <!--[nocache]--><!--[$core.editInfo]--><!--[/nocache]-->
    
    

Single and Multiple List Templates

The list view used in Pagesetter allows you to display a set of publications through a template. This can be done with either a single template, in which you must iterate through the elements yourself, or with a header/list/footer combination of templates that allows you to display one publication alone in a template, which is then invoked by Pagesetter multiple times.

Single Template

If a template named x-list-header.html can be found then x-list-single.html will be used instead. This template will be passed an array named publications which contains one entry for each publication in the list. Each array entry contains exactly the same variables as the ones passed to the multiple list template. This allows you to fine tune the exact positioning of the publications, at the cost of some performance since the complete list output cannot be cached. Checking on existence of x-list-header.html instead of x-list-single.html makes it possible to specify different template formats than "single".

Example:

<h1>My Frontpage</h1>

<table style="width: 70%">
  <tr>
    <td style="width: 50%">
      <h2><!--[$publications[0].core.title]--></h2>
      <!--[$publications[0].teaser]-->
    </td>
    <td style="width: 50%">
      <h2><!--[$publications[1].core.title]--></h2>
      <!--[$publications[1].teaser]-->
    </td>
  </tr>
  <tr>
    <td style="width: 50%">
      <h2><!--[$publications[2].core.title]--></h2>
      <!--[$publications[2].teaser]-->
    </td>
    <td style="width: 50%">
      <h2><!--[$publications[3].core.title]--></h2>
      <!--[$publications[3].teaser]-->
    </td>
  </tr>
</table>

Multiple Templates

If a template named x-list-header.html can be found then this will be displayed first. After this the template named x-list.html will be displayed one time for each publication in the list. At last the template named x-list-footer.html will be displayed. This reduces the possibilities for finetuning the layout, but it improves performance since the output of each of the publications can be cached.

Theme Specific Templates

With the pnRender system it is possible to specifiy theme specific templates. Just place your templates in the structure shown here (the top theme directory is PostNuke's main theme directory):

Template Operations

You can do a bunch of stuff with the Smarty template system. Please read the documentation at smarty.php.net as well as the pnRender documentation when it becomes available.

Here's anyway a few examples:

  <!-- Uppercase the title -->
<h2><!--[$title|upper]--></h2>

  <!-- Truncate the topic to 40 characters 
       use ... at the end -->
Topic: <!--[$topic|truncate:40:"..."]-->

  <!-- Produce category bread crumbs using "separator.png"
       image as separator instead of colons in the qualified
       title of a list item -->
Genre: <!--[$genre.fullTitle|replace:":":" 
            <img src='separator.png'> "]-->

  <!-- format a literal string -->
<!--[$"now"|date_format:"%Y/%m/%d"]--> 

Auto Generated Templates

It is possible to auto generate missing templates. Go to "Publications:Create Templates" in the menu. Here you find a list of your publications and the possibility to mark which templates to generate. The new templates are based on the templates named __template-... so you can modify these to suite your own needs.

Caution

You need to make the pntemplates directory writable by all for this to work!

pnRender Plugins

If you look into the pagesetter/pntemplates/plugins directory you will find a set of predefined plugins for Pagesetter. You will have to read the PHP code to get the documentation so far. But here's a short list:

pagesetter_pager
Generates a "<< 1,2,3, ..., >>" set of links for selecting a page in a multipaged publication.
pagesetter_ezcommentsCount
Counts associated EZComments items.
pagesetter_listBrowser
Generates a tree based on a category field. Just like the category based menu block. A more correct name would be "categoryBrowser".
pagesetter_inlinePubList
Creates a templated list of publications to be inserted on your page.
pagesetter_listSelector
Generates a HTML select tag for selection of items from a category field.
pagesetter_pubPager
Generates a prev/next link set for browsing through a list of publications.
pagesetter_createFilter
Creates a filter for input to the Pagesetter API function getPubList.
var
Internally used to auto-create templates.
bool_format
Formats a bool value as one of two strings.

Folder Templates

If you choose to organize your Pagesetter publications with the Folder module then you might want to create your own templates for this purpose. If you do not create any templates then the default templates folder.view.html and folder.select.html will be used for displaying items in the folder system and selecting items in the folder system respectively.

You can design your own templates and name them PubTypeName-folder.view.html and PubTypeName-folder.select.html respectively. You can use Image-folder.view.html or FileUpload.view.html for inspiration.

Chapter 8. PostNuke Features

Waiting Block

This block displays submitted publications waiting for approval. Since "waiting for approval" is a term that cannot be hardwired into the system, due to the flexible workflow system, you must configure which workflow states that should be considered "waiting". For each publication type you will find a list of checkboxes representing workflow states—each of these can be checked to mark that state as a "waiting" state.

You can create multiple Waiting blocks with different definitions of waiting states. By using PostNuke's permission system for the blocks you can then have different Waiting block setups for different groups of users.

Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Waitingblock:" and instance "Block title:Block Id:Type Id". The "Type Id" is the publication type Id.

List Block

This block shows the title of the top N publications of a specific type—for instance the last ten News items. The list is the same as shown when using Pagesetter as the frontpage module and the ordering as well as number of items depends on the publication type.

The List block uses the template named TypeName-block-list.html (for instance News-block-list.html) to render each of the publications. If this template does not exist then Default-block-list.html is tried and if even this is non-existent then Default.html is used.

Important

The list block cannot yet handle single template lists and must have both a header and a footer.

By default, for a publication with the template set to "News", the block looks for News-block-list.html. If you don't write anything then this is the file you must create. You must also supply News-block-list-header.html and News-block-list-footer.html in this case.

If you want something different then you must write a "format" name—for instance "other". Then the block will look for News-other.html, News-other-header.html and News-other-footer.html.

Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Listblock:" and instance "Block title:Block Id:Type Id". The "Type Id" is the publication type Id.

The list block supplies the header and footer templates with a simplfied $core template variable. This variable contains tid as the publication type ID, title as the title of the publication type, and blockTitle as the title of the block.

Old Stories Block

You can setup a block for "old stories" using the "List" block described above. The idea is that the front page normaly shows N items, so the "old stories" block should show the next X items after N. To do so you set the field "First publication number" to N and "Number of publications" to X. To style the list closer to the original PostNuke "old stories" block, you can specify the template to use as list-old-block, which is a supplied Pagesetter template for PN-News publications.

Publication Block

This block shows a specific publication using a template of your own choice. You need to select a publication type to show and then write the publication type ID yourself (so far no point-and-click selection). The template name must not include publication name and .html extension. So for a "News" publication you should just write "full" to use the "News-full.html" template.

Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Pubblock:" and instance "Block title:Block Id:Publication Id". The "Publication Id" is what is normaly referred to as "pid".

Category Based Menu Block

The category based menu block generates a nested list of menu entries based on the items in a specific category. Clicking on a menu item takes the user to a list of all publications associated with that category item or any sub-category item. Besides checking the normal permissions for Pagesetter, this block also checks for read access to the component "pagesetter:Listmenublock:" and instance "Block title:Block Id:Type Id". The "Type Id" is the publication type Id.

Figure 8.1. Example menu block based on a category setup

Example menu block based on a category setup

Configuring To set up the menu you need to specify the following attributes

Publication type
The publication type that this menu should show items from.
Category field to base menu on
This is the name of the publication field that this menu is based on. The field must be an existing field and be associated with some category. No error checking is done on this input.
Top item ID
If you consider the nested category structure as a tree then this is the ID of the category item that will be used as the root item for the menu. This allows you to only show a sub-set of the items. No error checking is done on this input. Leave it empty to get all items.
Maximum numbers of sub-levels to show
This specify how deep a nesting into the category structure the menu will show items from.
CSS class name for list
Any CSS class name of your choice. It will only be added to the top level <ul> HTML tag. You can find sample CSS rules in pagesetter/examples/News/styles.css.

PostNuke Hooks

Pagesetter is fully hook aware (with hooks for both display, transformation, create and delete). This means you can enable auto links, comments, rating and other nice hooks for your publications. To enable hooks you must do two things. First hooks must be enabled for Pagesetter in general. This can be done in the standard Admin::Modules section where you click "edit" for Pagesetter. This will bring you to the hooks enabling. The next thing is to enable hooks for your publication type. This is done in the checkbox "PN-Hooks" found in the publication type configuration.

Important

Hooks are not applied to publication lists! If they were then we would end up having comments applied to the various overview lists. Unfortunately this also means we don't get other interesting hooks applied.

PostNuke Searching

Pagesetter complies to the standard interface for PostNuke searching, which means you can search any of your publication fields for "all" words in a query as well as "any" word in a query. You may have to install the search file yourself (this depends on the zip-file structure). Copy the file html/modules/pagesetter/pnsearch/pagesetter.php into html/includes/search and you are ready to use the standard search module.

One of the things you often see in a PostNuke theme is a small search input field in the top bar. If you want to enable Pagesetter in this you must add a (hidden) input field in the web form with the properties type set to "hidden", name set to "active_pagesetter", and value set to "1".

Example 8.1. Example of search form taken from the standard PostNukeSilver theme.

echo  '<form action="modules.php" method="post">'
       .'<input type="hidden" name="name" value="Search">'
       .'<input type="hidden" name="file" value="index">'
       .'<input type="hidden" name="op" value="modload">'
       .'<input type="hidden" name="action" value="search">'
       .'<input type="hidden" name="overview" value="1">'
       .'<input type="hidden" name="active_stories" value="1">'
       .'<input type="hidden" name="active_pagesetter" value="1">'
       .'<input type="hidden" name="bool" value="AND">'
       .'<input name="q" type="text" size="15">'
       .'</form>';

Short URLs

It can be a bit difficult to get HTMLArea working with short URLs since it's popups are refering directly to the directories on the web server. For instance modules/pagesetter/guppy/HTMLArea/plugins/link.html.

To avoid this problem you must tell the URL rewwriter that the HTMLArea URLs should be ignored. This can be done with the following rewrite rule:

    RewriteRule ^(.+)guppy/HTMLArea30beta(.+)$ - [L,NC,NS]
    

The use of filters in the URL can also be a bit troublesome since the colons of the filter expressions ruins the browser's interpration of the URL. For this reason both hats (^) and colons (:) can be used in filters. Hopefully this helps.

Caching in pnRender

If you want improved performance from Pagesetter then make sure caching is enabled in pnRender. Go to "Admin - pnRender" and enable caching.

Organizing Publications

With the help of a separate module "Folder", found on elfisk.dk, you can organize your publications in a hierarchical folder structure. It is further more possible to import all of your existing Pagesetter publications into that module.

To import your publications you must first define folders and sub-folders for each of the publication types. Then make sure you have spelled the sub-folder template correctly—for instance by creating a few publications from within Pagesetter and verifying that they end up in the expected sub-folders. After that go to Pagesetter's admin page :: Tools :: Export Data and transfer all the items.

Chapter 9. Extra Features

RSS Feeds

Pagesetter can generate RSS feeds using the XML dumper and an appropriate template. The URL for this is: .../index.php?module=pagesetter&func=xmllist&tid=T&tpl=RSS This assumes the RSS template is in the file Name-RSS.html. An example template PN-News-RSS.html is supplied with Pagesetter. This file needs some modifications related to the feed title, image and description.

Title-Hack

It is possible to get the title of a Pagesetter publication put into the browser window's title bar with the use of the pagesetter_Title plugin, but only with Xantia themes.

It is also possible to do this using Jöerg's "Title-hack". Read more at http://sourceforge.net/projects/lottasophie.

FEProc Integration

FEProc Integration

FEProc is a PostNuke module for processing of forms data. It depends on FormExpress for the creation of web forms and then allows the admin to process the incoming data using various back-end handlers. FEProc comes with built-in handlers for e-mail notification, data transformations, validation rules, and much more—except a generic database API. With a Pagesetter handler for FEProc that problem is now solved.

Important

Users that needs to submit something through FormExpress/FEProc needs to have "Author" permissions to Pagesetter. This will enable them to submit new publications but it will not allow them to access other publications.

With the combination of FEProc/Pagesetter you can use FEProc for data input and validation and Pagesetter for storing the result. This can for instance be used in a setup where users can register for some event using FormExpress, get an acknowledge mail sent using FEProc, while at the same time you store a copy of the registration in Pagesetter.

In FEProc you combine various handlers by stringing them together to form a data pipe-line or set as FEProc calls it. Each instance of the handlers is called a stage and you may configure the stages in various ways depending on what kind of handler it is an instance of. A mail handler may let you define the recipient address, a display handler may let you define a template, and so on.

When data flows through the various stages it may be modified or transmitted to some external handler and then passed further on to the next stage. Each stage defines two ancestor stages—a success stage and a failure stage. Depending on the result of the current stage, data may be transferred to either the first or the second ancestor stage.

Pagesetter FEProc Handler

The Pagesetter handler lets you store previously entered data from a web form in a new publication instance of any type. The handler lets you pre-configure the publication type, the author name, a topic, and the workflow state for the new instance. The rest of the core attributes are hard-coded. All of the user defined fields are taken from any forms data entered before the Pagesetter handler is executed. To get the data from a web form you need to name the form fields exactly like the Pagesetter field you want it to be stored in.

Important

Remember to use FEProc's import manager to first import the Pagesetter handler before you can use it.

Here is a list of the attributes you can set for a Pagesetter FEProc stage:

Pagesetter type ID
The ID of the publication type you want to create an instance of when storing the FEProc data. Remember you must have an exact one-to-one match between the Pagesetter field names and your FormExpress field names.
Topic ID
The ID of the topic you want you publication associated with. This is currently hardcode and cannot be set from any form data. Use -1 for no topic.
Author
The name you want to store as the author for the created publication. This can be edited in the publication later on. The stored Publisher name/ID will be the PostNuke user ID of the person who initialized the publication creation through FEProc.
Author
The ID of the workflow state that the new publication should be placed in. The ID can be found in the state definition of the workflow definition file. A suitable works-for-all would be 'approved'.

Example - An Event Registration Setup

In this example we want our users to register for our "Advanced PostNuke" course. To do so they must submit their name and level of experience with Pagesetter. The level can be "Novice", "Administrator", or "Developer", which we want submitted as a Pagesetter list value. For this we create a publication type named "Registration" with the fields "Name" and "Expirence", but to do so we must also create a category type, which we will name "Experience". The category setup should be like this:

The publication setup should be:

So now we have somewhere to store the registration. Next thing is to create a FormExpress form. Open FormExpress' admin part and create a form with a text input named "name", and a dropdown input named "experience". The values of the dropdown field must be the category IDs for the Pagesetter category items (14, 15, and 16). The setup should be as in the following screen shots. Here is the FormExpress setup:

Here is the FormExpress dropdown field setup:

Now we have all we need to string a complete FEProc pipe-line together. Open FEProc's admin part and create a new set. This set should contain the following stages:

This can be obtained as follows:

  1. Create the Error Display stage. The template should contain a reference to ${message:error} in order to show Pagesetter error messages.
  2. Create the Success Display stage.
  3. Create the Pagesetter Store stage. Set "next success" stage to stage 2. Set "next error" stage to stage 1.
  4. Create the Mail stage. Set "next success" stage to stage 3. Set "next error" stage to stage 1.
  5. Create the FormExpress Input stage. Set "next success" stage to stage 4. Set "next error" stage to stage 1.

Now you are ready to accept registrations for your course!

Chapter 10. Extra Tools

Importing Data

Pagesetter offers a small set of tools to import data from other modules. You find these tools in the Tools::Import menu link which will take you to the window shown below.

Figure 10.1. Various import tools.

Various import tools.

Importing From PostNuke News

Pagesetter offers the possibility to import all of your existing news items into a new publication type. Select Tools::Import from the menu. Then click on the "Import News" button and you are done! You can check the "Add image field" in order to get a selectable image and image text associated with your news items.

Caution

If you have many (really many) news items then you may have trouble doing the import in the time allocated for your PHP script on the web server. If you have any influence on this factor then make sure your script have enough time. Otherwise, just try and see what happens, it probably works.

The new publication type will be named PN-News, comes with a full set of predefined templates named accordingly, and have the main text field converted to a multi-page field. The import does not import news categories. If your new(s) items do not show up in the list, then check the language, "include in lists", approval state, and online status of the missing items. You must also set the publication list ordering in order to sort descending by creation date. The import cannot import the comments. This is impossible since Pagesetter have no notion of a "comment". It only knows "Hooks" which can be used, among other things, for comments.

Importing From ContentExpress

Pagesetter also offers the possibility to import all of your ContentExpress pages into a new publication type. Select Tools::Import from the menu. Then click on the "Import ContentExpress" button and you are done! The new publication type will be named CE, comes with some predefined templates (full and print) named accordingly, and have the main text field converted to a multi-page field. The import does not import categories. If your new items do not show up in the list, then check the language, "include in lists", approval state, and online status of the missing items.

Importing From PostCalendar

The PostCalendar import is still a bit experimental. It can copy most of the data from PostCalendar into Pagesetter, except for the categories, which you will have to add afterwards. The templates can be found in pagesetter/examples/postcalendar. It has only been tested with PostCalendar version 4.1.0.

Importing Pagesetter Publication Types

Pagesetter can read a publication type configuration from an uploaded XML file and create a new publication type based on that data. Beware that a new publication type is created from the file, and any categories found in the XML file will also be created as new categories. So the current implementation does not allow you to update an existing publication type. Select Tools::Import from the menu. Then select an XML schema file to upload and click "Import XML Schema".

Exporting Pagesetter Publication Types

With Pagesetter you can export the setup of a publication type as an XML file. This file will be self-containing with both the publication setup and the categories needed for it. Select Tools::Export to create the export file.

Chapter 11. Workflows

Definition

The online Encyclopedia "Wikipedia" describes a workflow like this:

Workflow is the operational aspect of a work procedure: how tasks are structured, who performs them, what their relative order is, how they are synchronized, how information flows to support the tasks and how tasks are being tracked. [WikiPedia www.wikipedia.org]

In Pagesetter we can control where in the workflow a publication is located, what kind of actions you can perform on it, when it can be done, and who can do it. The location is defined by the publication's state, which for instance can be "Preview" for something in preview for an editor. The state is something visible and can always be seen on the editor's list. The actions can be things like "Submit", "Accept", or "Reject", all of which triggers some code that modifies the publication. A publication can only change state as a result of a workflow action. You never edit the state directly.

Each of the workflows may have some configuration settings that can be set through the menu Configuration::Workflow. The standard settings are things related to notification mails to be sent when a publication changes state during the workflow. The most obvious of these are the mail addresses of the editors and moderators that should be informed of new content arrivals.

The workflow system has been designed to let the administrator add his own workflow without modifying the existing ones. This is done through an XML file in the "workflows/custom" directory. A thorough description of how this is done can be found in the Workflow Manual bundled with this manual.

Remember that, no matter how clever a workflow you might create, everything begins and ends with your editors. The workflow in it self is only a technology, it is not and will never be a substitute for good writers.

Standard workflows

None

Allows Authors to create pre-approved documents. Not much to this one.

Standard

Allows Authors to submit a publication. It then requires an Editor to approve it.

Enterprise

Adds an additional approval step to the Standard workflow. An Author submits. An Editor accepts or rejects. A Moderator approves or rejects. A Moderator can also take publications offline and then put them back online.

Wiki

This workflow gives Authors full access to the publications. Every time someone updates a publication, a new version is built and a notification email is sent. All changes to all publications are logged. Every document is pre-approved. The use of Wiki for the name refers to the "edit-by-all" and revision control features. There is no support for the normal Wiki notations like using !/!!/!!! for headlines .

MyWiki

This workflow gives Authors full access to their own publications only. Every time someone updates a publication, a new version is built. All changes to all publications are logged. Every document is pre-approved. No reason to mail someone since it is assumed that you edit your own pages only. This is the workflow you should use if you want to allow your users to have their own set of pages they can manage. If for instance you have a home-garden site and want you users to present their gardens on your site then do as follows:

  1. Create a publication type named "Gardens" (or similar) and add the fields you need.

  2. Assign the "MyWiki" workflow to this publication type.

  3. Check (enable) the access to editing of own pages.

  4. Make sure your users have "author" access to this publication type. This can be done with a permission line in PostNuke like this: "YourGroup | pagesetter:: | T:: | Edit" (where T = type ID).

With this setup your users should be able to create new pages as well as edit their own pages only. You need to give them a URL to the "edit publication" feature (see the linking section).

Chapter 12. Customisation

Style Sheets

The Guppy input forms CSS files are located in pagesetter/guppy/themes/YourThemeName/style.css. If you do not write your own then the file pagesetter/guppy/themes/guppy/style.css will be used.

Input Forms Layout

Pagesetter does not only let you define your own publication types and their presentation. It also lets you define both workflows, as described in the previous chapter, as well as the input forms used for editing your publications.

Different input form layouts can in fact be associated with different workflow states. To do so you must create an XML layout file with a name related to the workflow name and place it in a publication type specific directory.

The filename must be made up like <StateName>/FormLayout.xml and be placed in a directory named publications/<PubTypeFormName>. The "PubTypeFormName" is the "Form name" field of the publication type setup. The filename used for a new instance of a publication (yet without a workflow state associated with it) is newFormLayout.xml.

So to specify the form layout for the "waiting" state of a "PN-News" publication you would have to create a file named publications/PN-News/waitingFormLayout.xml. The structure of the layout XML file is described in the Guppy Development manual located in the same directory as this manual. The Guppy manual is meant to be a complete Guppy manual, but for customizing input forms layout, you only need to read the chapter on "Form Layout"—the rest can be ignored.

In the examples directory you can find a newFormLayout.xml example file to use for standard PN-News items. Just copy it to publications/PN-News (you probably need to create the layout directory yourself).

Input plugins

The Guppy forms system allows the administrator to develop new simple types of inputs. Currently the "datetime", "e-mail", and "url" inputs are made this way. See the Guppy manual for further information.

HTMLArea Editor

The editor can be customized with a callback JavaScript file placed in the publication type specific directory. The filename must be named editorsetup.js and be placed in a directory named publications/<PubTypeFormName>. For instance publications/PN-News/editorsetup.js.

In the callback file you can place two callback functions named HTMLAreaConfigSetup and HTMLAreaEditorSetup. The first one will be called when the configuration object has been loaded by Pagesetter (and passed the config object). The second one will be called when the editor object has been created (and passed that object).

Example 12.1. Adding a CSS class selector to HTMLArea's right-click context menu.

  // Load various plugins on load of the setup script
HTMLArea.loadPlugin("ContextMenu");
HTMLArea.loadPlugin("CSS");


  // This function is called (if it exists) after the editor 
  // configuration is created, but before the editor 
  // itself is created
function HTMLAreaConfigSetup(config)
{
    // Here you can call config.registerButton, change the toolbar, 
    // and much more ... see HTMLArea's own documentation
}


  // This is called with the editor right after 
  // it has been created
function HTMLAreaEditorSetup(editor)
{
    // Register the plugins
  editor.registerPlugin(ContextMenu);
  editor.registerPlugin(CSS, { combos: [{label:"CSS", 
                               options:{a:"classA", b:"classB"}}] } );
}

Internal templates

Some of the internal windows are rendered via pnRender—especially the error messages that are displayed via pagesetter_error.html. This means you can redesign the layout of the error messages.

Post Submit Handler

In some cases it might be usefull to modify the data submitted after editing a publication. This can be accomplished with the addition of a single extra custom workflow operation. Please check the workflow manual for further instructions (it is not possible to modify/add data before opening the editor).

Appendix

Appendix A. Useful Hints

It is our hope that this manual some day becomes available on the internet with the ability to comment on the individual chapters. This appendix is meant for collecting all those comments that does not fit elsewhere.

Appendix B. Credits

  • Thanks to Tony Jensen, Jörg Napp, Sebastian Schürmann, Thomas Smiatek, Claus Parkhoi for lots of ideas, help, and code snippets.
  • Thanks to Axel Guckelsberger for conversion of the original plain HTML manual to DocBook XML.
  • Many thanks to the guys at interactivetools.com who made the HTML editor "htmlArea"—it's a very cool product.
  • Also lots of thanks to the guys at smarty.php.net who made the Smarty templating engine.
  • Thanks goes also to Mihai Bazon who made the really nice date picker.
  • I have of course also been looking at ContentExpress and PagEd as well as scores of other programs for inspiration.

GNU Free Documentation License

Version 1.2, November 2002

Free Software Foundation, Inc.
 59 Temple Place, Suite 330,
 Boston,
 MA
 02111-1307
 USA
 

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Version 1.2, November 2002

PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

GNU FDL Modification Conditions

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
  4. Preserve all the copyright notices of the Document.
  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
  8. Include an unaltered copy of this License.
  9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
  11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
  13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
  14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
  15. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Sample Invariant Sections list

Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:

Sample Invariant Sections list

with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.