XSL Architecture

PhPeace uses XSL for templates to generate (X)HTML pages, RSS feeds and email text messages.
XSL is a standard by W3C; please refer to the online specs and documentation for further details about its syntax. In this page you can find a summary explanation of the XSL architecture to help you orientate among the many different templates.

PhPeace is under continuous development, with an extremely short development cycle. New versions are released on a weekly basis, and they may contain changes in terms of functionalities that will impact the UI.
In order to allow for this continuous development and bug-fixing, a set of XSL is centrally managed and updated with every release. In this way you can receive all the relevant updates to the UI.

You are free to fork these central XSLs and fully customize them, but keep in mind that in this way you will not receive any fix or update. Furthermore, this is not necessary as you already have, as explained below, a customizable architecture that lets you fully control the UI.

Styles

A style is a set of XSL (and CSS, not discussed in this page), which import the default XSLs and allow you to fully override the existing templates. Each topic (a website in the portal managed by PhPeace) has its own style. Styles can also be shared across different topics. You can create as many styles as you want. and edit all their XSLs; this approach gives you full control and customization of the UI for each topic.

Pagetypes

A pagetype in PhPeace is a webpage with a specific identity in the structure of the portal, in terms of content and layout. Its content is defined and managed by the UI engine, and if necessary you can add some custom content (by the so-called features).
Content is output as XML, and transformed via XSL. Each pagetype uses a XSL style sheet as its template.

PhPeace defines three categories of pagetypes

• global pagetypes are used for generic pages of the portal which are generally not going to be customized; they provide general-purpose content, such as the portal homepage, the sitemap, the list of the feeds, and so on.
• specific pagetypes are the templates used by a topic; a topic is a website in the portal, with its own set of users, content, possibly domain name and graphic layout. A topic is associated to a style, i.e. a set of XSL that can be fully customized. A set of specific XSLs is centrally maintained, and a style is a full customizable copy of this set.
• modules pagetypes are equivalent to the specific ones, but they are part of an extensible architecture which gives space to future modules and enhancements of the software. Again a set of these XSLs is centrally maintained, and a style is a full customizable copy of this set.

The following diagram represent the XSL architecture of PhPeace

Legend

• "Central" box (grey backgorund) includes the XSL centrally manage and updated, unless forked
• "Style" box (pale blue background) includes the XSL created as part of a style, fully customizable
• The black arrow lines represent xsl:include statements
• The blue thick arrow lines represent xsl:import statements

---

XSL transformation for (X)HTML generation begins with the orange boxes, either global or specific pagetypes.

Each template will include and import some other templates, as shown in the diagram. Keep in mind that you can override a XSL template only if it's imported, not if it's included. However, note that you're always importing the upstream XSLs, so that you can always override their templates.

Here is an explanation of the purpose of the various templates.

common.xsl

Contains all major templates, common across the various pagetypes. You should never fork the central common.xsl. If you are in a generic pagetype, you can override its templates. If you're in a style, you have an empty common.xsl to play with. If you find out that there's something wrong, or that you would prefer a different organization of the XSL templates in the common.xsl, please let us know and we will evaluate your suggestions.

root.xsl

The main webpage definition is isolated in this template, so that you can break the main structure without forking the common.xsl. In case you want to redefine the webpages layout at portal level, you can fork the central root.xsl. This is fine, as far as you check regularly with the upstream root.xsl to see if any major changes have been introduced. Alternatively, you can always customize the webpage layout for your styles.
root.xsl gives you a hook to redefine completely the XSL architecture, as you can call different templates, that you can then implement in your custom templates, and use the ones of the main distribution only when necessary.

tools.xsl

This stylesheet include some templates that you probably will never need to worry about. They're isolated in this template for better maintenance in the unlikely case you fork the central common.xsl.

common_global.xsl

This is an empty stylesheets in the case you want to share some templates among the generic pagetypes, but not with the specific ones (otherwise you would customize your central root.xsl). This may be useful mainly for performance or maintenance reasons.

As you can see, at a style level, the specific templates include common.xsl, which further includes a custom root.xsl and tools.xsl, mirroring the structure of the central ones. While the distinction between common.xsl, root.xsl and tools.xsl is useful at central level, is not that important at style level. You may want to group all your custom templates in your common.xsl, or split them across the other templates. This is fine, as common.xsl, root.xsl and tools.xsl are all equivalent from an inclusion point of view.

Here follows a list of all pagetypes (soon more information will be added for each of them)

Global pagetypes

• homepage.xsl
• rss.xsl
• map.xsl
• feeds.xsl
• gallery_group.xsl
• user.xsl
• gnewsletter.xsl

Specific pagetypes

• topic_home.xsl
• subtopic.xsl
• article.xsl
• article_box.xsl
• events.xsl
• quotes.xsl
• campaign.xsl
• forum.xsl
• poll.xsl
• gallery_item.xsl
• people.xsl
• newsletter.xsl
• geosearch.xsl
• print.xsl
• send_friend.xsl
• image_zoom.xsl
• error404.xsl
• search.xsl
• random_item.xsl
• comments.xsl

Modules

• lists.xsl
• books.xsl
• orgs.xsl

Filesystem

All XSLs are stored in a dedicated directory under the PhPeace installation, which is not directly reachable from the the public website. The "Central" XSLs are in the directory xsl/0. All the styles are stored in different directories, identified with the style ID (xsl/1, xsl/2 and so on).

Whenever you edit an XSL from the admin interface, the XSL file is rewritten on disk, and it is immediately used by the transformation of the live site. A copy is also stored in the database, for versioning purposes. In case you submit a broken XSL, the file is not updated (to avoid breaking the live transformation) but it's still stored in the database, to keep your changes and let you fix them.

For backup purposes, the database dump will include a copy of all XSLs. However, given their small size, you are advised to backup the XSL files directly, which will give you also more control on selective restores.

If you are about to implement major changes to a set of XSL, the best approach is to create a different style as a clone of the existing one (this will copy all its XSLs and CSSs), and then work on this new style to avoid breaking the live site. You can always preview the content with the new style and apply it only when you're happy with your changes.

You should never edit directly the XSL files on the file system, unless you really know what ' you're doing, because this bypasses the database versioning.

XSL Extensions and Custom XSL

The XSL architecture is expandable with extensions, i.e. pagetypes that can by customized by styles, or custom XSLs, which are a one-off' stylesheet which could be handy to isolate some very complex code.