webuijsf
Tag alert


Use the webuijsf:alert tag to display an inline alert message at the top of the rendered HTML page. Inline alert messages permit users to correct problems or proceed with their work without having to dismiss a window and navigate to a new location.

HTML Elements and Layout

The alert component includes an icon, a summary message, and an optional detail message. The icon shown is determined by the type attribute, which must be set to information, success, warning, error or one of the developer define types. Alert supports a set of Indicators which enables to define custom types and associated images in addition with default types. Indicators also support the sorting attribute which enables sorting among Indicators depending on the sortValue value. A different icon is shown for each alert type. The icon is determined by the theme or could be a ImageComponent.

The component renders HTML <div> and <table> elements for the alert box and text, with an <img> element for the icon. If you include a link with the alert, an <a> element is also rendered.

Configuring the webuijsf:alert tag

The summary message is specified with the summary attribute, and is displayed prominently next to the icon. The optional detail message is specified with the detail attribute, and is displayed in less prominent text following the summary text. The detail text provides more information about the alert.

You can also include a link to further information or another window by using the linkTarget, linkText, linkToolTip, linkURL, and linkActionExpression attributes. The link is displayed below the detail text.

The icon and link can be overridden with facets.

Facets

The webuijsf:alert tag supports the following facets:

Client Side Javascript Functions

When the Alert component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you call functions on the DOM object. To disable the component, call document.getElementById(id).setProps({detail: "New Detail 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:
  • dir
  • lang
  • detail
  • spacerImage
  • indicators
  • id
  • summary
  • type
  • moreInfo
  • visible

Client Side JavaScript Events

When the component is manipulated on the 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.alert.event.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

webui.suntheme.widget.alert.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.alert.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: An Informational Alert

<webuijsf:alert id="msg1" type="information" summary="Patch Installed Successfully" detail="Patch 9997-01 was successfully installed on host alpha, beta and zed." />

Example 2: An Error Alert with Alert Link

<webuijsf:alert id="msg2" type="error" summary="Patch Installation Failed!" detail="Patch 9997-01 was not installed on host alpha, beta and zed." linkText="View Log" linkURL="/log/patch-log.txt" linkTarget="_blank" linkToolTip="Open Window Containing Error Log"/>

Example 3: Using alertImage facet

<webuijsf:alert id="msg2" type="error" summary="Patch Installation Failed!" detail="Patch 9997-01 was not installed on host alpha, beta and zed.">
    <f:facet name="alertImage">
       <webuijsf:image id="foo"
url="../images/foo.gif" />
    </f:facet>
</webuijsf:alert>

Example 4: Using Developer Define Types

<webuijsf:alert id="alert1" indicators="#{AlertBean.customIndicator}" type="myType" summary="Summary Text" />


Backing Bean for Examples

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

AlertBackingBean.java

 AlertBackingBean {
...
public List getCustomIndicator() {

FacesContext context = FacesContext.getCurrentInstance();
UIComponent comp = context.getViewRoot().findComponent("form1:alert1");
Alert alert = (Alert) comp;

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

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

return lst;
}
...
}
The example above defines "myType" as a custom define type in addition to the default types. 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 Alert Properties Using the getProps and setProps Functions

This example shows how to toggle the visible state of an alert 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 Alert Visible" onClick="toggleVisible()"/>
<webuijsf:alert id="alert1" type="information" summary="#{MyBean.summary}" />

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

Example 6: Asynchronously Update Alert Using Refresh Function - 1

This example shows how to asynchronously update an alert using the refresh function. When the user clicks the radio button, the alert is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Alert" onClick="refreshAlert()"/>
<webuijsf:alert id="alert1" type="information" summary="#{MyBean.summary}" />
<webuijsf:script>
    function refreshAlert() {
        var domNode = document.getElementById("form1:alert1"); // Get alert
        return domNode.refresh(); // Asynchronously refresh alert
    }
</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 Alert Using Refresh Function - 2

This example shows how to asynchronously update a alert using the refresh function. The execute property of the refresh function is used to define the client id which is submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the alert text is updated client-side -- all without a page refresh.
<webuijsf:alert id="alert1" type="information" summary="#{MyBean.summary}" />
<webuijsf:textField id="field1" text="#{MyBean.summary}" label="Change Summary Text"
onKeyPress="setTimeout('refreshAlert();', 0);"/> // Field used to asynchronously update summary.
<webuijsf:script>
    function
refreshAlert() {
        var domNode = document.getElementById("form1:alert1"); // Get alert
        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.AlertTag
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.
summaryfalsefalsejava.lang.String

Summary message text for the alert. This brief message is prominently displayed next to the icon.

linkActionExpressionfalsefalsejava.lang.String

The linkActionExpression attribute is used to specify the action to take when the embedded hyperlink component is activated by the user. The value of the linkActionExpression attribute must be one of the following:

  • An outcome string, used to indicate which page to display next, as defined by a navigation rule in the application configuration resource file(faces-config.xml).
  • A JavaServer Faces EL expression that resolves to a backing bean method. The method must take no parameters and return an outcome string. The class that defines the method must implement the
    java.io.Serializable interface or javax.faces.component.StateHolder interface.

linkToolTipfalsefalsejava.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 link that is specified with linkText.

typefalsefalsejava.lang.String

The type or category of alert. This attribute can be set to "information", "success", "warning" or "error". The selection determines which icon is rendered for the alert.

detailfalsefalsejava.lang.String

Optional detailed message text for the Alert that can include more information about the alert and instructions for what to do about the alert.

indicatorsfalsefalsejava.lang.String

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

linkURLfalsefalsejava.lang.String

Absolute, relative, or context relative (starting with "/") URL to the resource to navigate to when the link that is specified with linkText is selected.

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.

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

The window (target) in which to load the link that is specified with linkText.

styleClassfalsefalsejava.lang.String

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

visiblefalsefalsejava.lang.String

Indicates whether the component should be viewable by the user in the rendered HTML page. If this setting is false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, this setting is true, so HTML for the component HTML is included and visible to the user. If the Alert 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.

linkTextfalsefalsejava.lang.String

The text for an optional link that is appended to the detail message.

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.

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.