===== Install Messages ======

==== Q: How do I install message bundles for use? ====

<hi #ffd700>~~SP~~~~SP~~</hi> Depending on what you’re trying to accomplish, there are two ways you can install message bundles. Both methods require that you have one or more readable resource bundles (typically properties-based files). Currently you can read properties files on the file system or via any URL type supported by your Ant runtime. 

=== Installing a single default or ‘fall back’ messages bundle ===

If you have a single messages bundle that you want all AntXtras-based components to use, installing a fall back messages bundle with **<managemessages>** is the most straightforward thing to do as shown in the next snippet. Note that there can be only //ONE// fall back messages bundle and you should install it before using any AntXtras component that uses messages. While you don’t have to uninstall a fall back bundle, you can by passing ‘uninstall-fallback’ as the action for the manage task as demonstrated below.

<code xml 1>
[Declare your message bundle…]
<messagesbundle id="allmessages" mustexist="yes"
   resource="staging.META-INF.build-messages"/>

[Install your message bundle as default…]
<managemessages action="install-fallback"
   bundleid="allmessages"/>

[Read messages using any bundle-enabled component…]
<show messageid="LF.build.started" arg0="${$iso:}"/>

[Read messages using the $message: funcut…]
<echo message="{$message:LF.build.started?${$iso:}}"…/>

[If you have a "shutdown" include this…]
<managemessages action="uninstall-fallback"/>
</code>

:!: The big caveat with AntXtras messages is that in order to leverage the JRE’s automatic locale selection, you //must// refer to your bundles using a ‘resource’ parameter; files and URLs are loaded as generic resources //exactly as specified//.

== ==

=== Installing a messages bundle for a specific set of tasks ===

If you want to install a messages bundle for only a specific set of tasks (aka //a scoped configuration//) you need to use the **<overlaymessages>**<color #999966>[advanced antlib]</color> taskset as shown in the snippet below. 

<code xml 1>
 <macrodef name="mkapidocs">
   <attribute name="basedir"/>
   ...
   <sequential>
     <overlaymessages file="@{basedir}/messages">
        <show messageid="LF.apidocs.started".../>
        [...Other tasks to generate API documentation...]
     </overlaymessages>
   </sequential>
 </macrodef>
</code>

The <overlaymessages> configuration taskset is nestable, meaning you can nest one <overlaymessages> within another one (or more). Each newly nested taskset will use the nearest parent overlay as its default automatically //unless you tell it not to explicitly// by setting the ‘inheritance’ parameter to “off”. By turning inheritance off, you also stop AntXtras from using any installed fallback or parent message bundles.

<code xml 1>
 <macrodef name="mkdocs">
   <attribute name="basedir"/>
   ...
   <sequential>
     <overlaymessages file="@{basedir}/messages" inheritance="off">
        <apidocs/>
        <programmertests-reports/>
        <coverage-reports/>
        [...Generate other documentation...]
     </overlaymessages>
   </sequential>
 </macrodef>
</code>

== ==

=== Related Tips ===

  * [[enablefuncuts|How do I enable or disable function shortcuts?]]

~~UP~~