<section role="NotInToc" id="a4j_loadBundle">
   <title>
				&lt;
				a4j:loadBundle
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.0.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
      <sectioninfo>
        <keywordset>
            <keyword>a4j:loadBundle</keyword>
        </keywordset>
      </sectioninfo>
      <title>Description</title>
      <para>
          The <emphasis role="bold">
            <property>&lt;a4j:loadBundle&gt;</property>
         </emphasis> component is similar to JSF <emphasis role="bold">
            <property>&lt;f:loadBundle&gt;</property>
         </emphasis>: 
          it loads a resource bundle localized for the Locale of the current view and stores properties as a Map in the current request attributes of the current request. 
    </para>
   </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 "Hello!" 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 "<link linkend="GettingStarted">Getting started with RichFaces</link>" chapter) create resource bundles with "Hello!" 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 "Hello!" by default. 
            Clicking on links "De", "Eng" and "It" 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>"reRender"</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>Reference Data</title>
      <para>
         <ulink url="&tlddoc;a4j/loadBundle.html">Table of 
							&lt;a4j:loadBundle&gt; 
							 attributes</ulink>.
						</para>
      <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>
   <section>
      <title>Relevant Resources Links</title>
        <para>
              Visit 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>
</section>