Browser Information and Control

From Documentation
Revision as of 08:43, 19 November 2010 by Tomyeh (talk | contribs) (Created page with '{{ZKDevelopersReferencePageHeader}} To retrieve the information about the client, you can register an event listener for the <tt>onClientInfo</tt> event to a root component. To c…')
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Browser Information and Control


To retrieve the information about the client, you can register an event listener for the onClientInfo event to a root component. To control the behavior of the client, you can use the utilities in the Clients class.

The onClientInfo Event

Sometimes an application needs to know the client's information, such as time zone. Then, you can add an event listener for the onClientInfo event. Once the event is added, the client will send back an instance of the ClientInfoEvent class, from which you can retrieve the information of the client.

For example,

<grid onClientInfo="onClientInfo(event)">
    <rows>
        <row>Time Zone <label id="tm"/></row>
        <row>Screen <label id="scrn"/></row>
    </rows>

    <zscript>
     void onClientInfo(ClientInfoEvent evt) {
         tm.setValue(evt.getTimeZone().toString());
         scrn.setValue(
             evt.getScreenWidth()+"x"+evt.getScreenHeight()+"x"+evt.getColorDepth());
     }
    </zscript>
</grid>

Notice that the onClientInfo event is meaningful only to the root component (aka., a component without any parent).

The client information is not stored by ZK, so you have to store it manually if necessary. Since a session is associated with the same client, you can store the client info in the session's attribute.

For example, we coud use it to control the default time zone[1].

 session.setAttribute("org.zkoss.web.preferred.timeZone", event.getTimeZone());

Notice that the onClientInfo event is sent from the client after the page is rendered (and sent to the client). Thus, if some of your component's data depends on the client's info, say, time zone, you might have to ask the client to re-send the request as follows.

 import org.zkoss.util.TimeZones;
 ...
 if (!TimeZones.getCurrent().equals(event.getTimeZone())
     Executions.sendRedirect(null);

  1. For more information about time zone, please refer to the Time Zone section.

The org.zkoss.ui.util.Clients Class

Utilities to control the client's visual presentation (more precisely, the browser window) are put in Clients collectively. For example, you can scroll the browser window (aka., the desktop) as follows.

 Clients.scrollBy(100, 0);

Prevent User From Closing a Browser Window

In some situation, you might want to prevent or, at least, alert a user when he tries to close the window or browse to another URL. For example, when a user is composing a mail that is not saved yet.

 if (mail.isDirty()) {
     Clients.confirmClose("Your message has not been sent.\nDiscard your message?");
 } else {
     Clients.confirmClose(null);
 }

Once the confirmClose method is called with a non-empty string, a confirmation dialog is shown up when the user tries to close the browser window, reload, or browse to another URL:

100000000000036D000000FE561CE3BC.png

Version History

Last Update : 2010/11/19


Version Date Content
     



Last Update : 2010/11/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.