Advanced

Advanced topics

Customize the user interface

For information regarding the presentation of specific document types, see PSML document style.

There are several ways to customize PageSeeder's user interface and this document outlines some of the options.

For developer tutorials on this topic, click User Interface Customizations.

For further technical information, see Understanding the Layout Manager or Layout Manager Config 1.4.

We no longer recommend customizing the PageSeeder user interface, but if it is a MUST, find what is needed here.

Warning!

Several key components that used to make up the layout API are being deprecated or obsoleted. If the layout has been customized layout, make sure to check the release notes before upgrading !

Layout API

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 are to help developers avoid implementing customizations that are problematic to upgrade.

Note

In the steps below page id can be substituted for block id or dialog id.

  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 may 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 will automatically load 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, e.g. 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
    default
    Perspective=xyz

    This approach will keep the standard perspective accessible. Making the Standard Perspective current can be done by simply 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 custom folder in Template Properties (e.g. customFolder=mystyle).

Using CSS

For information on creating a Custom Style CSS see PageSeeder CSS.   To install a custom CSS for a particular Project, follow the steps below:

Create a [project] folder under:

\pageseeder\webapp\woconfig

Copy the CSS and images folders to:

woconfig\[project]\layout\css

 and

woconfig\[project]\layout\images

Note

Only the CSS/image files that are to be customized should be copied or created. It is good practice to import the original PageSeeder CSS file and then only override the desired CSS styles.

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 the steps below:

Edit the

\WEB-INF\config\template.properties

and add:

customFolder=[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 simple 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> tag is present, it will override 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 will be used.
  • New <block>, <blockset>, <tree> or <page> components can be defined.
  • Any component (block, blockset, tree or page) specified in the custom configuration file will override 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 tag (<servlet />) will force "no servlet definition".
    • the <script> tag is treated the same way as the servlet tag:. For "no script",  use <script />.
    • the <block-ref> and <blockset-ref> tags should be included in the component. The default tags are never used.
    • if a <tree-ref> tag 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.

Created on , last edited on