GrowlMessages

Overview

Since 4.0

The ace:growlMessages component renders Faces messages in a Growl container. This component will provide the user with a popup notifiaction panel, similar to the OS X Growl component. The container can be positioned on one of the four corners of the browser window. A message can auto-hide based on its severity level. Other attributes control the close-all button (close visible messages only, not hidden messages), display duration of auto-hide messages, no. of messages visible at a time, etc.

Since 4.2

The ace:growlMessages component can also render Faces messages as native browser notifications. See the Known Issues section below for details on supported platforms.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

To use the growlMessages component, first the ace component name-space has to be added in your page.

<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">

Now you ready to use growlMessages component, here is the basic example:

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

Define the model of this component:

The position attribute designates a class which is applied to the growl container and controls its position on the screen. Options: top-left, top-right, bottom-left, bottom-right.", defaultValue = "top-right".

The forValue attribute identifies the component for which to render the error messages. If it within the same naming container as the target, use component id, otherwise, must use absolute JSF component id (":"). Default is "@all". If it is desired to only have messages for those components within the current view, use "@inView",

The maxVisibleMessages limits the number of messages appearing at a given time. Default is 0, no upper limit.

The escape attribute is a flag indicating that characters that are sensitive in HTML and XML markup must be escaped. Defaults to true.

The header attribute allows a header to prefix a message

The autoHide attribute allows to select messages to auto hide after display. Value of "true" autohides all messages. Value of "false" does not hide any messages. Other types are "info", "warn", "error", or "fatal".

The messageOrder attribute designates whether a notification should be appended to the container after all notifications, or whether it should be prepended to the container before all notifications. Options are "after" or "before". defaultValue = "after".

The displayDuration attribute denotes the lifespan in ms of an auto-hide message on the screen. The default value is 3000ms.

The closeAll attribute denotes whetehr or not the close-all button should be used when more than one notification appears on the screen

The showEffectDuration attribute (aka speed in jQuery) shows duration of the show effect. The default value is "slow"

The hideEffectDuration attribute values and default same as showEffectDuration.

The useNativeNotifications attribute enables native browser notifications instead of using Growl notifications.

When native browser notifications are used only the following attributes are effective: forValue and header. The remaining attributes that control how the messages are rendered are replaced by the operating system's native notification system.

Client Behavior Events

No direct client behavior is currently associated with this component.

JavaScript API

ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the widgetVar attribute.

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

var widget = ice.ace.instance('frm:componentId);

The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).

This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

Keyboard Support

NA

CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<!-- Root container -->
<div class="top-right jGrowl">
	<div class="jGrowl-notification"></div>
	<!-- Message -->
	<div class="jGrowl-notification ui-state-highlight ui-corner-all default">
		<!-- Close message button -->
		<div class="jGrowl-close">
			<span class="ui-icon ui-icon-circle-close"></span>
		</div>
		<!-- Message header -->
		<div class="jGrowl-header"></div>
		<!-- Message body -->
		<div class="jGrowl-message">
			<span class="ui-icon ui-icon-info"></span>Info Sample
		</div>
	</div>
	<!-- Close all button -->
	<div class="jGrowl-closer ui-state-highlight ui-corner-all default">close all</div>
</div>

Known Issues

The native notifications feature ("useNativeNotifications='true'") is supported by the following platform/browser combinations:

Apple Safari 6+ on OSX 10.8+ and iOS
Google Chrome 32+ (Desktop only)
Microsoft Edge on Windows 10+
Mozilla Firefox 22+

Additional Resources

Tutorials

This component appears in the following ICEfaces tutorials:

None