[fleXive] CMS 0.6 Reference Documentation

Abstract

[fleXive] CMS is a Content Management System based on Java Enterprise Edition 5 and JavaServer Faces 1.2.

Its main features include:

  • XHTML-based templating with JSF
  • Integration of business logic via JSF and EJB
  • Out-of-the-box functionality for multilanguage websites, pretty URLs, fine-grained security, and much more.
  • Front-end editing for immediate feedback.


1. Getting started
Download [fleXive] CMS
Completing the installation
Accessing the CMS
First Steps
Creating new pages
Page editing
Publishing the changes
Outlook
2. Concepts
Page organization
Page content
Templating
Publishing or: Edit and Live
User groups
Putting it all together
3. Templating
Value rendering components
<fx:content>
<cms:image>
<cms:value>
Templating components
<cms:applyTemplate>
<cms:renderChildren>
<cms:navigation>
<cms:languageSelect>
Menu components
<cms:childMenu>
<cms:loginMenu>
<cms:navigationMenu>
<cms:pageContent>
JSF-EL functions
URL-related functions
Query functions
Navigation and templating
String and data handling
4. Recipes
Navigation
Teasers
URL rewriting
Website resources like images and stylesheets
Multilanguage websites
5. Deployment
Deploying the CMS to an application server
6. Custom development
7. Links
8. Things still missing

To install [fleXive] CMS on your machine, you need to have Java installed (version 5 or later). You can download the current version of Java from java.sun.com.

Download and run the installer from the download page. If your operating system does not launch Java archives (JARs) automatically, open a command line and type java -jar [path-to-installer.jar] to launch the installer.

The installer will prepare a fully functional installation on your local machine. After the installation process is finished, start the CMS server using the application menu shortcut or manually with the start.sh/start.bat scripts in the root installation directory.

When the server is running and you first access the CMS through the browser (http://localhost:8080), you are redirected to the [fleXive] backend. Complete the installation by logging in with the default superuser credentials, supervisor/supervisor, and wait a few moments until the initialization is complete.

If something went wrong, please stop by in our forum.

After the initialization was completed, you can access the actual CMS website on http://localhost:8080. By default, there are three example CMS users available:

  • cms-author/cms-author can create pages,

  • cms-editor/cms-editor can modify all contents and publish changes, and

  • cms-admin/cms-admin can edit the page templates.

To login, click on the "Login" link in the upper right corner or open http://localhost:8080/admin/login.xhtml. Use the default admin user and password to login (cms-admin/cms-admin).

After successful login the CMS control bar appears above the page:

Here you can perform the common tasks for managing the web site:

  • Edit allows you to edit the current page,

  • New Page is for creating new pages,

  • Templates allows you to edit and assign the templates of the current page,

  • Actions is for publishing changes from the edit mode to the live website,

  • and the select box in the middle provides a sitemap as quick navigation. On the far right the current user is displayed, as well as the current view settings:

    Templates: edit and Contents: edit indicate that the "edit" versions of templates and contents are shown. You can toggle both settings independently to preview the content changes with the live template settings, or the live contents with the anticipated template changes. For now, leave both settings on "edit", this is by far the most common mode unless you are heavily editing both contents and templates.

What are those funny blobs near the reference our new page? Clicking on them reveals a context menu that can be used to move the page around (in the navigation pane) or to edit the page content (in the content pane). The color indicates the publishing state of the page:

  • green pages are visible on the website and have no unpublished changes,
  • orange pages do have unpublished changes, but may already be visible on the website,
  • and gray pages are new and do not exist on the public website yet (logically, the orange blob in the image above should be gray, it's an implementation quirk of the current CMS version).

To check this, click on the "Contents: edit" link in the upper right corner. Now you see the website as an anonymous visitor would see it currently: our new page has not been published, thus it is not visible to anyone but other CMS users. Click on "Contents: live" again to switch back to edit mode.

Now, let's fill our new page with content. Navigate to the new page by clicking on the link. The page renders OK, but is devoid of any content:

To change this, click on the Edit button in the upper left corner. This opens the page editor in an overlay popup window:

The amount of buttons and inputs may seem intimidating at first, but it's actually pretty simple:

  • The Templates box is a group of properties that determines the templates to be used for this page.

  • Path name and title are the page parameters you set when creating the page.

  • Node reference is a CMS-internal setting (it should not be visible actually), please ignore it for now.

Each property has a few control buttons on the left: The first opens a context-sensitive menu for this node, the arrows can be used to change the property position (irrelevant for our current page template), and the plus/minus symbols add an additional line for the field (if possible) or remove the field (unless it is mandatory).

To add page content, we have to create a property that is not yet visible. To do this, click on a context menu icon on the far left:

You get a selection of properties that can be added to the current instance:

Since we want to add text content, select Paragraph and click Insert selected assignments. This creates a new paragraph with the properties that are defined by our page type:

In the default page type, the page content is described by paragraphs with a title, a HTML text body, and an optional image. The text fields are multilingual, so you can use a single content instance for different languages. Enter some text (you can leave the image property empty for now) and click the Save content button on the bottom of the page. The content instance is saved and the paragraph should be rendered immediately.

Pages are [fleXive] content instances derived from a common type, CMS_PAGE. CMS_PAGE defines the bare minimum of properties that a [fleXive] CMS page has:

Path name

The unique name for the URI of this page.

Title

The (possibly localized) title of this page that is used for building a site map or navigation panel with cms:navigation and can also be used for the HTML <title> element.

Page template

The template that is used for rendering this page as a standalone frontend page (i.e. with complete HTML headers and so on). It can use content templates to defer the rendering of the page content to a separate template.

Content template
The page template uses the content template to render the actual page content.
Teaser template

The template to be used for rendering a teaser (short preview of the content for embeddeding in another page) for this page.

Since every website has different requirements on how its content is organized, [fleXive] CMS does not impose a predefined structure for page contents.

Instead, the user controls both data structures and display templates, making it a very versatile site generation tool similar to a Structured Wiki.

An example is the CMS_BASIC_PAGE type that is used for the packaged example website. In addition to the properties listed above, this type defines the following properties:

Teaser/Title, Teaser/Text

The teaser definition. Briefly describes this content when listed on another page.

Paragraph/Title, Paragraph/Text, Paragraph/Image

A list of paragraphs that make up the page content. Each paragraph can contain a title, HTML text, and an image.

Templates determine how a page is rendered to the user. Usually the output is some sort of HTML, but you can also create templates for different output formats like plain text or binary formats like PDF.

Templating is based on the Facelets XHTML templating language for JavaServer Faces 1.2. A basic template could look like this:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://java.sun.com/jsf/facelets"
      xmlns:fx="http://www.flexive.com/jsf/core"
      xmlns:cms="http://www.flexive.com/jsf/cms">

<fx:content var="page" pk="#{fxPageBean.pagePK}">
    <head>
        <title>#{page.title}</title>
    </head>

    <body>
        <h1>
            <cms:value value="#{page.title}"/>
        </h1>

        <fx:children var="paragraph" value="#{page}" property="paragraph">
            <ui:fragment rendered="#{not empty paragraph.title}">
                <h2 class="title">
                    <cms:value value="#{paragraph.title}"/>
                </h2>
            </ui:fragment>

            <p class="paragraph">
                <cms:image value="#{paragraph.image}"/>
                <cms:value value="#{paragraph.text}"/>
            </p>
        </fx:children>

    </body>

</fx:content>
</html>

For someone familiar with JSF, this template contains no surprises. The CMS-specific part is the <fx:content> tag that provides the all page properties in the variable #{page}. <cms:value> is used to render the title. Then the paragraph(s) of the page are rendered using the <fx:children> component that iterates over all paragraphs of the page.

This component is vital for including other contents into the current page. In its current form, it only supports rendering the contents stored in a subfolder of the page (including the page itself, i.e. all page contents linked under the current page), or from an absolute folder reference.

There are two modes of operation:

  • When the template attribute is set, all contents that contain a template reference under this path are rendered using the corresponding template. I.e. the contents themselves control how they are rendered, the caller only determines which logical template class is selected (teaser templates).

  • When the type attribute is set, the template is provided in the tag body.

The template can use the following variables to access the content to be rendered:

content

The node content, as exposed by fx:content .

path
The (absolute) page path.
nodeId
The (tree) node ID, for custom lookup functions.

Render a link menu for choosing the language of the page.

Template parameters are specified in the tag body with <ui:define>.

item

The template for a language item. The language variable contains the language to be rendered (of type FxLanguage).

By default, this renders plain text links for toggling the language. You can use the fx:urlWithLocale JSF-EL function, for example (taken from the default template):

<cms:languageSelect languages="en,de">
    <ui:define name="item">
        <c:if test="#{language.iso2digit eq fxPageBean.languageCode}">
            <!-- Current language -->
            <strong>#{language.label}</strong>
        </c:if>
        <c:if test="#{language.iso2digit ne fxPageBean.languageCode}">
            <!-- Render link to the current page in the given language -->
            <a href="#{fx:urlWithLocale(language.iso2digit, fxPageBean.treePath)}">#{language.label}</a>
        </c:if>
    </ui:define>
</cms:languageSelect>

[fleXive] CMS offers static helper functions that can be used in page templates, e.g. for converting strings to uppercase or for creating absolute page URLs.

Objective: store website resources like images or stylesheets in the CMS.

[fleXive] CMS provides two special folders, /files and /resources, for dealing with website resources:

  • /files acts as a simple, path-based store for binary objects like images. Anything that is put there can be reached through the tree path that is visible in the backend.

  • /resources is a collection of text-based resources like stylesheets and scripts. These resources are actually normal CMS pages with custom templates that set the correct content types, e.g. text/css for CSS files.

In the screenshot above, the resources can be reached from the website with the following paths:

  • /files/flexive.jpg

  • /resources/default.css

  • /resources/perfect-3col-liquid.css

  • /resources/perfect-2col-liquid.css

To create a new content in one of these folders, right-click the folder, select Create content... and then the appropriate content type:

  • For image formats like PNG or JPG, select "Image".

  • For other binary formats like PDF files select "Document".

  • For text resources like CSS or JS files, select "CMS Resource". You then have to set the page template according to the resource type, like "Resource: CSS" or "Resource: Javascript".

These resource can be reached through the URI that is displayed in the backend when node paths are displayed (activate the ":/" icon in the content tree menu). In the image above, this mode is not activated. You are viewing node paths if the page root node has the name "flexiveCMS" instead of the page title ("Welcome to...").

Note that you have to activate the resources for them to be available on the public website. To do this, right-click the resource and choose Activate. You can also activate the whole resource folder by right-clicking the folder and choosing Activate subtree.

Using the [fleXive] content repository enables you to build multilanguage websites very quickly. For an example, check the demo website that the installer creates.

The demo website sets up a URL pattern that matches all URLs starting with /en and /de to English and German, respectively. This mapping is created with the following script that can be executed in the backend script console:

EJBLookup.configurationEngine.put(com.flexive.cms.shared.CMSConst.REWRITE_RULES,
'''<?xml version="1.0" encoding="utf-8"?>
<urlrewrite>

    <!--
        URL-based website locale: map /en to English page, /de to  German,
        everything else uses the browser language (if possible)
    -->
    <rule>
        <from>^/(de|en)/(.*)?</from>
        <to>/$2</to>
        <set name="languageCode">$1</set>
    </rule>

    <rule>
        <from>.*</from>
        <!-- Set CMS language URL format, on this demo website this is the same for all pages -->
        <set name="cmsEncodeLanguageFormat">/{languageCode}{url}</set>
    </rule>

</urlrewrite>
''')

You can use the <cms:languageSelect> component to render a menu for choosing the locale of the current page.

In the rewrite rules, you have to create a URL mapping for localized URLs that sets the correct language. [fleXive] then uses this language for the rest of the request.

You also have to specify the link format in the request attribute cmsEncodeLanguageFormat. Any URL rendered with #{fx:url(path)} on the current page will then use this format and encode the current page locale accordingly (in this case, the format is set for all URLs to enable cms:languageSelect on URLs without locale).

Using the installer gets you started with little effort, but it is not advisable to turn this version directly into a production instance.

The installer uses Jetty, OpenEJB, and H2. While all of them are mature technologies, we we recommend using a supported application server and a scalable, standalone database system. JBoss with MySQL or PostgreSQL is usually a fine and free combination. The website itself can be migrated between databases with the import/export tools in the backend .

For detailed installation instructions please refer to the [fleXive] installation guide .

While the CMS is a fine out-of-the-box solution for relatively static websites, one can only go so far without writing custom business logic.

Maven WAR overlays provide a way to override or extend the CMS web application's configuration. The existing CMS web application, flexive-cms-war, is used as an overlay where existing configuration files can be replaced (e.g. web.xml for adding servlets or filters).

The easiest way to integrate custom logic is by creating a Maven JAR module and implementing one or more custom JSF managed beans. These can be initialized with an additional faces-config.xml that will be discovered by JSF when the JAR file is added to the EAR.

The JAR file with custom business logic can then be added to a stock CMS EAR file. To achieve fully automatic packaging a new EAR Maven module similar to flexive-cms-ear, but including the additional dependency, must be created. This is also necessary to include additional EJB modules, which have to be listed in the EAR's application.xml.

The CMS artifacts are available in our Maven repository under http://repo.flexive.org/maven2/com/flexive/cms.

As of today, [fleXive] CMS is not yet a complete product. However, it is stable enough that we use it for our own projects, and it should serve well as a base technology for a wider range of websites. Among the things still missing are:

  • Referencing pages from contents (dynamic link replacement). (CMS-2)

  • Frontend editing of resources (images, stylesheets, etc.). (CMS-3)

  • User-defined URL mappings/routing.
  • User-defined tags.
  • Tree-based templating (i.e. the position in the page tree determines the template).
  • Inline editing (partially implemented)
  • Multiple websites (i.e. mapping domains to page tree root nodes). You can already serve multiple websites from a single server using [fleXive] divisions, but this prevents any data sharing.
  • WebDAV-based template and content editing (sort of works, but not extensively tested).
  • A Maven quickstart archetype for a customized CMS application. (CMS-4)

  • JSF 2 support.
  • Caching of tree-based components (e.g. navigation, path lookups, etc.).
  • Page fragment caching.
  • ...and more. Contact us if you have suggestions that are not listed here.