Core Components

The facelets is the default view declaration language that uses XML and XHTML. It is a composition and templating framework that allows to create the component tree.

The core components are defined in the following namespace:

xmlns:f="http://java.sun.com/jsf/core"

The core components are implemented by the ASF.Components.Core package which defines the UIComponent that describes the various elements provided by the core components. These components are instantiated when the view is created from the facelet tree that was read from the XHTML view description.

f:attribute

This tag associates an attribute with the nearest parent UIComponent. When the value is not an EL expression, this tag has the same effect as calling Component.Set_Attribute (Name, Value). When the attribute name specified matches a standard property of the component, that property is set. However it is also valid to assign attributes to components using any arbitrary name; the component itself won't make any use of these but other objects such as custom renderers, validators or action listeners can later retrieve the attribute from the component by name.

When the value is an EL expression, this tag has the same effect as calling Component.Set_Attribute (Tag, Value) A call to method Component.Get_Attribute (Name) will then cause that expression to be evaluated and the result of the expression is returned, not the original EL expression string.

See the ASF.Components.Base package for more details.

Unless otherwise specified, all attributes accept static values or EL expressions.

Attributes

Name Required Type Description
name false String The name of the attribute.
value false String The attribute's value.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:panelGroup layout="block">
        <h:outputText value="Hello world!">
            <!-- The 'styleClass' attribute is applied
                 on the h:outputText -->
            <f:attribute name="styleClass" value="left"/>
        </h:outputText>
        <p>
            <!-- The 'styleClass' attribute is applied
                 on the h:panelGroup -->
            <f:attribute name="styleClass"
                         value="ui-widget asf-container ui-corner-all"/>
        </p>
    </h:panelGroup>
</div>

f:convertDateTime

This tag registers an instance of a Date_Time_Converter, and associates it with the nearest parent UIComponent.

Attributes

Name Required Type Description
dateStyle false String Predefined formatting style which determines how the date component of a date string is to be formatted and parsed. Applied only if type is "date" or "both". Valid values are "default", "short", "medium", "long", and "full". Default value is "default".
locale false String Locale whose predefined styles for dates and times are used during formatting or parsing. If not specified, the Locale returned by FacesContext.Get_View_Root().Get_Locale() will be used. Value must be either a VB expression that evaluates to a valid String locale.
pattern false String Custom formatting pattern which determines how the date/time string should be formatted and parsed.
timeStyle false String Predefined formatting style which determines how the time component of a date string is to be formatted and parsed. Applied only if type is "time" or "both". Valid values are "default", "short", "medium", "long", and "full". Default value is "default".
timeZone false String Time zone in which to interpret any time information in the date String. Value must be either a VB expression that evaluates to a valid string that is a timezone ID.
type false String Specifies what contents the string value will be formatted to include, or parsed expecting. Valid values are "date", "time", and "both". Default value is "date".

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <dl>
        <dt>No converter</dt>
        <dd>
            <!-- pi is a float, use a default converter -->
            #{messages.today}
        </dd>
        <dt>With converter</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <!-- use the 'float' converter defined by the application  -->
                <f:convertDateTime dateStyle="short"/>
            </h:outputText>
        </dd>
    </dl>
    <h4>dateStyle</h4>
    <dl class='list'>
        <dt>short</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <f:convertDateTime dateStyle="short"/>
            </h:outputText>
        </dd>
        <dt>medium</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <f:convertDateTime dateStyle="medium"/>
            </h:outputText>
        </dd>
        <dt>long</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <f:convertDateTime dateStyle="long"/>
            </h:outputText>
        </dd>
        <dt>full</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <f:convertDateTime dateStyle="full"/>
            </h:outputText>
        </dd>
    </dl>
    <h4>timeStyle</h4>
    <dl class='list'>
        <dt>short</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <f:convertDateTime timeStyle="short"/>
            </h:outputText>
        </dd>
        <dt>medium</dt>
        <dd>
            <h:outputText value='#{messages.today}'>
                <f:convertDateTime timeStyle="long"/>
            </h:outputText>
        </dd>
    </dl>
</div>

f:converter

This tag creates an instance of the specified Converter, and associates it with the nearest parent UIComponent.

Register a named Converter instance on the UIComponent associated with the closest parent UIComponent custom action.

Attributes

Name Required Type Description
converterId true String The converter's registered identifier.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <dl>
        <dt>No converter</dt>
        <dd>
            <!-- pi is a float, use a default converter -->
            #{compute.pi}
        </dd>
        <dt>With converter</dt>
        <dd>
            <h:outputText value='#{compute.pi}'>
                <!-- use the 'float' converter defined by the application  -->
                <f:converter converterId="float"/>
            </h:outputText>
        </dd>
    </dl>
</div>

f:facet

This tag allows to register the named facet to the closest parent UIComponent.

Facets are used by some components to render and control specific parts of the component: for example a table header or footer, the column header, the widget panel titles. Example of components that use facets: h:dataTable, h:panelGrid, w:panel.

Warning: if a facet is used within a component that does not recognize the name, the facet content will be ignored.

Attributes

Name Required Type Description
name true String The facet name.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <f:facet name="title">
        title
    </f:facet>
</div>

f:metadata

Declares the metadata facet for the view.

Attributes

None.

Example

<f:view xmlns:f="http://java.sun.com/jsf/core">
    <f:metadata>
        <f:viewParam id='height' value='#{compute.height}'>
            <f:converter converterId="float" />
        </f:viewParam>
        <f:viewParam id='radius' value='#{compute.radius}'>
            <f:converter converterId="float" />
        </f:viewParam>
        <f:viewAction action="#{compute.run}"/>
    </f:metadata>
    <dl>
        <dt>Height</dt>
        <dd>
            #{compute.height}
        </dd>
         <dt>Radius</dt>
        <dd>
            #{compute.radius}
        </dd>
        <dt>Volume</dt>
        <dd>
            #{compute.volume}
        </dd>
    </dl>
</f:view>

f:param

This tag associates a parameter name-value pair with the nearest parent UIComponent. A UIComponent is created to represent this name-value pair, and stored as a child of the parent component; what effect this has depends upon the renderer of that parent component.

Unless otherwise specified, all attributes accept static values or EL expressions.

Attributes

Name Required Type Description
name false String The name under which the value is stored.
value false String The value of this component.
id false String Get a string which uniquely identifies this UIComponent within the nearest ancestor naming component.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:outputFormat value="The value of PI is {0} and 2 x PI is {1}.">
        <f:param value="#{compute.pi}"/>
        <f:param value="#{compute.pi + compute.pi}"/>
    </h:outputFormat>
</div>

f:selectItem

This tag associates a single SelectItem with the nearest parent UIComponent. The item represents a single option for a component such as an h:selectBooleanCheckbox or h:selectOneMenu. See also component f:selectItems.

Unless otherwise specified, all attributes accept static values or EL expressions.

UISelectItem should be nested inside a UISelectMany or UISelectOne component, and results in the addition of a SelectItem instance to the list of available options for the parent component.

Attributes

Name Required Type Description
itemDisabled false Boolean Determine whether this item can be chosen by the user. When true, this item cannot be chosen by the user. If this method is ever called, then any EL-binding for the disabled property will be ignored.
escape false Boolean The escape setting for the label of this selection item.
itemDescription false String The item description.
itemLabel false String The string which will be presented to the user for this option.
itemValue false String The value for this item.
value false ValueExpression The initial value of this component.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:selectOneMenu id='height' size='10' value='#{compute.height}'
                     styleClass="ui-state-default ui-corner-all">
        <f:selectItem itemLabel="1 inch" itemValue="25.4"/>
        <f:selectItem itemLabel="1 feet" itemValue="304.8"/>
        <f:selectItem itemLabel="1 yard" itemValue="914.4"/>
        <f:converter converterId="float" />
    </h:selectOneMenu>
</div>

f:selectItems

This tag associates a list of SelectItem with the nearest parent UIComponent. The list of items is retrieved via a value-binding. See also component f:selectItem.

Unless otherwise specified, all attributes accept static values or EL expressions.

UISelectItem should be nested inside a UISelectMany or UISelectOne component, and results in the addition of one or more SelectItem instance to the list of available options for the parent component.

Attributes

Name Required Type Description
itemDisabled false Boolean Determine whether this item can be chosen by the user. When true, this item cannot be chosen by the user. If this method is ever called, then any EL-binding for the disabled property will be ignored.
escape false Boolean The escape setting for the label of this selection item.
itemDescription false String The item description.
itemLabel false String The string which will be presented to the user for this option.
itemValue false String The value for this item.
value false ValueExpression The initial value of this component.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:selectOneMenu id='height' size='10' value='#{compute.height}'
                     styleClass="ui-state-default ui-corner-all">
        <f:selectItems value="#{countries}"/>
    </h:selectOneMenu>
</div>

f:validateLength

Creates a validator and associates it with the nearest parent UIComponent. When invoked, the validator ensures that values are valid strings with a length that lies within the minimum and maximum values specified. Commonly associated with a h:inputText entity. Unless otherwise specified, all attributes accept static values or EL expressions.

Attributes

Name Required Type Description
maximum false Natural The largest value that should be considered valid.
minimum false Natural The smallest value that should be considered valid.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:form id='text-form'>
        <dl class='ui-widget container_12'>
            <dt><label for='height'>Height</label><h:message for='height'/></dt>
            <dd>
                <h:inputText id='height' size='10' value='#{compute.height}'
                             styleClass="ui-corner-all">
                    <f:converter converterId="float" />
                    <f:validateLength minimum="2" maximum="3"/>
                </h:inputText>
            </dd>
            <dt><label for='radius'>Radius</label><h:message for='radius'/></dt>
            <dd>
                <h:inputText id='radius' size='10' value='#{compute.radius}'
                             styleClass="ui-corner-all">
                    <f:converter converterId="float"/>
                    <f:validateLength minimum="1" maximum="4"/>
                </h:inputText>
            </dd>
        </dl>
        <ul class='container_12 buttons'>
            <li>
                <h:commandButton id='run' value='Compute' action="#{compute.run}"
                                 styleClass="ui-button ui-state-default ui-corner-all"/>
            </li>
        </ul>
    </h:form>
</div>

f:validateLongRange

Creates a validator and associates it with the nearest parent UIComponent. When invoked, the validator ensures that values are valid longs that lie within the minimum and maximum values specified. Commonly associated with a h:inputText entity. Unless otherwise specified, all attributes accept static values or EL expressions.

Attributes

Name Required Type Description
maximum false Long The largest value that should be considered valid.
minimum false Long The smallest value that should be considered valid.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:form id='text-form'>
        <dl class='ui-widget container_12'>
            <dt><label for='height'>Height</label><h:message for='height'/></dt>
            <dd>
                <h:inputText id='height' size='10' value='#{compute.height}'
                             styleClass="ui-corner-all">
                    <f:converter converterId="float" />
                    <f:validateLongRange minimum="1" maximum="3"/>
                </h:inputText>
            </dd>
            <dt><label for='radius'>Radius</label><h:message for='radius'/></dt>
            <dd>
                <h:inputText id='radius' size='10' value='#{compute.radius}'
                             styleClass="ui-corner-all">
                    <f:converter converterId="float"/>
                    <f:validateLongRange minimum="1" maximum="5"/>
                </h:inputText>
            </dd>
        </dl>
        <ul class='container_12 buttons'>
            <li>
                <h:commandButton id='run' value='Compute' action="#{compute.run}"
                                 styleClass="ui-button ui-state-default ui-corner-all"/>
            </li>
        </ul>
    </h:form>
</div>

f:validator

Creates a validator and associates it with the nearest parent UIComponent.

During the validation phase (or the apply-request-values phase for immediate components), if the associated component has any submitted value and the conversion of that value to the required type has succeeded then the specified validator type is invoked to test the validity of the converted value.

Commonly associated with an h:inputText entity, but may be applied to any input component. Some validators may allow the component to use attributes to define component-specific validation constraints; see the f:attribute tag. See also the "validator" attribute of all input components, which allows a component to specify an arbitrary validation method (rather than a registered validation type, as this tag does).

Unless otherwise specified, all attributes accept static values or EL expressions.

Attributes

Name Required Type Description
validatorId false String The registered ID of the desired Validator.

Example

<div xmlns:f="http://java.sun.com/jsf/core"
     xmlns:h="http://java.sun.com/jsf/html">
    <h:form id='text-form'>
        <dl class='ui-widget container_12'>
            <dt><label for='height'>Height</label><h:message for='height'/></dt>
            <dd>
                <h:inputText id='height' size='10' value='#{compute.height}'
                             styleClass="ui-corner-all">
                    <f:converter converterId="float" />
                    <f:validator validatorId="validateDimension"/>
                </h:inputText>
            </dd>
            <dt><label for='radius'>Radius</label><h:message for='radius'/></dt>
            <dd>
                <h:inputText id='radius' size='10' value='#{compute.radius}'
                             styleClass="ui-corner-all">
                    <f:converter converterId="float"/>
                    <f:validator validatorId="validateDimension"/>
                </h:inputText>
            </dd>
        </dl>
        <ul class='container_12 buttons'>
            <li>
                <h:commandButton id='run' value='Compute' action="#{compute.run}"
                                 styleClass="ui-button ui-state-default ui-corner-all"/>
            </li>
        </ul>
    </h:form>
</div>

f:view

Creates a JSF View, which is a container that holds all of the components that are part of the view. The UIView represents the root of the component tree.

Unless otherwise specified, all attributes accept static values or EL expressions.

Attributes

Name Required Type Description
locale false String The locale of this view. Default: the default locale from the configuration file.
contentType false String The content type to be placed in the response header. The default content type is text/html.

Example

<f:view contentType="application/json"
        xmlns:f="http://java.sun.com/jsf/core"
        xmlns:util="http://code.google.com/p/ada-asf/util"
        xmlns:h="http://java.sun.com/jsf/html">
[
 { "action": "update", "id": "#result", "data": "<util:escape>
     <h:panelGroup rendered="#{not empty compute.volume}">
         <h2>The cylinder volume is
             <h:outputText value="#{compute.volume}">
                <f:converter converterId="float"/>
             </h:outputText>
         </h2>
     </h:panelGroup>
    </util:escape>" }
]
</f:view>

f:viewAction

The viewAction element is used in a medata facet. It allows to execute an Ada bean action method when a request is processed. The Ada bean method is executed before rendering the page.

Attributes

Name Required Type Description
itemDisabled false Boolean Determine whether this item can be chosen by the user. When true, this item cannot be chosen by the user. If this method is ever called, then any EL-binding for the disabled property will be ignored.
escape false Boolean The escape setting for the label of this selection item.
itemDescription false String The item description.
itemLabel false String The string which will be presented to the user for this option.
itemValue false String The value for this item.
value false ValueExpression The initial value of this component.

Example

<f:view xmlns:f="http://java.sun.com/jsf/core">
    <f:metadata>
        <f:viewParam id='height' value='#{compute.height}'>
            <f:converter converterId="float" />
        </f:viewParam>
        <f:viewParam id='radius' value='#{compute.radius}'>
            <f:converter converterId="float" />
        </f:viewParam>
        <f:viewAction action="#{compute.run}"/>
    </f:metadata>
    <dl>
        <dt>Height</dt>
        <dd>
            #{compute.height}
        </dd>
         <dt>Radius</dt>
        <dd>
            #{compute.radius}
        </dd>
        <dt>Volume</dt>
        <dd>
            #{compute.volume}
        </dd>
    </dl>
</f:view>

f:viewParam

The viewParam element is used in a metadata facet. It allows to initialize a bean attribute from a request parameter.

Attributes

Name Required Type Description
name false String The name of the request parameter from which the value for this component is retrieved on an initial request or to override the stored value on a postback.
from false String A value or expression that is evaluated to initialize the parameter value. This is an extension compared to the standard implementation.

Example

<f:view xmlns:f="http://java.sun.com/jsf/core">
    <f:metadata>
        <f:viewParam name='height' value='#{compute.height}'>
            <f:converter converterId="float" />
        </f:viewParam>
        <f:viewParam id='radius' value='#{compute.radius}'>
            <f:converter converterId="float" />
        </f:viewParam>
        <f:viewAction action="#{compute.run}"/>
    </f:metadata>
    <dl>
        <dt>Height</dt>
        <dd>
            #{compute.height}
        </dd>
         <dt>Radius</dt>
        <dd>
            #{compute.radius}
        </dd>
        <dt>Volume</dt>
        <dd>
            #{compute.volume}
        </dd>
    </dl>
</f:view>