youys
/
ant

<?xml version="1.0"?>
<!--
   Copyright 2003-2004 The Apache Software Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<document>

  <properties>
    <index value="1"/>
    <author email="simeon@fitch.net">Simeon H. K. Fitch</author>
    <author email="christoph.wilhelms@t-online.de">Christoph Wilhelms</author>
    <title>Module HOW-TO</title>
  </properties>

<body>

  <section name="Introduction">
    <p>The purpose of this document is to provide an overview of the
    basic steps one must undertake to add a new module to
    Antidote. Please see <a href="./design.html">The Antidote
    Design Overview</a> for information on what a module is and how it
    fits into Antidote. If you've already got all that, then read
    on!
    </p>

    <p>NB: <i>Please submit updates and criticisms to this, particularly
    areas that were unclear, missing, or difficult to follow.</i>
    </p>
  </section>

  <section name="Step by step">
    <h2>1) Specialize <code>org.apache.tools.ant.gui.core.AntModule</code></h2>

    <p>All modules must inherit from the <code>AntModule</code>
    class. This will probably irritate some of you, but it essentially
    enforces inheritance from <code>javax.swing.JComponent</code> and
    provides encapsulated handling of the <code>AppContext</code> instance
    that is so important to this class.
    </p>

    <p>Your module is required to implement the
    <code>AntModule.contextualize(AppContext)</code> method. The first
    thing this method should do is call
    <code>AntModule.setContext(AppContext)</code>, and then it is safe for
    it to begin constructing its display, using whatever resources it
    needs from the given <code>AppContext</code> instance. Think of this
    in a similar manner to <code>Applet.init()</code> or
    <code>Servlet.init()</code>.
    </p>

    <h2>2) Update
       <code>org/apache/tools/ant/gui/resources/antidote.properties</code></h2>

    <h3>2a) Externalize All Displayable Strings</h3>

    <p>All displayable strings must be externalized to the
    <code>antidote.properties</code> file, and looked up via the
    <code>AppContext.getResources()</code> method after the
    <code>AntModule.contextualize()</code> method has been called. Follow
    the naming convention currently used in the properties file and
    you should have to problems. This task should be done
    <b>during</b> development of your module. Under no circumstances
    should your module be submitted or committed without this task
    being completed. Remember that Antidote has an international
    audience.
    </p>

    <h3>2b) Add Module to List of Auto-Loaded Modules</h3>

    <p>Look for the properties with the format
    <code>org.apache.tools.ant.gui.Antidote.xxx.modules</code> where
    <code>xxx</code> is one of {left | right | top | bottom}. Depending on
    where you want your module to appear, and the order that you want
    it to appear in relationship to the other modules, add the class
    name of your module appropriately. If multiple modules are listed
    for a single property (via a comma delimited list), then each
    module will have it's own tab in a <code>javax.swing.JTabbedPane</code>.
    </p>

    <p>NB:<i>This goofy way of constructing the main screen will probably
    change to something much more general (but not as general as, say
    <a href="http://www.alphaworks.ibm.com/tech/bml">BML</a>).</i>
    </p>

    <h2>Run it!</h2>
    <p>That should be all you need to do, at least to get your module
    plugged in. Check out the source code for
    <code>ProjectNavigator</code> and <code>PropertyEditor</code> for module
    examples that use the various facilities of the Antidote
    framework.
    </p>

  </section>
</body>
</document>