Walkthrough: Globalizing a Date by Using Client Script

In this walkthrough you will use ECMAScript (JavaScript) to display days, months, and other date-related values in globalized formats. The AJAX functionality in ASP.NET provides client globalization support based on a setting in the ScriptManager control. After these globalization settings have been applied to the Web application, you can use client script to format a JavaScript Date or Number object based on a culture value. This does not require a postback to the server.

The culture value that is used by the client script is based on the default culture setting provided by the user's browser settings. Alternatively, it can be set to a specific culture value by using server settings or server code in your application.

A culture value provides information about a specific culture (locale). The culture value is a combination of two letters for a language and two letters for a country or region. Examples include es-MX (Spanish Mexico), es-CO (Spanish Columbia), and fr-CA (French Canada).

The ASP.NET AJAX Date extensions add functionality to the JavaScript Date object by providing the localeFormat method. This method enables a Date object to be formatted based on the browser language setting, on server settings, or on server code. These settings affect the server culture value, which is then interpreted by the server to generate a client object that is exposed by the Sys.CultureInfo.CurrentCulture property. This object is used for formatting dates.

For more information about cultures and locales, see ASP.NET Globalization and Localization and the CultureInfo class overview.

Prerequisites

To implement the procedures in your own development environment you need:

  • Microsoft Visual Studio 2005 or Microsoft Visual Web Developer Express.

  • An AJAX-enabled ASP.NET Web site.

Globalizing a Date Based on Browser Settings

To begin, you will use the language preference settings in the browser to specify how to format a date.

To globalize a date based on the browser language preference

  1. Close any open instances of Microsoft Internet Explorer or of your default browser so that all new instances will use a new locale setting.

  2. Open a new instance of Internet Explorer.

  3. On the Tools menu, click Internet Options, click the General tab, and then click Language.

  4. Set the language preference to es-MX (Spanish Mexico) and remove any other locales from the list.

    Note

    If you use a different browser, make the equivalent language settings in that browser.

  5. Close the browser.

  6. In Visual Studio, create or open an ASP.NET AJAX-enabled Web page and switch to Design view.

  7. Select the ScriptManager control and set its EnableScriptGlobalization property to true.

    Note

    If the page does not contain a ScriptManager control, add one from the AJAX Extensions tab of the Toolbox.

  8. In the AJAX Extensions tab of the Toolbox, double-click the UpdatePanel control to add an update panel to the page.

  9. Set the ChildrenAsTriggers property of the UpdatePanel control tofalse.

  10. Set the UpdateMode property of the UpdatePanel control to Conditional.

  11. Click inside the UpdatePanel control, and then from the Standard tab of the Toolbox, add a Button control and a Label control to the UpdatePanel control.

    Note

    Make sure that you add the Label and Button controls inside the UpdatePanel control.

  12. Make sure that the button's ID property is set to Button1, and set its Text property to Display Date.

  13. Make sure that the label's ID property is set to Label1.

  14. Switch to Source view.

  15. At the bottom of the page, create a script element and add the following client script to it:

    Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
    function formatDate() {
      var d = new Date();
      try {
        $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
      }
      catch(e) {
        alert("Error:" + e.message);
      }
    }
    
    Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
    function formatDate() {
      var d = new Date();
      try {
        $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
      }
      catch(e) {
        alert("Error:" + e.message);
      }
    }
    

    This code adds a click handler to the button named Button1. The code calls the formatDate function, which creates a new Date object and displays the formatted date in the element named Label1. The date is formatted by using the localeFormat function that is part of the Microsoft AJAX Library extensions for the Date object.

  16. In the Web site's Web.config file, include the following globalization element in the system.web section:

    <globalization culture="auto" />
    

    The "auto" setting specifies that the ACCEPT-LANGUAGE header in the browser request (which provides the user's language preference list) is used to set the culture value.

  17. Save your changes, and then run the Web page in the browser where you changed language settings.

  18. Click the Display Date button to see the globalized date value that is based on the browser language settings.

    The following example shows a complete ASP.NET Web page with client script that globalizes a date based on the browser language preference.

    <%@ Page Language="VB" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                             UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    
    <%@ Page Language="C#" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                             UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    
  19. When you are finished, reset the language settings in the browser.

Globalizing a Date Based on Configuration Settings

If you want to display formatted dates in multiple pages, you can set the culture in the Web site's configuration file. The format settings then apply to dates in all pages.

To globalize a date based on configuration file settings

  1. In the Web.config file of the application, change the globalization element in the system.web section to the following:

    <globalization culture="fr-CA" />
    

    This setting sets the culture value to "fr-CA" (French Canada), regardless of what the browser language setting specifies.

  2. Save your changes, and then run the Web page in your browser.

  3. Click the Display Date button to see the globalized date value.

    The date formatting is now based on the culture attribute in the configuration file instead of on the browser language preference.

    The following example shows a complete ASP.NET Web page with client script that globalizes a date based on configuration file settings.

    <%@ Page Language="VB" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                 UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    
    <%@ Page Language="C#" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                             UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    

Globalizing a Date Based on Page Settings

To set the culture for an individual page, you can use the Culture attribute of the @ Page directive. The Culture attribute of the @ Page directive takes precedence over the setting in the configuration file and over the browser's language settings.

To globalize a date based on a page setting

  1. In the page you are working with, modify the @ Page directive to set the culture value to "de-DE" (German Germany), as shown in the following example:

    <%@ Page Language="C#" AutoEventWireup="true" Culture="de-DE" %>
    
  2. Save your changes, and then run the Web page in the browser.

  3. Click the Display Date button to see the globalized date value.

    The date formatting is now based on the Culture attribute of the @ Page directive.

    The following example shows a complete ASP.NET Web page with client script that globalizes a date based on a page setting.

    <%@ Page Language="VB" Culture="de-DE" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                 UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    
    <%@ Page Language="C#" Culture="de-DE" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                 UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    

Globalizing a Date Programmatically

If you want to programmatically set the culture value for a page, you can override the page's InitializeCulture method in server code. The InitializeCulture method takes precedence over culture settings in the @ Page directive, in the configuration file, and in the browser.

To globalize a date programmatically

  1. Add the following method to the page:

    ProtectedOverridesSub InitializeCulture()
            Me.Culture = "it-IT"EndSub
    
    protectedoverridevoid InitializeCulture()
    {
        this.Culture = "it-IT";
    }
    

    This code overrides the InitializeCulture method of the base Page class and sets the culture value to "it-IT" (Italian Italy). This is the appropriate time in the page life cycle to change the culture programmatically.

  2. Save your changes, and then run the Web page in the browser.

  3. Click the Display Date button to see the globalized date.

    The date value is now being formatted based on server code.

    The following example shows a complete ASP.NET Web page with client script that globalizes a date programmatically.

    <%@ Page Language="VB" Culture="de-DE" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <script runat="server">
        ProtectedOverridesSub InitializeCulture()
            Me.Culture = "it-IT"EndSub
    </script>
    
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                 UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    
    <%@ Page Language="C#" Culture="de-DE" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN""http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    <script runat="server">
            protectedoverridevoid InitializeCulture()
            {
                this.Culture = "it-IT";
            }
    </script>
    
    <html xmlns="http://www.w3.org/1999/xhtml">
    
    <head runat="server">
        <title>Globalization Example</title>
    </head>
    <body>
        <form id="form1" runat="server">
            <asp:ScriptManager ID="ScriptManager1" runat="server" EnableScriptGlobalization="true"/>
            <asp:UpdatePanel ID="UpdatePanel1" runat="server" ChildrenAsTriggers="False" 
                 UpdateMode="Conditional">
                <ContentTemplate>
                       <asp:Panel ID="Panel1" runat="server" GroupingText="Update Panel">
                       <asp:Button ID="Button1" runat="server" Text="Display Date" />
               <br />
                       <asp:Label ID="Label1" runat="server"></asp:Label>
                       </asp:Panel>
                </ContentTemplate>
            </asp:UpdatePanel>
        </form>
    </body>
    </html>
    
    <script type="text/javascript">
        Sys.UI.DomEvent.addHandler($get("Button1"), "click", formatDate);
        function formatDate() {
          var d = new Date();
          try {
            $get('Label1').innerHTML = d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss");
          }
          catch(e) {
            alert("Error:" + e.message);
          }
        }
    </script>
    

Formatting Patterns

The localeFormat method can accept a variety of formatting patterns. For more information about date and time string formats, see Sys.CultureInfo Class.

See Also

Tasks

How to: Set the Culture and UI Culture for ASP.NET Web Page Globalization

Other Resources

ASP.NET Globalization and Localization