com.smartgwt.client.docs

Interface DataSourceLocalization

public interface DataSourceLocalization

DataSource and Component XML Localization

DataSources which are declared in XML (.ds.xml files) and are read by the Smart GWT server, which are normally loaded by the DataSourceLoader servlet, can instead be internationalized using an approach similar to the internationalization of JSP files with JSTL tags. This approach is also supported for screens defined using Component XML.

Note: The tags we use for internationalizing Smart GWT XML files look like standard JSTL tags; this is intentional, simply because developers are familiar with JSTL. However, the tags are being processed by Smart GWT code, not JSTL, so only the specific tags documented here are supported.

Given the following DataSource located in /shared/ds/supplyItem.ds.xml:

  <DataSource ID="supplyItem">
      <fields>
          <field name="itemName">
              <title>Item Name</title>
              <validators>
                  <Validator type="lengthRange" max="40">
                      <errorMessage>Must be 40 characters or less.</errorMessage>
                  </Validator>
              </validators>
          </field>
      </fields>
  </DataSource>
  

To localize the title and validator error string of the itemName field, change the DataSource definition as follows:

  <DataSource ID="supplyItem" xmlns:fmt="WEB-INF/">
      <fields>
          <field name="itemName">
              <title><fmt:message key="itemTitle"/></title>
              <validators>
                  <Validator type="lengthRange" max="40">
    <errorMessage><fmt:message key="itemLengthRangeValidator"/></errorMessage>
                  </Validator>
              </validators>
          </field>
      </fields>
  </DataSource>
  

This will cause Smart GWT Server to look for a ResourceBundle called "supplyItem", containing keys "itemTitle" and "itemLengthRangeValidator", and replace the <fmt:message> tags with the values from the resource bundle in the expected way. It obtains the user's Locale from the servlet request, but you can override this if you want to force an application-specific locale, regardless of the user's operating system settings. To do this, specify a "locale" parameter on HTTP requests to the DataSourceLoader and IDACall servlets.

The locale parameter should be an underscore-separated string conforming to the rules described in this article on Java internationalization. For example, "fr" (French language) or "en_US" (English language, US location).

As mentioned, Smart GWT Server will look for a ResourceBundle called "supplyItem" in this case because it defaults to the name of the DataSource. It is possible to override this default at both the DataSource and field levels:

• Specify <fmt:bundle> as a top-level DataSource tag, like this:
  

     <DataSource  xmlns:fmt="WEB-INF/" ID="supplyItem">
         <fmt:bundle basename="com.isomorphic.test.i18n" />
         ...
    </DataSource>

• Specify the bundle name in the individual <fmt:message> tags, like this:
  

     <title><fmt:message key='title1' bundle="com.mycompany.MyProperties"
   /></title>

When you name a resource bundle manually like this, if you qualify the name it influences where we expect to find that resource bundle. In the above example, we would look in the com.mycompany package. For unqualified names (including the default of the DataSource name that we use in the absence of an override), we look in the so-called "default package", which corresponds to the root of your classes directory or the root of a .JAR file.

Note that the xmlns:fmt attribute in the DataSource definition is required by the XML parser if you intend to use our fmt:message features. However, the actual value you use is unimportant as long as it is present.

Although these examples don't show it, note that it is also possible to internationalize DataSource-level values in the same way as field-level values - for example:

    <DataSource  xmlns:fmt="WEB-INF/" ID="i18nTest"> 
      <title><fmt:message key="dsTitle" /></title>
       ...
  </DataSource>
  

Component XML

All of the above applies similarly for localizing screens defined using Component XML. For example:

  <isomorphicXML xmlns:fmt="WEB-INF/">
    <fmt:bundle basename="com.isomorphic.test.i18n.test" />
    <Window ID="testWin1">
      <title><fmt:message key='title1' /></title>
    </Window>
  </isomorphicXML>
  

Note the following differences between localizing .ds.xml (DataSource) files and localizing .ui.xml (component XML) files:

• The <isomorphicXML> tag, which is ordinarily only used to wrap multiple widget definitions to give a valid XML file, is required if you are using this internationalization technique.
• Because there is no concept of an "ID" associated with a .ui.xml file, there is no default bundle like there is with DataSource definitions. Instead, you have to specify the bundle by hand, either by adding a <fmt:bundle> tag as an immediate child of the <isomorphicXML> tag, or by specifying bundle attributes in your individual <fmt:message> tags.
• Locale can be overridden, as described for DataSources above, by specifying a "locale" parameter on HTTP requests to the ScreenLoaderServlet (this is done for you when you pass a locale to the RPCManager.loadScreen() method).