Chapter 7. JSF Support

Table of Contents

The [fleXive] component library
Using the component library
Content manipulation
<fx:content>
<fx:children>
<fx:value>
<fx:fxValueInput>
<fx:fxValueInputLanguageSelect>
<fx:resultValue>
<fx:contentList>
<fx:thumbnail>
<fx:resultTable>
<fx:resultTableUpdater>
<fx:colorPicker>
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 ”.

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['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.

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”.

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.

labelKey

An optional message key that overrides the assignment label.

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 backend administration application 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 backend administration application or programmatically through the user configuration parameter com.flexive.shared.configuration.SystemParameters.USER_DEFAULTINPUTLANGUAGE.

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.


Example 7.10. 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 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.

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

all

If true, includes all resources supported by the tag. This leads to a performance penalty for loading and initializing the Javascript libraries, but is more convenient if performance is not critical.

htmlEditor

If true, the HTML editor (currently TinyMCE) will be loaded and initialized. Since TinyMCE must be initialized in the <head> section, unfortunately you have to set this attribute manually when a <fx:fxValueInput> component is used for a HTML property.

jsonRpc

Includes the JSON-RPC-Java library for Ajax calls via JSON/RPC (the Javascript proxy can then be obtained with flexive.yui.getJsonRpc()).

yui

Includes the Yahoo UI bootstrap library. If you want to use Yahoo UI components, you also have to include a call to <fx:yuiSetup/> near the end of your page. You also 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">.

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.