webuijsf
Tag image


Use the webuijsf:image tag to display an inline image in the rendered HTML page. The url attribute is used to specify the URL to the image file that is to be displayed.

The webuijsf:image tag can be used to display a theme-specific image in the rendered HTML page. The icon attribute used in the webuijsf:imagetag is a key value that is mapped to a URL in theme properties file. The key is used to look up the appropriate image source and related attributes from the current theme. By specifying a key, you avoid the need to specify predefined constants such as height and width. The image can also be seamlessly changed when a different theme is selected.

Note:
- Currently the list of icons that you can use is not publicly supported, but the icon names are specified in the/com/sun/webui/jsf/suntheme/SunTheme.properties file. The names are listed as resource keys of the format image.ICON_NAME. Use only the part of the key that follows image. For example, if the key isimage.ALARM_CRITICAL_SMALL, you should specifyALARM_CRITICAL_SMALL as the value of the icon attribute of thewebuijsf:icon tag. A list of supported icon values will be published in the near future.

- If you use an image that is a PNG type, this component will output the correct format for an <img> tag to display a PNG correctly in Internet Explorer. In order to use this feature you must set the height and width properties of the image. If you do not specify a height or width property, a generic default value will be used for each unspecified property. The default height and width may produce an unsatisfactory image in IE.

HTML Elements and Layout

The rendered HTML page displays an XHTML compliant <img> element with any applicable element attributes. The attributes can be specified through the <webuijsf:image> tag attributes.

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({title: "My Image"}).

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:
  • alt
  • align
  • border
  • className
  • dir
  • height
  • hspace
  • id
  • lang
  • longDesc
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • src
  • style
  • tabIndex
  • title
  • visible
  • vspace
  • width

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.image.event.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

webui.suntheme.widget.image.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.image.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 an image

<webuijsf:image id="image1" url="../images/dot.gif" />

This will generate the following markup:
  
<img src="../images/dot.gif" alt="" />

Example 2: Create a theme specific image

<webuijsf:image id="image2" icon="ALARM_CRITICAL_SMALL" />

Example 3: Update client-side image properties using the getProps and setProps functions

This example shows how to toggle the visible state of an image client side using the getProps and setProps functions. When the user clicks the radio button, the image is either shown or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Image Visible" onClick="toggleVisible()"/>
<webuijsf:image id="image1" url="../images/dot.gif" />

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

Example 4: Asynchronously update image using refresh function

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

This example shows how to asynchronously update an image 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 tabs out of the text field, the input value is updated server-side and the image is updated client-side -- all without a page refresh.
<webuijsf:image id="image1" url="#{MyBean.imageSrc}" />
<webuijsf:textField id="field1" text="#{MyBean.imageSrc}" label="Change Image Source"
onBlur="refreshImage()"/> // Field used to asynchronously update image.
<webuijsf:script>
    function
refreshImage() {
        var domNode = document.getElementById("form1:image1"); // Get image
        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.ImageComponentTag
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.
onDblClickfalsefalsejava.lang.String

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

widthfalsefalsejava.lang.String

Image width override. When specified, the width and height attributes tell web browsers to override the natural image or object size in favor of these values, specified in pixels. Some browsers might not support this behavior.

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

heightfalsefalsejava.lang.String

Image height override. When specified, the width and height attributes tell web browsers to override the natural image or object size in favor of these values, specified in pixels. Some browsers might not support this behavior.

iconfalsefalsejava.lang.String

The identifier of the desired theme image.

alignfalsefalsejava.lang.String

Specifies the position of the image with respect to its context. Valid values are: bottom (the default); middle; top; left; right.

vspacefalsefalsejava.lang.String

Specifies the amount of white space in pixels to be inserted above and below the image. The default value is not specified but is generally a small, non-zero size.

stylefalsefalsejava.lang.String

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

borderfalsefalsejava.lang.String

Specifies the width of the img border in pixels. The default value for this attribute depends on the web browser.

urlfalsefalsejava.lang.String

Absolute or relative URL to the image to be rendered.

onClickfalsefalsejava.lang.String

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

onMouseDownfalsefalsejava.lang.String

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

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.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over 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.

onMouseMovefalsefalsejava.lang.String

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

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

A verbose description of this image.

hspacefalsefalsejava.lang.String

Specifies the amount of white space in pixels to be inserted to the left and right of the image. The default value is not specified but is generally a small, non-zero size.

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.


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.