webuijsf
Tag button


Use the webuijsf:button tag to display an input button in the rendered HTML page. The input button submits the associated form when activated by the user. The corresponding ActionEvent events then occur on the server.

HTML Elements and Layout

This tag creates an XHTML <input> button element with a text label.

Configuring the webuijsf:button tag 

The button component can render a button as a primary button or a secondary button. A primary button is intended to be used for buttons that are the most commonly used on a page or section of a page, and are rendered to be more visually prominent than secondary buttons. The primary attribute is false by default, which renders a secondary button.

The text attribute is used to specify the characters displayed on the buttons, which use a default button image set by the theme. The escape attribute, when set to false, causes an HTML <button> to be rendered instead of an <input> element. The <button> element, unlike the  <input> element, allows you to specify button text that will be interpreted as HTML. For example if you wanted the button to say M&M, you would have to specify M&amp;M and set escape="false".  

You can use the imageURL attribute to specify a different image for a button, or the  icon attribute to specify a theme key to a button image. When you use these attributes, the text attribute is ignored, so your button image must include any desired button text.

Note that the mini attribute at one time rendered a smaller button, but currently all buttons are the same size. The mini attribute has no effect. However, you can use style and styleClass attributes to create a smaller button if desired.

Button Actions

The button component is the most commonly used component for submitting a page. By default, the button component creates a submit button. However, you might want to use a button to go to another page in the application. In this case, you should configure the button with immediate="true" and an actionExpression that handles the navigation.

A button that is used to affect the input components on the page, such as providing initial default input, should be configured with immediate="true" and  an actionListenerExpression that updates the components.

If you want a button to submit a page, you should not set immediate, and should set an actionExpression and possibly an actionListenerExpression.   The action should get information from the managed bean and perform some business logic, and then determine what to show next on the basis of the outcome of the business logic.

If you want the button to reset all the input component values on the page, set the reset attribute to true.

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({disabled: true}).

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
  • align
  • className
  • dir
  • disabled
  • escape
  • id
  • icon
  • lang
  • mini
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • primary
  • src
  • style
  • tabIndex
  • title
  • value
  • visible

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. Using the Dojo event system, listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    dojo.subscribe(webui.suntheme.widget.button.event.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

webui.suntheme.widget.button.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
webui.suntheme.widget.button.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: Create a primary button

<webuijsf:button id="button1" text="#{ButtonBean.text}" actionExpression="#{ButtonBean.success}" primary="true" />

Example 2: Create a secondary button

<webuijsf:button id="button1" text="#{ButtonBean.text}" actionExpression="#{ButtonBean.success}" />

Example 3: Create a reset button

<webuijsf:button id="button1" text="#{ButtonBean.text}" actionExpression="#{ButtonBean.success}" reset="true" />

Example 4: Create an image button

<webuijsf:button id="button1" imageURL="#{ButtonBean.image}" actionExpression="#{ButtonBean.success}" />

Example 5: Update client-side button properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a button client side using the getProps and setProps functions. When the user clicks the radio button, the button is either disabled or enabled.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Button Disabled" onClick="toggleDisabled()"/>
<webuijsf:button id="button1" text="My Button" />

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:button1"); // Get button
return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
}
</webuijsf:script>

Example 6: Asynchronously update button using refresh function

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

This example shows how to asynchronously update a button 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 button text is updated client-side -- all without a page refresh.
<webuijsf:button id="button1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Button Text"
onKeyPress="setTimeout('refreshButton();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshButton() {
        var domNode = document.getElementById("form1:button1"); // Get button
        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.ButtonTag
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 binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
onDblClickfalsefalsejava.lang.String

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

imageURLfalsefalsejava.lang.String

Resource path of an image to be displayed to create the visual appearance of this button instead of the standard button image. Either the imageURL or text attributes must be specified. When an imageURL value is given, the button type is set to image.

onKeyPressfalsefalsejava.lang.String

Scripting code executed when the user presses and releases a key while the component has focus.

resetfalsefalsejava.lang.String

Indicates that the button should be a HTML reset button. By default, this value is false and the button is created as a submit button. If the value is set to true, no action listener will be invoked.

onFocusfalsefalsejava.lang.String

Scripting code executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse.

escapefalsefalsejava.lang.String

Escape the html text so it won't be interpreted by the browser as HTML. When the escape value is set to false, an HTML button element is rendered, instead of an HTML input element. And the alt attribute does not apply.

onKeyUpfalsefalsejava.lang.String

Scripting code executed when the user releases a key while the component has focus.

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.

iconfalsefalsejava.lang.String

The identifier key of a theme image to be used for the button.

stylefalsefalsejava.lang.String

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

onClickfalsefalsejava.lang.String

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

minifalsefalsejava.lang.String Indicates that the button should be rendered using a different style than normal buttons. By default, a button that specifies the mini attribute looks the same as a normal button. You must set your own CSS style to render a mini button.
onBlurfalsefalsejava.lang.String

Scripting code executed when this element loses focus.

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.

primaryfalsefalsejava.lang.String

Indicates that the button is the most commonly used button within a group.

disabledfalsefalsejava.lang.String

Indicates that activation of this component by the user is not currently permitted. In this component library, the disabled attribute also causes the button to be renderered using a particular style.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer off this component.

altfalsefalsejava.lang.String

Alternative textual description of the image rendered by this component. The alt text can be used by screen readers and in tool tips, and when image display is turned off in the web browser.

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.

noTextPaddingfalsefalsejava.lang.String

Indicates that padding should not be applied to the button text. By default, whitespace characters are padded to button text greater than or equal to 4 characters in length. If the value is set to true, no padding is applied.

textfalsefalsejava.lang.String

Text to display on the button. Either the imageURL or text attributes must be specified. When an imageURL value is given, the button type is set to image.

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.

onKeyDownfalsefalsejava.lang.String

Scripting code executed when the user presses down on a key while the component has focus.

tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

immediatefalsefalsejava.lang.String Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
actionExpressionfalsefalsejava.lang.String MethodExpression representing the application action to invoke when this component is activated by the user. The expression must evaluate to a either a String or a public method that takes no parameters, and returns a String (the logical outcome) which is passed to the NavigationHandler for this application.
actionListenerExpressionfalsefalsejava.lang.String Use the actionListenerExpression attribute to cause the component to fire an event. The value must be an EL expression and it must evaluate to the name of a public method that takes an ActionEvent parameter and returns void.
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.