webuijsf
Tag label


Use the webuijsf:label tag to display a label for a component. To specify which component the label belongs to you may either:

If the tags are adjacent on the page, the first option should be preferred as it is simpler to configure the tag this way.

Note that many components in this library have labellabelLevel attributes (and sometimeslabelOnTop) which can be used instead of webuijsf:label. The main reason to use webuijsf:label is if you need to specify the appearance of the label beyond what these attributes permit.

HTML Elements and Layout

The webuijsf:label tag results in a HTML label or span element. A span element is rendered if no labelled component could be found.

If the tag has a body, the body must consists of tags corresponding to JSF components only. The corresponding JSF components become children of the Label component. All the child components are rendered after the label element.

If the tag has a body but no for attribute, alabel is printed, and its for attribute is set to the element ID of the first child component which is an EditableValueHolder.

Theme Identifiers

None.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({level: 2}).

getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
refresh(execute)
Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • className
  • contents
  • dir
  • errorImage
  • htmlFor
  • id
  • lang
  • level
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • required
  • style
  • title
  • valid
  • value
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: webuijsf:label with for attribute

<webuijsf:label id="label1" text="Label 1:" for="field1" labelLevel="2"/>
<webuijsf:field id="field1" text="#{Bean.value}" type="text" trim="true"/>

Example 2: webuijsf:label with labelled component in tag body

<webuijsf:label id="label2" text="Label 2:" labelLevel="2"/>
<webuijsf:field id="field2" text="#{Bean.value}" type="text"
trim="true"/></webuijsf:label>

Example 3: Using the label attribute instead of webuijsf:label

<webuijsf:field id="field3" text="#{Bean.value}" type="text" 
trim="true" label="Label 3:" labelLevel="2"/>

Example 4: Update client-side label properties using the getProps and setProps functions

This example shows how to toggle the visible state of a label client side using the getProps and setProps functions. When the user clicks the radio button, the laebl is either show n or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Label Visible" onClick="toggleVisible()"/>
<webuijsf:label id="label1" text="My Label" />

<webuijsf:script>
function toggleVisible() {
var domNode = document.getElementById("form1:label1"); // Get label
return domNode.setProps({visible: !domNode.getProps().visible}); // Toggle visible state
}
</webuijsf:script>

Example 5: Asynchronously update label using refresh function

This example shows how to asynchronously update a label using the refresh function. When the user clicks on the radio button, the label is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Label" onClick="refreshLabel()"/>
<webuijsf:label id="label1" text="#{MyBean.text}" />
<webuijsf:script>
    function refreshLabel() {
        var domNode = document.getElementById("form1:label1"); // Get label
        return domNode.refresh(); // Asynchronously refresh label
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 6: Asynchronously update label using refresh function

This example shows how to asynchronously update a label using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the label is updated client-side -- all without a page refresh.
<webuijsf:label id="label1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Label"
onKeyPress="setTimeout('refreshLabel();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshLabel() {
        var domNode = document.getElementById("form1:label1"); // Get label
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.LabelTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

onMouseDownfalsefalsejava.lang.String

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.

hideIndicatorsfalsefalsejava.lang.String

Use the hideIndicators attribute to prevent display of the required and invalid icons with the label. When the required attribute on the component to be labeled is set to true, the required icon is displayed next to the label. If the user submits the page with an invalid value for the component, the invalid icon is displayed. This attribute is useful when the component has more than one label, and only one label should show the icons.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over this component.

requiredIndicatorfalsefalsejava.lang.String

Flag indicating that the labeled component should be marked as required. It is only relevant if the labeled component is not a child of the label tag. Set this flag to ensure that the required icon shows up the first time the page is rendered.

onMouseOverfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

onMouseUpfalsefalsejava.lang.String

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

textfalsefalsejava.lang.String

The label text to be displayed for this label. This attribute can be set to a literal string, to a value binding expression that corresponds to a property of a managed bean, or to a value binding expression that corresponds to a message from a resource bundle declared using f:loadBundle.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

labelLevelfalsefalsejava.lang.String

Style level for this label, where lower values typically specify progressively larger font sizes, and/or bolder font weights. Valid values are 1, 2, and 3. The default label level is 2. Any label level outside this range will result in no label level being added.

onClickfalsefalsejava.lang.String

Scripting code executed when a mouse click occurs over this component.

forfalsefalsejava.lang.String

Use this attribute to specify the labeled component. The value of the attribute is the absolute client id of the component or the id of the component to be labeled. A relative component id may be used only if the labeled component is a sibling of the label.

converterfalsefalsejava.lang.String The converter attribute is used to specify a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
renderedfalsefalsejava.lang.String Use the rendered attribute to indicate whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
idfalsetruejava.lang.StringNo Description

Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.