The ICEfaces Tutorial
Table of Contents


Lesson: Using the OutputConnectionStatus component

How to Use the ICEfaces OutputConnectionStatus Component

The outputConnectionStatus component displays information about the status of the network connection between the client browser and the server. The component displays one of 4 possible states, which are as follows.

  1. Active: The connection is alive and there is a request pending.
  2. Inactive: The connection is alive and there is no pending activity.
  3. Caution: The connection request/response latency has exceeded the configured threshold. Indicates that asynchronous updates from the server may not be received in a timely manner.
  4. Disconnected: The connection has been lost, either due to network or application error (session expiry, etc.).

The outputConnectionStatus component provides an ideal mechanism to provide continuous real-time feedback to users of the status of their ICEfaces application. It is particularly important to inform users when the application is busy sending and receiving data in response to a user-initiated action to manage their expectations with respect to application readiness for additional user input. Generally, the outputConnectionStatus component should be located in a consistent location throughout an ICEfaces application.

NOTE: A web-page may only contain a single outputConnectionStatus component. Using more than one outputConnectionStatus component on the same web page will result in erratic results.



The rest of this tutorial will cover the following topics:

Creating an outputConnectionStatus component

The creation of an outputConnectionStatus component is a simple one step process. The following code sample shows how to use the component to reflect the current connection status:

<ice:outputConnectionStatus
    cautionLabel="Caution: Connection in danger."
    activeLabel="Active: Working."
    disconnectedLabel="Disconnected."
    inactiveLabel="Active: Idle."
/>

The screen shot below shows the component in action:


outputConnectionStatus with label

Download demo:


Graphical representation of an outputConnectionStatus component

The outputConnectionStatus component can also be graphically represented. The component displays one of four possible states graphically as follows:

connection status component in Component Showcase application

The creation of the outputConnectionStatus component with graphical representation is also simple. The following example code shows how to display the outputConnectionStatus component in two different themes:

<link rel='stylesheet' type='text/css' href='./xmlhttp/css/xp/xp.css'/>
<ice:outputConnectionStatus/>

or,

<link rel='stylesheet' type='text/css' href='./xmlhttp/css/royale/royale.css'/>
<ice:outputConnectionStatus/>

The screen shots below show the two different themes:



outputConnectionStatus XP Style


outputConnectionStatus Royale Style

Download demo:


Customize the style of the outputConnectionStatus component

The style of the outputConnectionStatus component is customizable to a user's preference. As shown in the above examples, the styling and positioning are determined by the css file that comes with the ICEFaces framework:

<link rel='stylesheet' type='text/css' href='./xmlhttp/css/royale/royale.css'/>

You are able to customize the outputConnectionStatus component for different purposes. The example below shows how to customize styling the component so that the component can be use to display a full page overlay of a different translucent colour for each connection state.

To customize the styling of the outputConnectionStatus component you only need to create your own css file and choose the background images. In this example, four transparent images of different colors are used as the outputConnectionStatus component's background image. The example css file is as follows:

 .iceOutConStat {
   border:medium none;
   font-size:2em;
   height:25px;
   margin:10px;
   width:25px;
}
  .iceOutConStatInactive {
    position: absolute;
    left: 0px;
    top: 0px;
    background-image: url( css-images/connect_idle.gif );
    background-position: 0px 0px;
    background-repeat: repeat;
    width: 100%;
    height: 100%;
}

.iceOutConStatActive {
    position: absolute;
    left: 0px;
    top: 0px;
    background-image: url( css-images/connect_active.gif );
    background-position: 0px 0px;
    background-repeat:  repeat;
    width: 100%;
    height: 100%;
}

.iceOutConStatCaution {
    position: absolute;
    left: 0px;
    top: 0px;
    background-image: url( css-images/connect_caution.gif );
    background-position: 0px 0px;
    background-repeat: repeat;
    width: 100%;
    height: 100%;
}

.iceOutConStatDisconnect {
    position: absolute;
    left: 0px;
    top: 0px ;
    background-image: url( css-images/connect_disconnected.gif );
    background-position: 0px 0px;
    background-repeat:  repeat;
    width: 100%;
    height: 100%;
}

Specify the css file for the customized outputConnectionStatus with the following line:

<link rel='stylesheet' type='text/css' href='style.css'/>

The screen shots below shows how the component switches background color as the connection state changes.


outputConnectionStatus Custom Style Idle


outputConnectionStatus Custom Style Disconnected

Download the demo:


Examples Using OutputConnectionStatus Component

Example Source Notes
connectionStatus-label connectionStatus-label source code Simple example of how to setup a basic outputConnectionStatus component with label.
connectionStatus-xp connectionStatus-xp source code Example showing how to setup an outputConnectionStatus component with XP style theme
connectionStatus-royale connectionStatus-royale source code Example showing how to setup an outputConnectionStatus component with royale style theme
connectionStatus-customize connectionStatus-customize source code Custom styling the outputConnectionStatus component that displays transparent background images in different color when the connection state changes

The ICEfaces Tutorial
Table of Contents

Copyright 2006 ICEsoft Technologies Inc. All rights reserved.