webuijsf
Tag alarm


Use the webuijsf:alarm tag to display a theme-specific alarm image in the rendered HTML page. The webuijsf:alarm tag can be used anywhere that an image can be displayed. Alarm images are useful in pages and tables that display the status of devices.

HTML Elements and Layout

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

Configuring the webuijsf:alarm tag

Use the severity attribute to specify the alarm severity, which determines the theme-specific alarm icon to render. The Alarm supports a set of Indicators which enables you to define custom types and associated images in addition to default types. Indicators also support the sorting attribute which enables sorting among Indicators depending on the sortValue value.

The text attribute is used to specify the text to be displayed next to the alarm icon, and the textPosition attribute specifies whether the text should be displayed to the left or right of the icon.

The url attribute can be used to override the theme-specific alarm icon. The image that you specify with the url attribute is always rendered, even if a severity is not specified. If you specify a theme key with the icon attribute, you must also specify a standard severity. If you do not specify a severity, the component will assume default severity. The icon is coupled with the severity, while the url is not. If you specify an icon attribute as well as a url attribute, the image specified by the url takes precedence over the image specified by the icon attribute.

Other image-related attributes, such as border, height, and width, can also be specified with the webuijsf:alarm tag attributes to override the image attributes of the icon.

Facets

None.

Theme Identifiers

The Theme provides the following alarm icon identifiers.

 DOWN_ALARM_INDICATOR
CRITICAL_ALARM_INDICATOR
MAJOR_ALARM_INDICATOR
OK_ALARM_INDICATOR
ALARM_CRITICAL_SMALL
ALARM_CRITICAL_MEDIUM
ALARM_MAJOR_SMALL
ALARM_MAJOR_MEDIUM
ALARM_MINOR_SMALL
ALARM_MINOR_MEDIUM
ALARM_DOWN_SMALL
ALARM_DOWN_MEDIUM
ALARM_MASTHEAD_CRITICAL_MEDIUM
ALARM_MASTHEAD_DOWN_MEDIUM
ALARM_MASTHEAD_MAJOR_MEDIUM
ALARM_MASTHEAD_MINOR_MEDIUM

Client-Side JavaScript Functions

When the Alarm component is rendered, a DOM object corresponding to the component is created. To manipulate the Alarm component on the client side, you can call functions on the DOM object. To disable the component, call document.getElementById(id).setProps({text: "New Alarm Text"}).

getProps() Use this function to get widget properties. 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:
  • className
  • dir
  • indicators
  • id
  • lang
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • style
  • text
  • textPosition
  • title
  • type
  • visible

Client-Side JavaScript Events

When the component is manipulated client side, some functions might publish event topics for custom Ajax implementations to listen for. Using the Dojo event system, you can instruct Ajax to listen for the refresh event topic by using:

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

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


</webuijsf:script>

The following events are supported.

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

Code Examples

Example 1: Alarm with Critical Severity.

<webuijsf:alarm id="alarm1" severity="critical" />

Example 2: Alarm with Major Severity Overriding the Alarm Image.

 <webuijsf:alarm id="alarm2" 
severity="major"
url="../images/major.gif"
height="10"
width="10"
alt="Processor Alarm:Major" />

Example 3: Using Alarms in a Table

See the Examples section in the documentation for the webuijsf:tableColumn component.

Example 4: Developer Define Types

<webuijsf:alarm id="alarm1" indicators="#{AlarmBean.customIndicator}" severity="mySeverity" text="Custom severity" />


Backing Bean for Examples

The AlarmBackingBean.java backing bean is used the examples above.

AlarmBackingBean.java

 AlarmBackingBean {
...
public List getCustomIndicator() {

FacesContext context = FacesContext.getCurrentInstance();
UIComponent comp = context.getViewRoot().findComponent("form1:alarm1");
Alarm alarm = (Alarm) comp;

Indicator indicator = new Indicator("ALARM_CRITICAL_SMALL", "mySeverity", 600);

List lst = Alarm.getDefaultIndicators();
lst.add(indicator);

return lst;
}
...
}
The example above defines "mySeverity" as a custom define severity in addition to the default severities. An Indicator object can be constructed by calling any Indicator constructors.

Indicator(String imageKey, String type, int sortValue)
or Indicator(UIComponent imageComponent, String type, int sortValue)

The third parameter of constructor enables sorting for Indicators.

Example 5: Update Client-Side Alarm Properties Using the getProps And setProps Functions

This example shows how to toggle the visible state of an alarm client side using the getProps and setProps functions. When the user clicks the radio button, the button is either shown or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Alarm Visible" onClick="toggleVisible()"/>
<webuijsf:alarm id="alarm1" severity="major" text="#{MyBean.text}" />

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

Example 6: Asynchronously Update Alarm Using Refresh Function

This example shows how to asynchronously update an alarm using the refresh function. When the user clicks the radio button, the alarm is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Alarm" onClick="refreshAlarm()"/>
<webuijsf:alarm id="alarm1" severity="major" text="#{MyBean.text}" />
<webuijsf:script>
    function refreshAlarm() {
        var domNode = document.getElementById("form1:alarm1"); // Get alarm
        return domNode.refresh(); // Asynchronously refresh alarm
    }
</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 only using values set server-side.

Example 7: Asynchronously Update Alarm Using Refresh Function

This example shows how to asynchronously update an alarm 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 alarm text is updated client-side -- all without a page refresh.
<webuijsf:alarm id="alarm1" severity="major" text="#{MyBean.text}" />
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Text"
onKeyPress="setTimeout('refreshAlarm();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshAlarm() {
        var domNode = document.getElementById("form1:alarm1"); // Get alarm
        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 on the server-side: refresh("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.AlarmTag
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 that is executed when the user presses a mouse button while the mouse pointer is on the component.

onDblClickfalsefalsejava.lang.String

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

onKeyPressfalsefalsejava.lang.String

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

severityfalsefalsejava.lang.String

Specifies the severity of the alarm. Valid values are:

  • critical
  • major
  • minor
  • down
  • ok
The default value is "ok", which renders no alarm icon.

indicatorsfalsefalsejava.lang.String

A developer define types of Alarm. This attribute can be set to an array of Indicators where Indicator holds the custom defined type and associated image.

onMouseOutfalsefalsejava.lang.String

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

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

idfalsetruejava.lang.StringNo Description
onMouseOverfalsefalsejava.lang.String

Scripting code that is 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.
onKeyUpfalsefalsejava.lang.String

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

onMouseMovefalsefalsejava.lang.String

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

onMouseUpfalsefalsejava.lang.String

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

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

textfalsefalsejava.lang.String

The text description of the alarm.

visiblefalsefalsejava.lang.String

Indicates 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, is true, so HTML for the component HTML is included and visible to the user. If the Alarm component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

stylefalsefalsejava.lang.String

CSS style or styles to be applied to the outermost HTML element when this component is rendered.

onKeyDownfalsefalsejava.lang.String

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

onClickfalsefalsejava.lang.String

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

textPositionfalsefalsejava.lang.String

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

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.

longDescfalsefalsejava.lang.String

A verbose description of this image.

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.

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.

iconfalsefalsejava.lang.String

The identifier of the desired theme image.

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.

urlfalsefalsejava.lang.String

Absolute or relative URL to the image to be rendered.

borderfalsefalsejava.lang.String

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


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.