webuijsf
Tag imageHyperlink


Use the webuijsf:imageHyperlink tag to display a clickable image in the rendered HTML page. The image is surrounded by an HTML hyperlink, allowing the image to function as a hyperlink.  This tag is based on a webuijsf:hyperlink tag and functions the same way.  The main difference is this tag will format an image with a surrounding hyperlink.  See the webuijsf:hyperlink tag for more examples on using a hyperlink.

The webuijsf:imageHyperlink component can be also be used to submit forms. If the actionExpression attribute is used, the form is submitted. If the url attribute is used, the link is a normal hyperlink that sends the browser to a new location.

The webuijsf:imageHyperlink can display a clickable icon image from the current theme in the rendered HTML page using the "icon" attribute. Take a look at the webuijsf:image tag to see how the icon attribute is to be used. The image that is specified as a part of the imageUrl or the icon attribute is shown for the enabled state of the imageHyperlink. If a disabledImage facet is specified, then that image will be shown when the imageHyperlink changes to the disabled state. If not, the image specified for the enabled state will be shown.

HTML Elements and Layout

The rendered HTML page contains an XHTML <a> element with an <img> element inside. Image attributes that are specified with the webuijsf:imageHyperlink tag are used as attributes in the <img>  element.

Facets

The imageHyperlink supports the following facets

disabledImage

Specify the image to be shown when the imageHyperlink is disabled.

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({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:
  • id
  • className
  • dir
  • disabled
  • disabledImage
  • enabledImage
  • href
  • hrefLang
  • imagePosition
  • lang
  • onFocus
  • onBlur
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • style
  • tabIndex
  • 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: Create an imageHyperlink with yahoo gif

<webuijsf:imageHyperlink id="imagehyperlinktest1" imageURL="../myyahoo.gif" action="#{HyperlinkBean.getRequiredHelp}" />

Example 2: Create an IconHyperlink using the required indicator icon

<webuijsf:iconHyperlink id="iconhyperlinktest1"
              icon="LABEL_REQUIRED_ICON"
              action="#{HyperlinkBean.getRequiredHelp}" />

Example 3: Using disabledImage facet.

<webuijsf:imageHyperlink id="iconhyperlink" url="/faces/calendar/index.jsp"   alt="Go to Calendar tests" icon="ALARM_MAJOR_MEDIUM" text="Calendar Test">
<f:facet name="disabledImage">
    <webuijsf:image id="disabledImage" icon="ALARM_MASTHEAD_MAJOR_DIMMED"/> </f:facet> </webuijsf:imageHyperlink>

Example 4: Update client-side image hyperlink using the setProps and getProps functions

This example shows how to toggle the visible state of an image hyperlink client side using the getProps and setProps functions. When the user clicks the button, the image hyperlink is either shown or hidden

<webuijsf:imageHyperlink id="form1:hyperlink1" icon="ALARM_MAJOR_MEDIUM" text="#{HyperlinkBean.text}"
          actionExpression="#{hyperlinkBean.action}" /> Click here </webuijsf:imageHyperlink>

<webuijsf:button id="button1" text="Hide hyperlink" onClick="toggleVisible()"/>

< script type="text/javascript">
    function toggleVisible() {
        var domNode = document.getElementById("form1:hyperlink1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 5: Asynchronously update image hyperlink using refresh function

This example shows how to asynchronously update an image hyperlink using the refresh function. When the user clicks on the button, the image hyperlink is asynchronously updated with new data.
<webuijsf:imageHyperlink id="hyperlink1" icon="ALARM_MAJOR_MEDIUM" text="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshHyperlink();return false;"/>
<webuijsf:script>
    function refreshHyperlink() {
        var domNode = document.getElementById("form1:hyperlink1"); // Get hyperlink
        return domNode.refresh(); // Asynchronously refresh hyperlink
    }
</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 hyperlink using refresh function

This example shows how to asynchronously update an image hyperlink 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 hyperlink is updated client-side -- all without a page refresh.
<webuijsf:imageHyperlink id="hyperlink1" icon="ALARM_MAJOR_MEDIUM" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change hyperlink Text"
onKeyPress="setTimeout('refreshHyperlink();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function refreshHyperlink() {
        var domNode = document.getElementById("form1:hyperlink1"); // Get hyperlink
        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.ImageHyperlinkTag
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

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

widthfalsefalsejava.lang.String

Image width override. When specified, the width and height attributes tell user agents to override the natural image or object size in favor of these values.

imageURLfalsefalsejava.lang.String

Absolute or relative URL to the image to be rendered.

heightfalsefalsejava.lang.String

When specified, the width and height attributes tell the client browser 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.

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.

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.

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.

borderfalsefalsejava.lang.String

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

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.

textPositionfalsefalsejava.lang.String

Specifies where the text will be placed relative to the image. The valid values currently are "right" or "left".

onKeyPressfalsefalsejava.lang.String

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

targetfalsefalsejava.lang.String

The resource at the specified URL is displayed in the frame that is specified with the target attribute. Values such as "_blank" that are valid for the target attribute of a HTML anchor element are also valid for this attribute in this component

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.

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.
urlLangfalsefalsejava.lang.String

The language code of the resource designated by this hyperlink.

idfalsetruejava.lang.StringNo Description
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.

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.
stylefalsefalsejava.lang.String

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

urlfalsefalsejava.lang.String

Absolute, relative, or context relative (starting with "/") URL to the resource selected by this hyperlink. If the url attribute is specified, clicking this hyperlink sends the browser to the new location. If the action attribute is specified, the form is submitted. If both are specified, the url attribute takes precedence.

onClickfalsefalsejava.lang.String

Scripting code executed when a mouse click occurs over this component. If the component submits the form (by using the action attribute), the script that you use with the onClick attribute should not return from the function. When the action attribute is used, the component handles the return with a script that is appended to the anchor element's onclick property. When you supply an onClick attribute, this return script is appended after your script in the anchor's onclick. It is ok to return from your script to abort the submit process if necessary.

onBlurfalsefalsejava.lang.String

Scripting code executed when this element loses focus.

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.

typefalsefalsejava.lang.String

The MIME content type of the resource specified by this component.

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.
disabledfalsefalsejava.lang.String

Flag indicating that clicking of this component by the user is not currently permitted.

onMouseOutfalsefalsejava.lang.String

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

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.
textfalsefalsejava.lang.String

The text to be displayed for the hyperlink.

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


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.