Common Concepts |
|
Developer’s Guide Home
Installation and Configuration Common Concepts Components Index Border Layout Panel Calendar Chart Command Button Command Link Confirmation Data Table Date Chooser Day Table Drop Down Field Dynamic Image Folding Panel For Each Graphic Text Hint Label Input Text Input Textarea Layered Pane Popup Layer Popup Menu Select Boolean Checkbox Select Many Checkbox Select One Radio Spinner Suggestion Field Tabbed Pane Tab Set Tree Table Two List Selection Window Focus Load Bundle Scroll Position Ajax Framework Validation Framework Tag Reference API Reference |
Configuring ComponentsKinds of Components, Component Names and APIThere are both OpenFaces components that are the extended versions of the standard JSF components, and components which don't have their standard analogs. When creating the extended versions of the standard components we tended to minimize the efforts required for transition from the standard components to their OpenFaces analogs. Thus such components have the same name as theiur standard analogs, and the standard API is mostly preserved for them. In most cases all that you're required to do to switch to the extended component is to change the component's tag prefix. For example suppose you have the following declaration: <h:commandButton value="Add" action="#{MyBean.add}"/> <h:dataTable value="#{MyBean.users}" var="user"...> <f:column> ... </f:column> ... </h:dataTable> All that you need to replace the standard components with their OpenFaces analogs is to use the "o:" tag prefix, without changing any other declarations, like this: <o:commandButton value="Add" action="#{MyBean.add}"/> <o:dataTable value="#{MyBean.users}" var="user"...> <o:column> ... </o:column> ... </o:dataTable> Using OpenFaces analogs won't change the look and behavior of your components, though, once you've switched to using the OpenFaces versions of the standard components, you are free to use the vast range of the additional functionality. For example despite looking very similar to the standard <h:dataTable> tag and having a compatible API, the <o:dataTable> tag (which represents the OpenFaces DataTable component), provides an order of magnitute higher level of functionality as opposed to its standard version with the usual features like sorting, selection, filtering, pagination, conditional styling, handling large data sets and much more. In addition to the extended components, OpenFaces complements the standard components with a range of other components commonly required for web application development, such as containers, windows, calendars, charts, more input components, etc. Although not having analogs among the standard JSF components, we strived to make the API of all components as uniform as possible, so similar approaches and functionality usually have the similar API so that once you learn a small part of the library you're fluent at using any part of it. The sections below describe the concepts that are common for all components. Customization With Attributes and Child TagsAs usual, the majority of customizations can be made through the attributes of the component's tag. The OpenFaces components have a set of common attributes. As the standard JSF components, all the OpenFaces components support the id, rendered and binding attributes. Input components support the required, validator and converter attributes. Most attributes allow specifying their values using the Expression Language (EL), and you can find out whether some particular attribute supports EL but looking up the Tag Reference. OpenFaces also employs another powerful and flexible way of customization – a child tag based customization. This way of customization is usually applicable for complex component's features that cannot be controlled by just one attribute. For example you can add the row selection and scrolling capabilities to the <o:dataTable> component simply by adding the appropriate tags as follows: <o:dataTable ...> <o:singleRowSelection rowData="#{MyBean.selectedRow}" style="background: silver"/> <o:scrolling horizontal="true" position="#{MyBean.tableScrollPos}/> ... </o:dataTable> This kind of customization usually serves two goals:
Customizing StylesAll OpenFaces components have a default style and allow flexible style customization through their attributes. These attributes usually define the component appearance in terms of Cascading Style Sheets (CSS) with the exception of some component-specific attributes whose usage depends on the component itself. Every component has the style and styleClass attributes that control the style characteristics of the entire component. The style attribute is used to specify inline CSS declarations, and the styleClass attribute is used to reference CSS classes declared elsewhere on the page or attached to the page. In case of complex components, you can usually customize styles for different parts of a component. The attributes that control a particular part of the component are named *Style and *Class, where the asterisk denotes the part of a component being customized, for example the DropDownField component has the buttonStyle/buttonClass attributes for customizing the button style. There are also attributes that specify the style depending on the state of a particular part of the component. For example, rollover*Style, rollover*Class or pressed*Style, pressed*Class. All styles that you specify for OpenFaces components are combined with the default component styles. The user-specified styles have a higher priority over the default ones, so if some style definitions overlap, custom styles will take the precedence. When specifying the state-dependent styles, it is possible that several styles can be considered applicable to a particular part of component in certain cases. For example at a moment of pressing a button, the button's pressed style, rollover style and regular (no state) style is applicable. In such cases, all of the state-dependent styles applicable for the current state are applied and are merged with the usual CSS cascading rules according to styles' priorities. Here's a typical separation of state-dependent styles on priorities (items below have a precedence over the items above):
Let's consider this on a simple example: <o:inputText value="Test" style="font-size: 14pt; background: silver" rolloverStyle="background: yellow"/> This component has a regular style of 14 pt font and a silver background, but when the mouse hovers over it, another style specifying the yellow background is added in addition to the regular style. Since both of the styles are applied simultaneously and a rollover style has a precedence over the regular style, hovering over the field will turn the background into yellow while retaining the font size specified in the regular style. The same is applicable for more complex scenarios when more styles can be applied simultaneously. Gridline/Separator StylesSeveral components have another kind of style customization attributes. These are the attributes for customizing the style of lines that separate different component's parts, outline line styles, etc. For example the horizontalGridLines attribute of <o:dataTable> tag, or the frontBorderStyle attribute of the <o:tabbedPane> tag. These attributes specify are specified as values for the CSS border attribute but without the "border:" prefix, e.g. "1px solid gray". Here's an example: <o:dataTable horizontalGridLines="1px solid #c0c0c0" verticalGridLines="1px solid gray" ... OpenFaces and the Form componentPlease note that in order for OpenFaces components to work properly, they should be placed in the <h:form> or similar tag. Handling Client-Side EventsAll OpenFaces components have a set of standard client-side events, such as onclick, ondblclick, onfocus. In addition, some components provide non-standard client-side events whose functionality depends on a particular component. Client-Side APISome OpenFaces components provide client-side methods to control the state or behavior of a component on the client side. See the "Client-Side API" section in component documentation pages for a list of client-side functions available for the respective components. Each method listed in a "Client-Side API" section is a function that should be invoked on a component's instance. Component instance can be retrieved by component's client Id using the standard document.getElementById(id) functional, or the O$(id) function as described below. The O$(id) FunctionRetrieving HTML elements or JSF components by their client id is a very common scenario in client-side programming, which usually involves invoking the document.getElementById(id) function. OpenFaces introduces the O$(id) (capital letter O and a dollar sign) function as a short replacement for the document.getElementById(id) function. Here is an example of using this function for invoking the client-side show() function for a PopupLayer component: <h:form id="form"> <o:popupLayer id="popupLayer1">...</o:popupLayer> <h:commandButton value="Show" onclick="O$('form:popupLayer1').show(); return false;"/> </h:form> Client Action ComponentsThere's a category of components that declare certain client-side behaviors that can be attached to other components or invoked explicitly with the JavaScript code. These are the components such as:
All of the client action components can be used in the following three scenarios:
Please refer to the documentation for the appropriate client action components for the full information on their usage. Ajax SupportAjax is a technique providing the ability to exchange data with the server without reloading a Web page. As a result, Web applications provide smoother user interaction, better responsiveness and take less network traffic. Please refer to the Ajax Framework page to learn about the Ajax capabilities provided with the OpenFaces library, and the way of utilizing various Ajax-related features such as reloading components, handling session expiration, customizing the Ajax progress message and defining Ajax-related events. Creating Components DynamicallyYou can create and manipulate OpenFaces components programmatically the same way as standard JSF components. However, there is one requirement: You should call the createSubComponents() method for some of the OpenFaces components after you create a component and configure its properties. This method should be called when dynamically creating the components that implement the org.openfaces.component.CompoundComponent interface after the component's id has been specified. These are components such as: FoldingPanel, TabbedPane, DropDownField, TableColumn, TreeColumn, ComboBoxFilter, DropDownFieldFilter, and InputTextFilter. Note that id assignment is optional, but the createSubComponents method should still be invoked along with dynamic component creation and component's id should not be changed after this invocation. Here is an example of creating the TabbedPane component: FacesContext facesContext = FacesContext.getCurrentInstance(); Application application= facesContext.getApplication(); TabbedPane tabbedPane = (TabbedPane) application.createComponent(TabbedPane.COMPONENT_TYPE); tabbedPane.setId("myTabbedPane"); tabbedPane.setStyleClass("tabbedPane"); ... tabbedPane.createSubComponents(facesContext); Open APIOpenFaces is a constantly evolving project and we strive to create a flexible and convenient API for the components and all capabilities provided by the library while not compromising API stability and backwards compatibility. There are different kinds of APIs in OpenFaces: tag-based APIs, Java APIs, and JavaScript APIs. Please note that for Java and JavaScript APIs there are classes, methods and functions that are an internal part of OpenFaces and shouldn't be used from application code. Such classes and methods are not considered as a part of an "open API", which means that they can be changed as the project evolves and therefore no application code should use them. Though there's a safe criterion for judging whether a particular part of API is open – if a class, method or a JavaScript function is mentioned in this Developer's Guide, then it can be considered as an open API. Naturally, all component classes, all property accessors for any component's attribute, and all data types for those properties are considered an open API. Please avoid using the JavaScript methods that are not listed in component documentation pages in this Developer's Guide. |
© 2009 TeamDev Ltd. | ![]() |