Customize the user interface

For information regarding the presentation of specific document types, see PSML document styles (CSS) or Organization customization.

PageSeeder UI components (pages, blocks & dialogs) are defined in the layout config. They are also powered by servlets and generators.

Additionally, each component is associated with a set of XSLT, CSS and JavaScript to generate the HTML structure, the style, and behavior of the component.

Developer guidelines

Following are recommended guidelines for creating user interface customizations. The purpose of these guidelines is to help developers avoid implementing customizations that are problematic to upgrade.

1. In Layout/config.xml, create new page ids; do not override existing page ids.
2. To override an existing URL, use a new page id but copy the <url> element(s) from the existing page.
3. Create new XSLT for the new page ids, do not override existing XSLT. Definitions, JavaScript and CSS can change with each PageSeeder release; this might create incompatibilities with customizations that have overridden PageSeeder system files.
4. Copy XSLT code you need from default; do not import XSLT from default. Importing XSLT can also create incompatibilities with future releases.
5. If a page/block/dialog requires Javascript or CSS, save that code in separate files with the same name as the id of the page i.e.:
   woconfig/[project]/layout/script/[page|block|dialog]/[page id].js
woconfig/[project]/layout/css/[page|block|dialog]/[page id].css
   This automatically loads those files with your customization.
6. When removing functionality from the UI, create the customizations as a perspective (previously known as Style View). The perspective, for example, mystyle.xyz, can be set as the default by adding/creating the following file:
   template/[project]/Config/project.properties
   
   with the following statements:
   perspectives=xyz
defaultPerspective=xyz
   
   This approach keeps the standard perspective accessible. Making the Standard Perspective current can be done by adding the following parameter to any standard PageSeeder URL: ps-perspective=standard
7. If a layout customization is intended for the PageSeeder server instead of a Project, set it as the globalTemplate in global properties (e.g. globalTemplate=mystyle).

Using CSS

For information on creating a Custom Style CSS. To install a custom CSS for a particular Project, complete the following steps:

Create a [project] folder under:

\pageseeder\webapp\woconfig

Copy the CSS and images folders to:

woconfig\[project]\layout\css

 and

woconfig\[project]\layout\images

Custom CSS as the default

To install a Custom CSS as the PageSeeder Server default for all Groups, first install it for a project as described above and then follow these steps:

Edit the

\WEB-INF\config\global.properties

and add:

globalTemplate=[project]

Restart the PageSeeder Service and the new style should be the default.

Customizing the config.xml

PageSeeder’s Understanding the Layout Manager provides a powerful mechanism for customizing the User Interface.

To view a customization, there are two Layout Tools in the Developer Tools.

Following are straightforward examples of how to use the config.xml file.

The config.xml file can be overridden for a specific perspective. Doing so requires the configuration file to be valid against the layout-config-override DTD and located in the following location:

template/[project]/Layout/config.xml

The override DTD is essentially the same as the default DTD except that it enforces constraints for overriding, which are:

• If the <navigation> element is present, it overrides the default navigation. If a <section> is specified but left empty and there is a default section with the same title, the default <subsection> elements are used.
• New <block>, <blockset>, <tree> or <page> components can be defined.
• Any component (block, blockset, tree or page) specified in the custom configuration file overrides the default component with the same ID. This is not recommended, it is better to create new components.
  Overriding an existing component follows these rules:
• Existing <url> patterns are ignored when a override url is specified, otherwise the default patterns are used.
• Default <servlet> elements are ignored where a corresponding servlet definition is present in the override. An empty servlet element (<servlet />) forces “no servlet definition”.
• The <script> element is treated the same way as the servlet element:. For “no script”,  use <script />.
• The <block-ref> and <blockset-ref> elements should be included in the component. The default elements are never used.
• If a <tree-ref> element is present, all default tree-ref are ignored, otherwise the default definitions are used.
• Default <url-parameter> elements are ignored for any overrides with the same name. 

Using XSLT

PageSeeder uses XSLT stylesheets to generate the HTML interface from the underlying XLink data. These are stored in the folder structure under:

\WEB-INF\template\default\Layout

To customize the stylesheets, the .xsl files must be stored in the same folder structure but with the project name as a qualifier:

\WEB-INF\template\[project]\Layout

The XSLT stylesheets can be modified directly on the server using the View Bundle page in the Developer tools.