XPages supports different time zones, so dates can be displayed in the user's local time, using the server's time zone, or using a programmatically configured time zone.
The time zone is used when displaying date objects as text. The date objects contain the universal region-independent time (e.g. 1pm in London today, saved in milliseconds), and the current time zone is used to display the time, so for example, it knows to display the date as 8am EST when the web server is located in the east of the USA. By default, in XPages the server time zone is used. So if you have users in different time zones, the exact same time is shown to each user, instead of the local time for that user. There is an option to use the user's browser time zone, instead of the server's, so that users see their local time.
As well as detecting either browser and or server time zones, you can programmatically change a user session to any time zone. There is also an option to make individual edit boxes and computed fields display in a particular time zone.
In 8.5.1, there is a problem using browser time zones. The fix is available in
8.5.1 Fix Pack 1. With browser time zones enabled, an edit box will always display dates using the GMT time zone. The Date Time converter, used to display dates in an edit box or computed field, can no longer handle the custom time zones produced when detecting the browser time zone. The issue is tracked as MKEE7V9F82.
Configuring the Time Zone
The option to use the Server or Browser time zone can be set in different places, depending on whether you want all Applications on the server to use the browsers' time zones, or just one particular Application.
To change the time zone option for the entire Server
As the default time zone for XPages is the server's time zone, you may want to change this to be the users' browser time zones. You can change this for every application on the server in the xsp.properties file on your server machine.
Open the xsp.properties file.
In
8.5, the file is \Domino\xsp\nsf\xsp.properties
In
8.5.1 and later, the file has moved. You need to rename this file to xsp.properties: \Domino\data\properties\xsp.properties.sample
Go to the User Preferences section of the file. You will notice that these options are currently commented out.
# #######################################
# USER PREFERENCES
# #######################################
# Defines the timezone to use
# When not specified, it computes the timezone from the user browser.
#xsp.user.timezone=false
#xsp.user.timezone.redirect=true
Note, the comment is incorrect; it actually uses the server time zone by default, rather than the user browser's time zone (issue #MKEE7V9EEQ).
To change to use the browser's time zone, change the line
to remove the # and change the value to true:
Save the xsp.properties file and restart the server to pick up the change.
The second setting is incorrectly named as .redirect instead of .roundtrip (issue #MKEE7W6D6N). It should be:
#xsp.user.timezone.roundtrip=true
That setting can sometimes be changed as an optimization. The round-trip it refers to is part of how XPages detects the browser time zone. The time zone information is not automatically passed by the browser to the server. So XPages computes a time zone using a piece of JavaScript in a temporary page, then submits the result to the server, and redirects to the actual XPage. The piece of JavaScript produces a rough guess of the time zone, so it will find GMT+5 instead of "America/New_York". If the first XPage in your application does not use any time zone information, then you can change the setting to avoid the temporary page, and prevent that round-trip to the server. In that case, the piece of JavaScript is output in the first XPage you open, and the browser time zone is only available after the user submits for the first time.
To change the Time Zone option for an Application
The time zone used by an Application can be changed in the Applications Properties.
Open the Application Properties by selecting your Application in the Applications view in Domino Designer and in the menus choose "File", "Application", "Properties".
Select the XPages Tab. Here you will see 3 options:
The default is the Server Default which means the setting in the xsp.properties file for "xsp.user.timezone=" will be used.
If your Server Default is the Server time zone, you can change the time zone setting here on an Application level to 'Browser' by selecting the 'Browser' radio button.
Or if your Server Default is the user's Browser time zone, then selecting the 'Server' radio button here will mean your application is now using the Server's time zone.
Programmatic access to the Time Zone
The context object is used to access the Time Zone. You can create a Java TimeZone object and set it as the current time zone. The time zone value set is used for the current user session. It is discarded after the session has timed out. It is not necessary to reload the page after changing the time zone. The time zones are IDs defined by the java.util.TimeZone class, like
"America/Los_Angeles". Not all common names for time zones are supported, so you may need to refer to that class. It also describes the custom time zone syntax, for example,
"GMT+5" means 5 hours ahead of GMT. The time zone methods on the context object are:
getTimeZone() : TimeZone
getTimeZoneString() : string
setTimeZone(timeZone:TimeZone)
setTimeZoneString(timeZone:string)
Also, the server time zone is always available through the I18n library, like so:
I18n.getServerTimeZone(): TimeZone
An example:
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:label value="The current timeZone is:" id="label1"
for="computedField1"></xp:label> 
<xp:text escape="true" id="computedField1"
value="#{javascript:context.getTimeZone()}"></xp:text>
<xp:br></xp:br>
Local time is: 
<xp:text escape="true" id="computedField2"
value="#{javascript:@Now()}">
<xp:this.converter>
<xp:convertDateTime type="time"></xp:convertDateTime>
</xp:this.converter>
</xp:text>
<xp:br></xp:br>
<xp:button value="to LA" id="button1">
<xp:eventHandler event="onclick" submit="true"
refreshMode="complete">
<xp:this.action>
<xp:executeScript
script="#{javascript:context.setTimeZoneString('America/Los_Angeles');}">
</xp:executeScript>
</xp:this.action>
</xp:eventHandler>
</xp:button>
</xp:view>
The converter timeZone option
The time zone can be set for an individual Edit Box or Computed Field. First check in the Properties view, Data tab, that the display type is set to Date/Time. Then in the All Properties tab, the Data category, configure the converter's timeZone property.
An example:
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:label value="Current time in New York:" id="label1"
for="computedField1"></xp:label>
<xp:text escape="true" id="computedField1" value="#{javascript:@Now()}">
<xp:this.converter>
<xp:convertDateTime type="time" timeZone="America/New_York">
</xp:convertDateTime>
</xp:this.converter>
</xp:text>