%cms_entities; ]> &flexivecms; 0.5 Reference Documentation Daniel Lichtenberger daniel.lichtenberger@flexive.com 2009-2010 UCS - unique computing solutions gmbh &flexivecms; is a Content Management System based on &jee5; and &jsf12;. 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. Getting started
Download &flexivecms; Download and run the installer from the &downloadPage;. 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.
Completing the installation When the server is running and you first access the CMS through the browser (&refLocalhost;), you are redirected to the &refBackendDocs;. 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.
Accessing the CMS After the initialization was completed, you can access the actual CMS website on &refLocalhost;. 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.
First Steps 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: The CMS administration bar after successful login. 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.
Creating new pages Let's create a new page. Click on the "New Page" icon in the administration bar and enter the new page data: Creating a new page. The Page path determines the initial URI of this page (in this case, first_page.xhtml), and the Page title is used as the HTML page title e.g. in the website navigation or in the HTML page title. You can change both values afterwards. For now, leave the other input fields. They are set to sensible defaults based on the current page. Click on Create child page to actually create the new page. You will then see the new page in the navigation panel on the left and in the sitemap in the administration bar: The demo website after creating a new page.
Page editing 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 pages, 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: The CMS after navigating to the created page. To change this, click on the Edit button in the upper left corner. This opens the page editor in an overlay popup window: The generic page content editor. 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: Opening the context menu for adding new properties to a content. You get a selection of properties that can be added to the current instance: The context menu for adding new properties to a content. 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: A new paragraph for your page. 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.
Publishing the changes Now that you created a new page you want the rest of the world to see it. To do this, navigate to the page and click on the Actions button in the toolbar. Currently there are two actions available, Publish and Publish all: The actions menu for "My first page". Publish all publishes a complete part of a web page, i.e. the page itself and all subpages. Since we only have a single page, it's sufficient to click on Publish. This will add the page to the live website navigation and make the content readable for everyone. You can verify this by clicking on the "Content: edit" link in the upper right corner again. You can also logout and view the page as an anonymous user, but be sure to refresh it since the CMS allows browsers to cache public pages for a certain amount of time (currently 30 minutes).
Outlook Congratulations, you now have the tools to build pages with &flexivecms;. However, there is still a lot of stuff to know to really use the possibilities that &flexive; provides: Build a multilanguage website with a URI-based locale selection (e.g. /en vs. /de). Create custom page types in the backend to suit your web page requirements. Create new templates and build more complex layouts. Implement custom functionality as JSF managed beans and Enterprise Java Beans (EJBs), and much more. We will cover these topics eventually, but for the moment let's take a step back and look at the fundamental concepts we used for building this page in the next chapter.
Concepts
Page organization Websites in &flexivecms; are organized in a hierarchical page tree similar to the folders of a file system. When logging into the backend application under http://localhost:8080/flexive/, the page tree is visible in the left panel: The backend content tree.
Page content Pages are &flexive; content instances derived from a common type, CMS_PAGE. CMS_PAGE defines the bare minimum of properties that a &flexivecms; 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 ]]> 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, &flexivecms; 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.
Templating 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 &jsf12;. A basic template could look like this: For someone familiar with JSF, this template contains no surprises. The CMS-specific part is the ]]> tag that provides the all page properties in the variable #{page}. ]]> is used to render the title. Then the paragraph(s) of the page are rendered using the ]]> component that iterates over all paragraphs of the page.
Publishing or: Edit and Live A &flexivecms; page exists in two mostly independent versions: The live version is the public-facing version of the website. The edit version is only visible to authorized CMS users. Changes can be made in the edit version and even follow a custom workflow, before they eventually get published to the live website. Contents can be published individually, or as a group. In the latter case, all contents of a part of the website including their templates are published in one sweep.
User groups A user accessing a CMS page falls into one of the following categories: Visitor Author Editor Administrator A visitor can only view published contents, while an administrator has complete access to the CMS. Authors and Editors are CMS users that manage the page content. Authors generate page content. They can create articles and make changes to their own articles, but cannot modify articles created by other users. They also cannot publish contents, and cannot undo publishing of contents (including their own). Editors manage the website. They can edit all contents, publish contents, remove contents from the website. They cannot, however, change page templates. Administrators are the CMS superusers. They are the only ones who can change the page templates. They also can create new users and data structures in the backend. A user is member of one of these user groups, all users of a group share the same permission configuration.
Putting it all together A page is a single content instance of a predefined, structured type. It contains all non-presentational content in all languages that are supported by the website. Pages are kept in a hierarchical, filesystem-like structure. A page determines how it should be rendered by referencing templates. A template is a &facelets; XHTML template for &jsf12;. A page can include and reference arbitrary contents, either through common subfolders referenced by the template or through SQL-like queries with &refFxSQL;. A content included on a page either knows how to render itself in a given context through an assigned template, or the enclosing template specifies a template to render the child content. The website exists in a live and in an edit version. The former is the public-facing website, the latter is only accessible to authorized CMS users and is used to prepare the next live version of the website. User groups control the permissions of a user. The predefined groups are Author, Editor, and Administrator.
Templating
Value rendering components
<code><![CDATA[<fx:content>]]></code> Page templates usually load the content associated with the page with the fx:content tag: ... (page content) ... ]]> The properties of the content type can then be accessed through the page variable, e.g. #{page.title} or #{page.paragraph[0].title}. Please check the &flexive; documentation on fx:content for further details.
<code><![CDATA[<cms:image>]]></code> Renders an image tag, based on fx:thumbnail and fx:fxValueInput.
Parameters value the value (of type FxBinary) pointing to an image. If empty, nothing is rendered. previewSize size of the image (default: ORIGINAL). Valid values are taken from BinaryDescriptor.PreviewSizes: PREVIEW1, PREVIEW2, PREVIEW3, SCREENVIEW, ORIGINAL (default). title alt passed to the img tag.
<code><![CDATA[<cms:value>]]></code> Renders content values, based on fx:fxValueInput. This field will turn into an edit component when inline editing is activated. If this functionality is not required, the output is similar to writing the (string) value directly, e.g. through #{page.field}.
Parameters value the FxValue to be rendered
Templating components
<code><![CDATA[<cms:applyTemplate>]]></code> Apply a template on a content. The goal is to achieve a decoupling of the page template (which may be shared for many different types of pages) from the rendering of the actual page content (e.g. an article, news item, product description, etc.). For example, the default page template uses the component like this: <cms:applyTemplate template="/templates/content"/>. The templating engine will now perform two steps: Lookup the template defined in /templates/content for the current page content (defined through the page URL). Render the page content using this template and include the output in the page. The current FxContent entry is exposed to the body in the variable "content", the page path in the variable "path", and the node ID in "nodeId" (as in cms:renderChildren).
Parameters pk The PK of the content to be rendered (default: the page content, i.e. #{fxPageBean.pagePK}). template The name of the template assignment. The default value is /TEMPLATES/CONTENT (the default page content template).
<code><![CDATA[<cms:renderChildren>]]></code> 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). 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.
Parameters id A unique ID for the component. Unfortunately, we need this to prevent JSF errors due to duplicate IDs. folder the folder name (must be a direct child of the current article node). If not set, all direct children of the current page are rendered (i.e. folder=""). template the name of the template assignment, including the root type that defines it (e.g. CMS_PAGE/TEMPLATES/PAGE or CMS_MY_ARTICLE/TEMPLATES/SNIPPET ). This implicitly limits the type of the rendered children, which must have a content type derived from this root type. If template is not set, the template must be provided in the tag body and the type attribute must be set to specify the root type. type the base type of the contents to be rendered, e.g. CMS_PAGE (if template is not set, otherwise this attribute will be ignored, default: CMS_PAGE). itemBefore header markup of an item. To work around entity encoding issues with some browsers (even if the entities are correctly escaped, some browsers replace the escaped entities when editing the template in a textarea), you may want to use the cms:openTag and cms:closeTag functions instead. For example: #{cms:openTag('li')} instead of &lt;li>. itemAfter trailing markup of an item.
<code><![CDATA[<cms:navigation>]]></code> This component renders links for a part of the page tree, e.g. for creating the website navigation menu. Please refer to the &flexive; documentation on fx:navigation for a complete description of its parameters. A short snippet using this component can be found in the navigation example.
Parameters depth The maximum depth (relative to the root node) of the navigation (default: 1). output The output mode: default (nested ul/li lists), csspopup (pure CSS popup), or yui (Yahoo UI-based menu). var Name of the JSF-EL variable provided to the tag body for rendering a menu item.
Menu components These components can be added to own templates to offer popup menus when the CMS frontend editor is active.
<code><![CDATA[<cms:childMenu>]]></code> Renders a menu with options for a child rendered by cms:renderChildren when the edit mode is active.
Parameters id A unique ID for the component.
<code><![CDATA[<cms:loginMenu>]]></code> Renders a login button for guest users or a logout button if the user is already logged in.
Parameters showLoginLink If true, a login link for the CMS is always rendered. Otherwise the menu is only visible when the edit mode is active.
<code><![CDATA[<cms:navigationMenu>]]></code> The edit mode menu for a navigation item rendered by cms:navigation.
<code><![CDATA[<cms:pageContent>]]></code> Wrapper for the page content. Inserts a form and content-related buttons in edit mode, does not alter the page otherwise.
JSF-EL functions &flexivecms; offers static helper functions that can be used in page templates, e.g. for converting strings to uppercase or for creating absolute page URLs.
URL-related functions
fx:url Renders an absolute URL for the given page URL that obeys (optional) rewriting rules, e.g. from .xhtml to .html extensions. For example: #{fx:url('/test')} => /test.xhtml
Query functions
cms:query Submit a &refFxSQL; query and return the result set. For complex queries is is usually easier to construct them in a separate expression or provide them from a managed bean. Submitting a FxSQL query in a template

PK: #{row[0]}

Title: #{row[2]}
Last modified: #{row[1]}

 ]]>
cms:escapeSql Escape the argument for use in a SQL expression. For example, strings get quoted and escaped, dates get properly formatted, and so on. For example, to escape a parameter passed from a request parameter (e.g. page.xhtml?queryName=name): ]]>
Navigation and templating
cms:pagesForLevel Returns the tree nodes for the given navigation level. The CMS root node is at level #{fxPageBean.treeRootLevel}. Using the cms:pagesForLevel function
  • Root navigation: #{node.label}
    • ]]>
    String and data handling
    cms:escapeQuotes Escapes quotes in its String argument with backslashes, e.g. for use in JavaScript expressions.
    cms:toLowerCase Converts its argument to lower case. For example: #{cms:toLowerCase('Pete')} => pete.
    cms:toUpperCase Converts its argument to upper case. For example: #{cms:toUpperCase('Pete')} => PETE.
    cms:tagOpen Renders an opening tag. This is useful to avoid issues with escaping control characters in XHTML contexts, e.g. in tag attributes. For example: #{cms:tagOpen('li')} => <li>
    cms:tagClose Renders a closing tag. This is useful to avoid issues with escaping control characters in XHTML contexts, e.g. in tag attributes. For example: #{cms:tagClose('li')} => </li>
    cms:replace Replaces a part of an input string and returns the new string. For example: #{cms:replace('Hello NAME', 'NAME', 'Pete')} => "Hello Pete"
    Recipes
    Navigation Objective: Automatically generate a top-level navigation for the pages of the website. To create a navigation that resembles the pages of your website use the cms:navigation component, for example: Using cms:navigation #{node.label} ]]>
    Teasers Objective: Render short preview texts (teasers) of pages attached to the current page. Use the cms:renderChildren component to render the pages in a specific subfolder with a teaser template. Rendering teasers with cms:renderChildren Page template: ]]> Teaser template:

    ]]>
    URL rewriting Objective: Map arbitrary URLs to CMS pages. &flexivecms; does all internal URL rewriting with UrlRewriteFilter. You can define additional rules that are applied before the CMS rules. Custom URL rewriting with UrlRewriteFilter Execute the following Groovy script in the backend script console with a user that has "Script Execution" privileges, e.g. the supervisor user. This example configuration redirects requests to /legacy-url to /info.xhtml and use page URLs ending in .html instead of .xhtml. /legacy-url /info.xhtml (.+)\\.html \$1.xhtml (.*)\\.xhtml \$1.html """)]]>
    Website resources like images and stylesheets Objective: store website resources like images or stylesheets in the CMS. &flexivecms; provides two special folders, /files and /resources, for dealing with website resources: The backend content tree with files and resources folders. /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.
    Deployment 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 .
    Deploying the CMS to an application server The CMS comes pre-packaged as an EAR application including the &flexive; backend. You can download the latest stable release from the &downloadPage;.
    Custom development 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. Links Official Homepage Download page Source code (FishEye) &flexive; core documentation Things still missing As of today, &flexivecms; 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.