Publishing
This section explains how PageSeeder can output to different formats and applications.
Overview
Some publishing situations need multiple processing stages in order for resolved values to be available for other parts of the process.
This is similar to the way a conventional typesetting app must first compose the individual pages, then insert page numbers in the Table of Contents (ToC) then adjust all page numbers based on how many pages the fully resolved ToC is.
Examples include:
- Creating the navigation and content of a website.
- Transforming, then generating pages and cross-reference values for PDF.
Multi-stage, batch processing is available through the PageSeeder publish function. Using the PageSeeder Ant API, Publish leverages Apache Ant , an open source technology that is available on most operating systems.
To get the most out of Publish, needs an understanding of Ant. While there are many sources of Ant reference and learning material, the focus of this site is how PageSeeder interacts with Ant.
More information on batch processing is available through publish scripts. To modify the user interface or configure different options, see <publishing>. For example publish scripts, see PSML Ant scripts.
Publish Engine components
Publish Engine is a Java servlet that communicates with the PageSeeder Core using HTTP. The publish script is an Apache Ant build script.
After the script is instantiated, the Publish Control passes a request to the Publish Engine for the following actions:
- query – the engine processes the script, returning a list of user-selectable options, such as the following:
- generate Table of Contents.
- use hi-resolution images.
- publish – executes the script and selected options.
- check – displays the status of selected publishing task.
- cancel – cancel the current task.
Depending on the actions initiated, the response is passed back to the Publish Control, processed by XSLT and rendered on the user screen. The architecture is outlined in the following diagram:
Publish parameters
These parameters are accessed in ANT using the Task config.
The following table lists the parameters passed to the Publish Ant Script:
| Parameter | Description | Example |
|---|---|---|
| ps-jsessionid | The user’s jsessionid in PageSeeder | |
| ps-host | The webSiteAddress from global.properties | |
| ps-port | The webSitePort from global.properties | |
| ps-servletPrefix | The servletPrefix from global.properties | |
| ps-sitePrefix | The sitePrefix from global.properties | |
| ps-groupId | id of group initiating the publish | 12 |
| ps-groupName | Name of group initiating the publish | acme-demo |
| ps-groupFolder | Path of default group folder | /ps/acme/demo |
| ps-groupFolderNoPrefix | Path of default group folder with no site prefix | /acme/demo |
| ps-groupHost | Host of default group folder | mycompany.com |
| ps-groupPort | Port of default group folder | 80 |
| ps-groupTemplate | Template for group (or default group if URI) | acme |
| ps-globalTemplate | globalTemplate name from global.properties | acmedefault |
| ps-style-owner | Template for group (or default group if URI). DEPRECATED in v5.99 use ps-groupTemplate instead. | acme |
| ps-customFolder | globalTemplate name from global.properties. DEPRECATED in v5.99 use ps-globalTemplate instead. | acmedefault |
| ps-working | Path to local unique working folder or this group/document | |
| ps-workingRoot | Path to root for all local working folders | |
| ps-documentsRoot | Path to PageSeeder documents folder only if Publish Engine is installed on PageSeeder server) | |
| ps-webRoot | Path to the root for result files (see ps-sessionfolder) | |
| ps-engineUrl | The external URL used to contact the Publish Engine | http://mycompany.com/ps/publisher |
| ps-sessionfolder | A unique folder name for the current PS user session to copy result files to | ${ps-webRoot}/session/${ps-sessionfolder} |
| ps-username | username of the current user | jsmith |
| ps-userId | ID of the current user | 123 |
| ps-userFirstname | Given name of the current user | John |
| ps-userSurname | Family name of the current user | Smith |
| ps-userToken | The access token for the current user (only if script was started using an access token) |
Following are the parameters for a Document being published. These are not applicable for a Group or Batch being published or a document in the Loading Zone:
| Parameter | Description | Example |
|---|---|---|
| ps-uriId | URI id | 123 |
| ps-uriScheme | URI scheme | http |
| ps-uriHost | URI host | mycompany.com |
| ps-uriPort | URI port | 80 |
| ps-uriPath | URI path | /ps/acme/demo/minutes/2006-12-08.xml |
| ps-uriPathNoPrefix | URI path without prefix | /acme/minutes/demo/2006-12-08.xml |
| ps-uriPathNoGroup | URI path without group prefix | /minutes/demo/2006-12-08.xml |
| ps-uriFolder | URI folder | /ps/acme/demo/minutes |
| ps-uriFolderNoPrefix | URI folder with /ps prefix | /acme/demo/minutes |
| ps-uriFolderNoGroup | URI folder without group prefix | /minutes |
| ps-uriFilename | Filename | 2006-12-08.xml |
| ps-uriFilenameNoExt | Filename without extension | 2006-12-08 |
| ps-uriExtension | File extension | xml |
| ps-uriDocumentId | URI docid (optional) | mydoc1 |
| ps-uriPublicationId | The ID of the publication that URI is the root of (optional) | mypub1 |
| ps-uriPublicationType | The type of the publication that URI is the root of (optional) | report |
| ps-style-config | URI document type | definition |
The following parameters are for processing a Batch of documents (requires PageSeeder v5.98 or higher):
| Parameter | Description | Example |
|---|---|---|
| ps-batchIds | A comma-separated list of URI IDs in the batch | 123,456,789 |
| ps-searchQuestion | The search question used to select the batch IDs from (optional) | green |
| ps-searchQuestionFields | The search question fields used to select the batch IDs from (optional) | pstitle,pscontent,psfilename,psdocid,psid |
| ps-searchFilters | The search filters used to select the batch IDs from (optional) | psdocumenttype:product,pslabel:simple |
| ps-searchRanges | The search ranges used to select the batch IDs from (optional) | psproperty-title:[A;C},ranges=psxrefcount:{50;] |
The following parameters are for processing a Document in the Loading Zone:
| Parameter | Description | Example |
|---|---|---|
| ps-uploadPath | Document path | /minutes/2006-12-08.xml |
| ps-uploadFolder | Document folder | /minutes |
| ps-uploadFilename | Document filename | 2006-12-08.psml |
| ps-uploadFilenameNoExt | Filename without extension | 2006-12-08 |
| ps-uploadExtension | File extension | xml |
| ps-uploadConfirmed | If script is run before displaying the Upload confirmation, the value is false, otherwise it’s true. |
Publish messages
Generally all messages output from an Ant script are logged by PageSeeder, but the following special Ant messages are also recognized:
<echoxml><progress percent="[n]" /></echoxml>
- where n is an integer from 0 to 100, displays progress on the Publish Page (not logged by PageSeeder).
<echoxml><displayUriPath>[url]</displayUriPath></echoxml>
- where url is a URL beginning with /, http:// or https://, displays the content of [url]?t=[timestamp] when the Publish is complete.
<echoxml><previewPath>[path]</previewPath></echoxml>
- which displays the PSML at this path on the Publish Engine as HTML where path is to start with ‘/session/${ps-sessionfolder}’ (PageSeeder does the translation to HTML). Only supported for upload preview ANT scripts using
target/@previewname.
<echoxml><publisherPath>[path]</publisherPath></echoxml>
- which displays the file at this path on the Publish Engine where path is to start with ‘/session/${ps-sessionfolder}’. If using a Publish Engine on a different PageSeeder server, this can be used to proxy the request using the local PageSeeder URL; however, it is more efficient to use the direct Publish Engine URL with
<displayUriPath>.
<echoxml><downloadLink>[url]</downloadLink></echoxml>
- where url is a URL beginning with /, http:// or https://, displays a link to [url] when the Publish is complete.
As of PageSeeder v6 you can't access documents using path info, for example in <displayUriPath> and <downloadLink>. In v6 use the path parameter (or docPath in v5 or v6). For example instead of /ps/acme/specs/my.psml use /ps/uri?path=/ps/acme/specs/my.psml
PageSeeder Ant tasks
The PageSeeder External API defines a few Ant tasks that are useful to connect and interact with the PageSeeder Server. For details, see Ant API and Using Ant.