Chapter 7. JSF Support

Table of Contents

The [fleXive] component library
Using the component library
Content manipulation
<fx:content>
<fx:children>
<fx:contentEditor>
<fx:value>
<fx:fxValueInput>
<fx:fxValueInputLanguageSelect>
<fx:resultValue>
<fx:contentList>
<fx:thumbnail>
<fx:resultTable>
<fx:resultTableUpdater>
<fx:colorPicker>
<fx:linearizeFxValueInputs>
Navigation components
<fx:navigation>
Framework components
<fx:includes>
<fx:yuiSetup>
Form utility components
<fx:formRow>
<fx:fieldSet>
JSF managed beans
fxContentViewBean
fxAuthenticationBean
fxMessageBean
Delivering XHTML pages from the classpath
URI rewriting for contents
Writing reusable [fleXive] components
JSF components
Build file support
Deployment
Packaging
EJB components
The JSF plugin API
Overview
The plugin registry
Registering plugins at extension points

[fleXive] offers a set of JSF components for working with [fleXive] contents and data structures. This includes components to render and edit FxContent instances, submit search queries and show their results, and create custom content queries. To make your own reusable components, [fleXive] provides a simple-to-use plugin API for wiring your own reusable JSF and EJB components for other [fleXive] applications.

[fleXive] JSF support consists of two major modules:

A comprehensive guide on extending [fleXive] functionality is the section called “Writing reusable [fleXive] components ”.

The [fleXive] component library

To use the [fleXive] component library, you have to

  1. Add flexive-plugin-jsf-core.jar to your application's classpath

  2. Add the namespace declaration xmlns:fx="http://www.flexive.com/jsf/core" to the top of your XHTML documents.

  3. On every page using [fleXive] components, you have to add a call to <fx:includes/> somewhere in the HTML head section. This tag includes javascript files and CSS stylesheets needed by the components via Weblets.

  4. If you want to use components based on Yahoo UI, you have to include a call to <fx:yuiSetup/> near the end of the HTML body section. This initializes all YUI components on the current page and loads the required Javascript libraries. You also have to specify the YUI skin class on your page, the most convenient way is through the body tag, e.g.: <body class="yui-skin-sam">.

The [fleXive] components for displaying and editing contents are most crucial for any application that works with [fleXive] contents.

The <fx:content> component offers direct access to FxContent values through the property XPath. It also supports groups and multiplicities, i.e. iteration over properties and groups that may exist more than once in an instance. When no content ID is specified, a FxType name or ID is passed to create a fresh instance of the given property type. Instances can then be saved through the fxContentViewBean, or any other JSF managed bean that has a FxContent property.

A main service of the <fx:content> component is to provide direct access to the property values stored in FxContent instances through JSF-EL expressions. Inside the body of <fx:content var="content">, the following expressions may be used:

#{content.name} , #{content['name']} , #{content['/name']

Return the FxValue of the property identified by the XPath "/name[1]". For properties like "/name" that are attached directly to the content root node, the notations #{content.name}, #{content['name']}, and #{content['/name']} are equivalent. The following examples won't always specify all possible notations.

#{content.name$label}

Return the assignment label of type FxString for the given XPath.

#{content.name$hint}

Return the assignment hint of type FxString for the given XPath.

#{content['group/text']}

Return the given group property. Note that #{content.group.text} currently does not work.

#{content.element$list}

Provide a list for all entries of the group (or property) "element". If "element" is a property, the iterator returns FxValue objects, otherwise it returns a list of virtual fx:content instances with a prefix for the current group element ( Example 7.1, “Render FxContent property values” illustrates how this feature can be used for looping over groups with <ui:repeat>).

#{content.element$listAll}

Like #{content.element$list}, but includes empty elements.

#{content.reference$.property}

Resolve the given reference property and provides a content for its properties. An expression can also use several nested resolving operations, e.g. #{content.reference$.owner$.email}.

#{content['group/text$new']}

Create a new instance of "group" and return its text property. Note: the current implementation is a hack and works only for simple cases.

#{content['group/text$mayCreateMore']}

Returns true if evaluating the $new suffix for the given XPath will succeed. Useful when using the $new suffix for assignments with a limited multiplicity, since it could cause an exception otherwise.

#{content.name$valid}

Return true if the given XPath (name) is valid for the content instance.

Render-time Components

Be aware that <fx:content> is a render-time component. That is, the content instance is provided during view rendering (i.e. between encodeBegin and encodeEnd), but not during view creation. This means, unfortunately, that it is not possible to use Facelets' compile-time tags like <c:forEach> or <c:if> with EL expressions that contain content instances provided by <fx:content>. Instead, render-time components must be used to achieve similar results - for example, <ui:repeat> to iterate over lists or <ui:fragment rendered="..."> for conditional page rendering.







The <fx:children> component provides an iterator over properties and groups of a content instance. The current value is stored in a variable with the same name as the property. The same can be achieved by using the $list JSF-EL suffix as described in the section called “Accessing property values with JSF-EL”.

The <fx:contentEditor> component allows creation, editing and deletion of content instances similar to the Instance Editor.

Warning

This component depends on <fx:includes htmlEditor="true" yui="true"> on the beginning of the page, together with <fx:yuiSetup/> at the end of the page. Furthermore the component needs to be surrounded by a prefixed multipart form. Beyound the core JSF tag libraries, Ajax4jsf and MyFaces Tomahawk are required as well.

editorId

Id of the content editor component (must be unique in a view, used as key to retrieve a specific content instance stored in view-state).

formPrefix

The form prefix of the surrounding form.

contentId

Id of the content to be edited. The maximum available version is loaded.

pk

FxPk of the content to be edited.

content

Content instance to be edited.

typeId

Type id of the content instance to be created.

type

FxType of the content instance to be created.

valueFormatter

A custom valueFormatter which is passed to <fx:fxValueInput/> components within this component.

reset

True if the content for the given editor id should be reset upon the next request (==removed from content storage and reinitilaized with given attributes, default: false). Normally you won't use this, but if you want to know more, see the section called “Customizing the <fx:contentEditor> component” for details.

reRender

External client id which is to be rerendered upon the next AJAX-request triggered by the content editor component. Normally you won't use this, unless you need to rerender a component containing several fxContentEditors.

editMode

If true initilaizes this component to edit mode, otherwise to view mode (default: false).

disableAcl

True if ACL selectbox should not be rendered (default:false).

disableWorkflow

True if workflow selct box should not be rendered (default:false).

disableEdit

True if "edit" button should not be rendered (default:false).

disableDelete

True if "delete" button should not be rendered (default:false).

disableVersion

True if "save in new version" button and "delete version" button should not be rendered (default:false).

disableCompact

True if "compact" button should not be rendered (default:false).

disableSave

True if "save" button should not be rendered (default:false).

disableCancel

True if "cancel" button should not be rendered (default:false).

disableButtons

True if no buttons should be rendered (default:false).

disableAddAssignment

True if icons for adding/inserting assignments should not be rendered (default:false).

disableRemoveAssignment

True if icons for removing assignments should not be rendered (default:false).

disablePositionAssignment

True if icons for positioning assignments should not be rendered (default:false).

disableMessages

True if the <h:messages/> tag inside the content editor should not be rendered (default:false).

disableReferenceEditor

True if the inline editor controls for references should not be rendered (default: false).

closePanelScript

A JavaScript code which is called when the editor is closed (clicking on the "Save and exit" or "Stop editing" button)

showLockOwner

True if the the respective content's lock owner should be shown (default: true).

Because of its generic nature the content editor cannot satisfy every need out of the box. However, precautions have been taken to make this component customizable to your specific application needs. Let's look at the different parts that make up the content editor more closely:

Stylesheet

All relevant style entries are prefixed with .fxContentEditor_. So if you want to replace icons and images, change colors etc., you can include your own stylesheet overriding those entries.

Templating

<ui:insert> tags allow you to insert or replace whole parts of the content editor component via <ui:define>.

The provided names of the <ui:insert> tags and respective locations are:

insertTop: located at the very top of the component
contentSettings: replaces the ACL and Workflow select boxes
insertMiddle: located right after contentSettings
buttons: replaces all buttons
editButton: replaces the "Edit" button
createButton: replaces the "Create" button
saveButton: replaces the "Save" button
saveInNewVersionButton: replaces the "Save in new Version" button
deleteButton: replaces the "Delete" button
deleteVersionButton: replaces the "Delete Version" button
compactVersionButton: replaces the "Compact" button
cancelButton: replaces the "Stop Editing" button
saveAndCancelButton: replaces the "Save and Stop Editing" button
additionalButtons: located right after the previous buttons
insertBottom: located at the very bottom of the content editor

Extending functionality

By using templating and FxWrappedContent as described above you can add your own buttons to add additional functionality. Also you may extend existing functionality by calling methods of the component's backing bean FxContentEditorBean from within your own managed beans. See the section called “Content Editor Examples” for examples and important instructions.


Example 7.10. Content Editor adding buttons

In this example three buttons are added, which will be inserted in the contentEditor component's template at the <ui:include/> named "additionalButtons". Note that for the Ajax4jsf button flexive.contentEditor.preSubmit() should be called. If you want to use actions of the component's backing bean, make sure you set up the property action listeners accordingly.


<fx:contentEditor var="myContent" ...>
    <ui:define name="additionalButtons">

        <!-- adding a command button -->
        <h:commandButton value="My Button" action="#{myBean.doSomething}">
            <!-- property action listener for FxWrappedContent-->
            <f:setPropertyActionListener value="#{myContent}" target="#{myBean.content}"/>
        </h:commandButton>

        <!-- adding an ajax command button -->
        <a4j:commandButton value="My Ajax Button" action="#{myBean.doSomething}">
            <!-- necessary js call when using a4j button(caused by a4j multipart form submit bug -->
            onclick="flexive.contentEditor.preSubmit();"
            <!-- rerender attribute -->
            reRender="#{myContent.guiSettings.reRender}"
            <!-- using the content editor component's status -->
            status="#{myContent.editorId}_status">
        </a4j:commandButton>

        <!-- adding property action listeners for the component's backing bean (FxContentEditorBean)-->
        <a4j:commandButton .. action="#{__ceBean.action}">
            <f:setPropertyActionListener value="#{myContent.editorId}" target="#{__ceBean.editorId}"/>
            <f:setPropertyActionListener value="#{myContent.guiSettings.reRender}" target="#{__ceBean.reRender}"/>
        </a4j:commandButton>

    </ui:define>
</fx:contentEditor>


For writing FxContent editors, the <fx:value> component provides a complete property value input row consisting of

The output is controlled by the <fx:formRow> component. All parameters of <fx:formRow> can also be set for <fx:value>, except those that control the actual value being rendered.

Note: <fx:value> is a Facelets compile-time component, this means that its input variables must be bound during view creation. Data exposed by components like <ui:repeat> is not available during "compile time" and cannot be used as input for <fx:value>. Use compile-time iterators such as <c:forEach> instead.

property

The XPath of the property.

var

The value of the "var" attribute of the <fx:content> component whose content should be edited. If nested directly in a fx:content tag, this attribute can be omitted.

label

An optional label that overrides the assignment label.

labelKey

An optional message key that overrides the assignment label.

tooltip

The input label tooltip (optional).

tooltipKey

Message key of the tooltip (overrides tooltip, if not specified and labelKey is set, it defaults to#{labelKey}.tooltip)

readOnly

If true, no input field will be rendered.

forceLineInput

For multiline and HTML properties, force to render a single-line input field (e.g. for search query forms).

inputMapper

An optional input mapper for rendering the input control. For example, properties referencing other content may need a custom input mapper that provides a select list of content instances. For more information take a look at the InputMapper documentation and at Example 7.6, “Use InputMappers for application-specific properties”.

valueFormatter

A FxValueFormatter to be used for rendering the value (in read-only mode only). If not specified, the JSF renderer will choose the appropriate default formatter for the actual value class.

filter

If set to false, HTML output will not be filtered. If set to true (the default), HTML entities will be used for sensitive characters (e.g. "&lt;" instead of "<").

disableMultiLanguage

Disables multi language support even if the FxValue object is multilingual. Only the default translation will be displayed and updated.

disableLytebox

Set this property to true if the Lytebox javascript library used for rendering inline previews of images should not be used.

onchange

An optional javascript expression to be called when an input element changed its value.

autocompleteHandler

An instance of the flexive.yui.AutoCompleteHandler javascript class. This class provides a query method for a client-side autocomplete widget provided by Yahoo UI, as well as a method for formatting the response.

For basic usage examples, look at the the section called “Examples” in the <fx:content> documentation. For examples on controlling the output of the <fx:formRow> component, see the section called “Examples” of that component.

The <fx:fxValueInput> component is a universal component for editing FxValue objects. It supports every datatype of FxValue, for example plain text, numbers, dates, or even binaries. It is used in the administration GUI content and search query editors and in every other place where a FxValue needs to be edited. It also includes multilanguage support by providing a language select list next to the input elements.

The default input language of multi-language values can be set in the user preferences of the administration GUI or programmatically through the user configuration parameter com.flexive.shared.configuration.SystemParameters.USER_DEFAULTINPUTLANGUAGE.

Note that this component is a JSF UIInput component, thus it supports many standard JSF input facilities (like value change listeners or validators).

value

An expression of type FxValue of the value to be edited. Note that the value must not be null, otherwise the input component cannot determine the actual FxValue type.

id

An optional client ID of the input component.

externalId

An optional external ID that overrides the clientId in JSF validation error messages - may be necessary in complex, generic forms, but usually you won't need this.

readOnly

If true, only the value itself will be rendered.

readOnlyShowTranslations

If true, all translations of a property will be shown, else only the best matching translation (in the calling users language or the language marked as default).

forceLineInput

For multiline and HTML properties, force to render a single-line input field (e.g. for search query forms).

inputMapper

An optional input mapper for rendering the input control. For example, properties referencing other content may need a custom input mapper that provides a select list of content instances. For more information take a look at the InputMapper documentation and at Example 7.6, “Use InputMappers for application-specific properties”.

valueFormatter

A FxValueFormatter to be used for rendering the value (in read-only mode only). If not specified, the JSF renderer will choose the appropriate default formatter for the actual value class.

filter

If set to false, HTML output will not be filtered. If set to true (the default), HTML entities will be used for sensitive characters (e.g. "&lt;" instead of "<").

containerDivClass

If this CSS class property is set, the component will be embedded in a div-container using this CSS class as style.

disableMultiLanguage

Disables multi language support even if the FxValue object is multilingual. Only the default translation will be displayed and updated.

disableLytebox

Set this property to true if the Lytebox javascript library used for rendering inline previews of images should not be used.

onchange

An optional javascript expression to be called when an input element changed its value.

autocompleteHandler

An instance of the flexive.yui.AutoCompleteHandler javascript class. This class provides a query method for a client-side autocomplete widget provided by Yahoo UI, as well as a method for formatting the response.

valueChangeListener

A JSF listener that is invoked when the component value changes.


Example 7.13. An autocomplete handler for user names

In this example, we use the predefined JSON/RPC autocomplete provider AutoCompleteProvider#userQuery(String query). It searches for user account names based on the user input and returns possible matches.

<script type="text/javascript">
<!--
    // Initialize the Javascript handler that submits the queries via JSON/RPC and evaluates the response
    var userAcHandler = new flexive.yui.AutoCompleteHandler(function(query) {
        // execute JSON/RPC call and evaluate the response
        return eval("(" + flexive.util.getJsonRpc().AutoCompleteProvider.userQuery(query) + ")");
    });
//-->
</script>

<fx:fxValueInput value="#{backingBean.userName}" autocompleteHandler="userAcHandler"/>

The backing bean property #{backingBean.userName} is a property of type FxString and will hold the submitted user name.



The resultValue tag is a specialized wrapper for the <fx:fxValueInput> to be used for rendering a column value of a search result row. If the value passed is an instance of FxValue, a read-only instance of <fx:fxValueInput> is created which then renders the given value. Otherwise (e.g. for FxPK primary keys or primitive values) a generic formatter is used, which can be customized e.g. for formatting of tree paths with a link formatter.

value

The value to be rendered. Can be of any type.

linkFormatter

A ContentLinkFormatter instance that will be used for rendering links to contents. This applies to the rendering of the virtual properties @pk and @path, as described in the section called “Tree Search”. If not specified, the default ContentLinkFormatter will be used. For a description of the supported link format, please refer to the [fleXive] JavaDoc of this class.

contentLinkFormat

The format string passed to the linkFormatter for content links, i.e. FxPK values. For a description of the supported link format of the default formatter, please refer to the [fleXive] JavaDoc of this class.

itemLinkFormat

The format string used for FxPaths values as returned by the virtual @path property. For a description of the supported link format of the default formatter, please refer to the [fleXive] JavaDoc of this class.

Iterates over a collection of content instances. This component is essentially an iterator wrapping a fx:content component. The content instances can be specified through nested Groovy queries or a SqlQueryBuilder instance.

Renders a thumbnail for a given FxPK or FxBinary reference.

pk

The primary key of the content instance. If the PK is specified, the default thumbnail of the content is rendered.

binary

A specific binary entry of type FxBinary to be rendered. This is useful for for content types with more than one binary property. For an example, see the section called “ <fx:children>.

urlOnly

If true, only the thumbnail URL will be rendered (relative to the context root, e.g. thumbnail/pk5.1/s0).

previewSize

The desired size of the thumbnail. Valid values are taken from BinaryDescriptor.PreviewSizes:

  • PREVIEW1,

  • PREVIEW2 (default),

  • PREVIEW3,

  • SCREENVIEW,

  • ORIGINAL.

forceVersion

If set to max or live, it overrides the version information in the PK or binary descriptor.

Renders a Yahoo UI datatable widget for a [fleXive] result set. This provides an easy way of rendering a result to the user, and it includes a paginator widget.

var

The name of the Javascript variable that exposes the Yahoo UI DataTable widget.

value

The result set to be rendered, or a plain text FxSQL query. The following types are supported:

String

A FxSQL query, for example: SELECT @pk, #image/caption

com.flexive.shared.search.FxResultSet

The result of a FxSQL query.

com.flexive.shared.search.query.SqlQueryBuilder

A FxSQL query builder instance the will be used for fetching the result set.

viewType

The view type of the datatable. "list" renders a common table view for each of the columns, while "thumbnails" renders only the thumbnails as in the backend administration's thumbnail view. Note that the thumbnail view only works if the object's primary key ("@pk") was selected in the query, otherwise no valid thumbnail image can be rendered.

clickHandler

An optional Javascript method for handling clicks on the table with signature function handler(targetEl, pk). The primary key parameter is only available if the @pk column was selected in the FxSQL query.

actionColumnHandler

An optional instance of type flexive.yui.datatable.ActionColumnHandler for generating the contents of the "Action" column - an additional column that can be used for displaying custom actions for contents and that will only be visible when this parameter is set. The flexive.yui.datatable.ActionColumnHandler#getActionColumn method is passed the primary key and the permissions of the column, which can be null if the search result does not contain the @pk or @permissions properties.

previewSize

name of the preview size to be used for thumbnails (see BinaryDescriptor#PreviewSizes ).

rowsPerPage

current value for the paginator (optional).

initialPage

current page index for the paginator (optional).

firstColumn

index of the first column to be included in the table (1-based, optional).

[fleXive] offers a powerful way for mapping web page navigation structures through its tree engine. The components in this section allow rendering of (parts of) the tree in HTML, e.g. web page menus or trees.

Renders part of the content tree as nested <ul> elements. These can be styled via CSS to resemble menus or even pop-up menus, or enhanced with JavaScript using YahooUI components.

var

The variable name where the current tree node of type FxTreeNode will be exposed to the page.

output

The output format.

default

Plain HTML output.

csspopup

Renders additional CSS classes that will show only the first tree level and open the subfolders when the mouse hovers over them.

yui

Renders additional markup that allows the Yahoo UI Menu component to build a menu. If JavaScript is disabled, the plain HTML markup is shown to the use. Note that you have to include YUI on the page with <fx:includes>.

path

The tree folder to be rendered. If none is specified, the root folder ("/") is rendered.

mode

The tree mode, "edit" or "live" (default).

depth

The maximum tree depth for sub folders. For example, a value of 2 will render content of the given tree path and the first level of subfolders.

selectedNodeId

If specified, the given tree node ID will be highlighted in the HTML output.

baseTypeId/baseTypeName

An optional type filter for the rendered nodes. Only nodes whose reference is of the given type (or a subtype of the given type) are rendered.

When a non-folder base type is specified, folders are (by default) not rendered in the response. You can override this by setting the includeFolders attribute.

includeFolders

When baseTypeId/baseTypeName is set, setting this attribute to "true" will include folders and their contents in the output even if the specified base type is not a folder.

includeRoot

When set to true, the root node of the rendered (sub-)tree is included in the output. (default: false)

Includes external resources (CSS and JavaScripts) used by [fleXive] components. Place this in the <head> section of your HTML page.

Note that you can include the <fx:includes> tag more than once. This is useful if a component (e.g. the HTML editor) is only needed on some pages and <fx:includes> is already included in the main page template.

Initializes the Yahoo UI widgets on the current page and loads all required libraries. Note that you still have to initialize the YUI bootstrap loader using <fx:includes yui="true">.

When using Yahoo UI you have to specify the skin class on your page, the most convenient way is through the body tag, e.g.: <body class="yui-skin-sam">.

[fleXive] provides a set of JSF managed beans for working with [fleXive] in JSF applications. Some of them are usually used only in administration pages, some will probably be used in every [fleXive] application. For a complete reference consult the [fleXive] JavaDoc.

The fxMessageBean is an application-scoped bean that provides a localized message lookup service for JSF. Instead of a single resource bundle as provided by JSF's loadBundle, the fxMessageBean provides centralized access to the messages of all [fleXive] applications and plugins available in the current context.