<?xml version="1.0" encoding="UTF-8"?>
<chapter>
  <chapterinfo>
    <keywordset>
      <keyword>a4j:loadBundle</keyword>
    </keywordset>
  </chapterinfo>
     <table>
	  <title>Component identification parameters </title>
      <tgroup cols="2">
	  <thead>
            <row>
                  <entry>Name</entry>
                  <entry>Value</entry>
            </row>
        </thead>
        <tbody>
          <row>
            <entry>component-type</entry>
            <entry>org.ajax4jsf.Bundle</entry>
          </row>
          <row>
            <entry>component-family</entry>
            <entry>org.ajax4jsf.Bundle</entry>
          </row>
          <row>
            <entry>component-class</entry>
            <entry>org.ajax4jsf.component.html.AjaxLoadBundle</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  
      <section>
            <title>Creating the Component with a Page Tag</title>
            <para>
                  To create the simplest variant on a page use the following syntax:
            </para>
            <para>
                  <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[<a4j:loadBundle baseName="demo.bundle.Messages" var="Message"/>]]></programlisting>
      </section>
      
      <section>
            <title>Creating the Component Dynamically Using Java</title>
            <para>
                  <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.AjaxLoadBundle;
...
AjaxLoadBundle myBundle = new AjaxLoadBundle();
...]]></programlisting>
      </section>
      
      <section>
            <title>Details of usage</title>
            <para>
                  Internationalization and Localization are the processes of adaptation of web applications for different languages and cultures. 
                  When you develop English and German versions of a site it can be said that you localize the site for England and Germany. 
                  Language is not the only thing that undergoes the localization — dates, times, numbers, currencies, phone numbers, addresses, graphics, icons, colors, personal titles and even favourite sounds are also varies from country to country. 
                  It means that an internationalized application may have lots of different types information, which should be changed depending on user location. 
            </para>
            <para>
                  There are several approaches of organizing the localization. 
                  The JSF <emphasis role="bold"><property>&lt;h:loadBundle&gt;</property></emphasis> loads bundles into the request scope when page is being rendered and updates all the needed areas in a crowd. 
                  Bundle information loaded in such way becomes unavailable when dealing with Ajax requests that work in their own request scopes. 
                  The approach provided by RichFaces <emphasis role="bold"><property>&lt;a4j:loadBundle&gt;</property></emphasis> component enriches one given by the JSF <emphasis role="bold"><property>&lt;h:loadBundle&gt;</property></emphasis> with Ajax capability: 
                  it allows to use reference to a particular bundle item during an Ajax update.
            </para>
            <para>
                  The <emphasis role="bold"><property>&lt;a4j:loadBundle&gt;</property></emphasis> usage is pretty simple. 
                  Imagine a small application that says &quot;Hello!&quot; in different languages, where switching between translations (localizations, in our case) occurs when corresponding links are being clicked, like you have used to see on lots of sites. 
                  In our JSF with RichFaces application (those who feel not strong with that should better read the &quot;<link linkend="GettingStarted">Getting started with RichFaces</link>&quot; chapter) create resource bundles with &quot;Hello!&quot; message for three different languages: English, German and Italian. 
                  Resource bundles are represented with <code>*.properties</code> extention files that keep items in <code>key(name) - value</code> pairs. 
                  A key for an item should be the same for all locales. 
            </para>
            <figure>
                  <title>
                        Resource bundles <code>*.properties</code> files with Keys and Values for multi-language application. 
                  </title>
                  <mediaobject>
                        <imageobject>
                              <imagedata fileref="images/loadBundle_init.png"/>
                        </imageobject>
                  </mediaobject>
            </figure>
            <para>
                  Мessage resource bundles should be registered in the Faces configuration (<code>faces-config.xml</code>) file of your application as <code>&lt;message-bundle&gt;</code> inside the <code>&lt;application&gt;</code> element. 
                  Name of a resource should be specified without language or country code and without <code>.properties</code> extension. 
                  Supported locales should be specified inside the <code>&lt;supported-locale&gt;</code> element. 
            </para>
            <para>
                  <emphasis role="bold">Registering resource bundles in the Faces configuration file:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[<application>
      <locale-config>
            <default-locale>en</default-locale>
            <supported-locale>en</supported-locale>
            <supported-locale>de</supported-locale>
            <supported-locale>it</supported-locale>
      </locale-config>
      <message-bundle>demo.message</message-bundle>
</application>]]></programlisting>
            
            <para>
                  For the application we will use JSF <code>javax.faces.component.UIViewRoot.setLocale</code> method that will set a needed Locale 
                  (each link will invoke corresponding method — there are, off course, another ways to do that). 
            </para>
            <para>
                  <emphasis role="bold"><code>ChangeLocale</code> Java class with three methods for setting the correponding Locale:</emphasis>
            </para>
            <programlisting role="JAVA"><![CDATA[package demo;

 import java.util.Locale;
 import javax.faces.context.FacesContext;

 public class ChangeLocale {
    public String germanAction() {
       FacesContext context = FacesContext.getCurrentInstance();
       context.getViewRoot().setLocale(Locale.GERMAN);
       return null;
    }

    public String englishAction() {
       FacesContext context = FacesContext.getCurrentInstance();
       context.getViewRoot().setLocale(Locale.ENGLISH);
       return null;
    }
    
    public String italianAction() {
        FacesContext context = FacesContext.getCurrentInstance();
        context.getViewRoot().setLocale(Locale.ITALIAN);
        return null;
     }
}]]></programlisting>
                  
                  <para>
                        Recently, the JSP page will look as following:
                  </para>
            
            <programlisting role="XML"><![CDATA[<h:form>
      <a4j:loadBundle var="msg" basename="demo.message"/>
      <h:outputText id="messageBundle" value="#{msg.greeting}"/>
      <a4j:commandLink value="De" action="#{changeLocale.germanAction}" reRender="messageBundle" />
      <a4j:commandLink value="Eng" action="#{changeLocale.englishAction}" reRender="messageBundle" />
      <a4j:commandLink value="It" action="#{changeLocale.italianAction}" reRender="messageBundle" />
</h:form> ]]></programlisting>
      
      <para>
            As an output we will get a simple application with English &quot;Hello!&quot; by default. 
            Clicking on links &quot;De&quot;, &quot;Eng&quot; and &quot;It&quot; will show the messages specified within the corresponding <code>*.properties</code> file.
            To reference to a particular bundle item during an Ajax update it is necessary to point the component(s) that shold be re-rendered (in this example it is done with the help of <emphasis role="bold"><property>&lt;a4j:commandLink&gt;</property></emphasis> <emphasis><property>&quot;reRender&quot;</property></emphasis> attribute).
      </para>
            
            <figure>
                  <title>
                        Using of the RichFaces <emphasis role="bold"><property>&lt;a4j:loadBundle&gt;</property></emphasis> component for application localization.
                  </title>
                  <mediaobject>
                        <imageobject>
                              <imagedata fileref="images/loadBundle2.png"/>
                        </imageobject>
                  </mediaobject>
            </figure>
      </section>
      
  <section>
    <title>Relevant resources links</title>
        <para>
              Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/bundle.jsf?c=loadBundle">LoadBundle page</ulink> at RichFaces LiveDemo for additional information on the component. 
        </para>
        <para>
              More useful examples and articles: 
        </para>
    <itemizedlist>
          <listitem>
                <para>
                      <ulink url="http://java.sun.com/javaee/javaserverfaces/1.1_01/docs/tlddocs/f/loadBundle.html">loadBundle tag reference</ulink> at java.sun portal;
                </para>
          </listitem>

        <listitem>
              <para>
                    <ulink url="http://java.sun.com/docs/books/tutorial/i18n/resbundle/propfile.html">Backing a ResourceBundle with Properties Files</ulink> at java.sun portal;
              </para>
        </listitem>
                    
          <listitem>
                <para>
                      <ulink url="http://www.objectsource.com/j2eechapters/Ch19-I18N_and_L10N.htm">Internationalization and Localization of J2EE application</ulink> explains main principles of  the internationalization of a web application;
                </para>
          </listitem>

          <listitem>
                <para>
                      <ulink url="http://www.laliluna.de/javaserver-faces-message-resource-bundle-tutorial.html">one more useful tutorial</ulink> explains the internationalization of a web application using JSF message resource bundle;
                </para>
          </listitem>
          
          <listitem>
          <para>
                <ulink url="http://www.i-coding.de/www/en/jsf/application/locale.html">Some special problem with JSF internationalization</ulink> and solution from the i-coding.de portal.
          </para>
          </listitem>

    </itemizedlist>  
    
  </section>  
</chapter>   