Image

Add mouse-over, depressed and disabled states to an <input type='image'> tag or to an <input type='button-type'> tag or to an <img>.

The JSF image component is used to augment the standard HTML <img> or <input> tags of type button (for example, submit, reset, button and image) providing them with four different visual states (normal or up, depressed, moused, and disabled). In addition, it can be used to add a label that can be styled or positioned (or second label in the case of a button that already has a label) and/or an icon (small graphic) to the image button.

At its simplest (no attributes are provided), it effectively provides support for the CSS pseudo-class hover. You can specify (via CSS), classname_moused (instead of classname:hover) in the CSS and you will get a mouse-over effect on the button. Equally, it provides the ability to specify the style of the button when it is depressed and/or disabled.

In addition to providing states, the component enables you to add an icon to the button (in addition to any graphic/text already in the button). For example, you could add a small arrow graphic or a hinky graphic to the button. Equally, you can add a label to the button (in addition to a label that the button may already display). Both the icon and label support states as well (for example, the label can be turned red on mouseover or the icon made black).

In the case of an image button (<input type="image">), the component supports the common JavaScript-provided function of swapping the src attribute's value based on the state of the button (for example, switching to a different image when the mouse is over the button).

In the case of <img>, JSF Image effectively turns the tag into a button. The click event handler should be specified if the image is to perform an action when it is clicked. The keyboard is automatically wired on img tags so that it can be used to click the button (and the click event handler is called). The tabindex needs to be set to put the img into the taborder (if it can be clicked) since this is not done by browsers by default.

JSF tags that emit the component

<hx:commandExButton>

Base HTML

<input type="image" id="id">
<input type="submit" id="id">
<input type="reset" id="id">
<input type="button" id="id">
<img src="src" id="id">

All attributes set on the base tag are supported.

All event handlers associated with the base tag are supported.

JavaScript constructor

hX_5.addComponent("id", new hX_5.JSFImage(attributes)); where

id

The ID of the HTML tag to which the component is attached.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Attributes

Table 1. Image attributes

Attribute name

Description

depressed

For images and buttons of type image only, the URL of the image to display when the button is depressed. If omitted, the normal image is used in the depressed case.

disabled

Specifies if the object is available.

icon-normal

The URL of an icon image to be displayed atop the image/button while in normal state. For example, a little triangle image that means the button has a drop-down.

icon-moused

The URL of the image to display as an icon when the mouse is over the image/button (the hover case). The normal image must be supplied as well for this to be used. If omitted, the normal image is used in the hover case.

icon-depressed

The URL of the image to display as an icon when the image/button is depressed. The normal image must be supplied as well for this to be used. If omitted, the normal image is used in the depressed case.

label

The text to display for the object.

moused

For images and buttons of type image only, the URL of the image to display when the mouse is over the button (the hover case). If omitted, the normal image is used in the hover case.

normal

For images and buttons of type image only, the URL of the image to display when the button is in normal state (not moused, not depressed, not disabled). The image for the button can also be specified via the src attribute of the <input> tag. For image tags, the src must be supplied (even if it is not used) due to HTML restrictions.
Note: For this and all other attributes which supply a URL, the URL can reference a file on the file system or it can be wrapped in a URL prolog. The image can also be specified via CSS instead of as an attribute.

CSS classes

Table 2. Image CSS classes

CSS class name

Description

user-supplied

Supplied as the class of the <input> or <img> tag. Styles the image/button proper (for example, sets the height, width, background color) when it is in normal (up) mode.
Note: For any kind image/button or button state, the background-image style property can be used to specify the image used as the button. If specified, the height and width properties must be set as well (to the size of the background image).

<base>_moused

Styles the image/button proper (for example, sets the height, width, background color) when it is moused over (hover case). If omitted, the normal state is used when hovering.

<base>_depressed

Styles the image/button proper (for example, sets the height, width, background color) when it is depressed. If omitted, the normal state is used when depressed.

<base>_disabled

Styles the image/button proper (for example, sets the height, width, background color) when it is disabled. If omitted, the normal state is used when disabled.

<base>_Label

If the label is specified, styles the label when in the normal (up) state. Note that font properties for the label (for example, font-family, font-size), must be specified in this class. They are not picked up from the base class.

<base>_Label_moused

If the label is specified, styles the label when the button is in the normal (up) state. If omitted, the normal state is used for the label when hovering.

<base>_Label_depressed

If the label is specified, styles the label when the button is depressed. If omitted, the normal state is used when depressed.

<base>_Label_disabled

If the label is specified, styles the label when the button is disabled. If omitted, the normal state is used when disabled.

<base>_Icon

If the icon is specified, styles the icon when in the normal (up) state.

<base>_Icon_moused

If the icon is specified, styles the icon when the button is in the normal (up) state. If omitted, the normal state is used for the icon when hovering.

<base>_Icon_depressed

If the icon is specified, styles the icon when the button is depressed. If omitted, the normal state is used when depressed.

<base>_Icon_disabled

If the Icon is specified, styles the icon when the button is disabled. If omitted, the normal state is used when disabled.

Note:
  • In the icon class, if a background-image is supplied for at least the normal case, the icon will be drawn using this background image (whether an explicit icon attribute is set or not). This allows the icon to be specified via CSS only.
  • In the label and icon classes, the style property position determines how the element is positioned within the button. If position is absolute, then left, top, right and bottom can be used to absolutely position the icon or label within the button. If position is relative (the default), then text-align and vertical-align can be used to position the element. text-align supports left, right and center, vertical-align supports top, middle and bottom (only).
  • When using relative positioning, on the label element you can "nudge" the element up/down/left/right using either padding or margin. However, on the icon element (which is an IMG), IE does not support padding so you should use margin. Also, on the icon element, IE does not support a margin of right or top (so to "right-align" two pixels inside the button, use position:absolute positioning and set right:2px).
  • If you set a border on an image button, IE tends to draw the focus rect on top of it, thus the focus rect may not be terribly visible if the border color is dark.
  • As with any JSF component, if you dynamically disable it (that is, you disable it via JS), you need to redraw it after you disable it. (As soon as the button becomes disabled, DHTML stops propagating attribute changed messages, so the button code will not be told the button is disabled and so it will not redraw it without explicitly being told to).

API calls

Table 3. Image API calls

API call

Description

redraw()

Redraw the component taking into account any changes made to the attributes/properties of the base tag.

uirelease()

Releases any active UI associated with the component.

setValue(string)

Sets the value of the component and ensures that the value provided is valid.

object = getValue(boolean)

Retrieves the value of the component. If the boolean is false, this is equivalent to getting the value of the base tag. If the boolean is true, the value is returned as a JavaScriptâ„¢ date/time object instead of as a string.

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Limitations

In a rendered button with an icon or a label, if you press the mouse pointer down while it is over the button, then (with it depressed) you move it off the button, the behavior is does not match the behavior of a standard Windows® button. In Windows, the button can be pressed while the cursor is off the button and nothing happens if you release the mouse button while the cursor is off. However, if you (all while holding down the mouse button), move the cursor back over the button it will re-depress and a mouse-up will cause a click. In a JSF image button, the button is correctly pressed when you move off it. We may or may not be able to depress it again if you move back. In IE, you can click only if the mouse was over the button on the mouse down and is (back) over the button on mouse up. In Mozilla, the behavior is less reliable.

Example code

Add a mouse over image, a depressed image and a click handler to an <img> tag. The images are all specified in CSS.

<style>
.green, .green_moused,  .green_depressed {
    border-width: 0px;
    height: 25px;
    width: 113px;
    background-repeat: no-repeat;
}
.green { background-image: url("img/green-button.gif") }
.green_moused {	background-image: url("img/green-button-moused.gif") }
.green_depressed { background-image: url("img/green-button-depressed.gif") }

<img border='0' class="green" id="image1" src="img/1x1.gif" onclick="return doClick(this, event);">
<script>
hX.addComponent("image1", new hX.JSFImage());
</script>

Add a mouse over effect (emboldening) to a JSF button using CSS

<style>
.button, .button_moused {
    border-width: 2px;
    border-style: solid;
    border-color: black;
    color: black;
    font-weight: normal;
    width: 100px;
}
.button_moused {
    border-color: blue;
    font-weight: bold;
}
</style>

<hx:commandExButton type="submit" styleClass="button" id="button1"></hx:commandExButton>
<script>
hX.addComponent("form1:button1", new hX.JSFImage());
</script>

Add a mouse over image, a depressed image, a disabled image, a label and an icon to an HTML button.

<style>
<script>
.button4a, .button4a_moused, .button4a_depressed {
    width:100px;
    height:21px;
}
.button4a_Label, .button4a_Label_moused, .button4a_Label_depressed {
    font-family: sans-serif;
    color: black;
    font-size: 14px;
    text-align: left;
    margin-left: 24px;
}
.button4a_Label_depressed { margin-left:25px; margin-top:2px; }
.button4a_Icon, .button4a_Icon_moused, .button4a_Icon_depressed {
    text-align: left;
    margin-left: 4px;
    height: 17px;
    width: 17px;
    background-repeat: no-repeat;
}
.button4a_Icon_depressed { margin-top:2px; margin-left:5px; }
</script>
<input type="image" class="button4a" id="button2" name="form1:text21" alt="Search" title="Search" />
<script>
hX.addComponent("form1:button2", new hX.JSFImage("icon-normal:img/search-icon.gif",  
                "icon-moused:img/search-icon-moused.gif", "normal:img/search-button.gif", 
                "moused:img/search-button-moused.gif", "depressed:img/search-button-depressed.gif",
                "label:search"));
</script>

Feedback