<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
-->

<chapter id="using">
  <title>Using Tobago (Users guide)</title>
  <para>This chapter describes how JSF applications are developed with
    Tobago.</para>
  <sect1 id="setup">
    <title>Setup</title>
    <para>To get your web application work with Tobago you have to do (at least)
      the following:
      <itemizedlist>
        <listitem>
          Include the "tobago-core.jar" in your classpath. A good
          position may be the "WEB-INF/lib" directory.
        </listitem>
        <listitem>
          <para>
            Add the needed themes to your web application. A theme is a zip
            file containing a subset of a war file. For example: html, css,
            image, javascript, jsp and java class files. The file contains
            a "tobago-theme" and a "WEB-INF/lib" directory.
          </para>
          <para>
            To add themes extract the theme files into your content root
            directory. This is the directory that contains your "WEB-INF"
            directory.
          </para>
          <para>
            Themes may extend other themes. In this case you have to include
            all super themes a theme depends on!
          </para>
        </listitem>
        <listitem>
          Add a "tobago-config.xml" file to your "WEB-INF" directory. The
          configuration file is described in
          <xref linkend="configuration"/>
          . You may use a sample provided with the distribution.
        </listitem>
      </itemizedlist>
      The distribution comes with an ant build file containing a "war"
      target which can be used as a reference.
    </para>
  </sect1>
  <sect1>
    <title>Tag library</title>
    <para>Tobago offers a rich set of user interface components described in
      this chapter. The component are used as tags on jsp pages.</para>
    <para>The following sections describe the components in detail.</para>
    <!-- the reference of the tag lib is generated -->
    &taglib;
  </sect1>
  <sect1 id="layout">
    <title>Layout management</title>
    <para>Tobago uses a layout manager to render the components. The manager
      is specified (as a facet) for a container component like a panel. Layout
      information given to the manager determine how the contained components
      are positioned and sized.</para>
    <para>The most important layout manager is the GridLayoutRenderer which is
      used to layout components in grid structures like forms.</para>
    <para>
      The following example illustrates the use of a layout manager:
      a typical web form.
    </para>
    <example>
      <title>Layout management</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="image/layout-management-example.png"
                     format="PNG"/>
        </imageobject>
      </mediaobject>
      <para>The form has two columns and six rows. Both columns get the same
        size which is expressed through
        <code>columns="1*;1*"</code>
        . The first five rows have a
        <code>fixed</code>
        height. This means the
        row is rendered as high as the components contained in the row needs it.
        The last row consumes the rest of the available space. This is specified
        by <code>rows="fixed;fixed;fixed;fixed;fixed;*"</code>. (Note the star
        at the end!)
      </para>
      <para>
        The complete code comes here:
      </para>
      <programlisting lang="jsp">
        <textobject>
          <textdata fileref="build/sniplets/layoutManagementExample.snip"/>
        </textobject>
      </programlisting>
      <para>
        Two of the rows range over both columns. This can be archived through
        a <code>cell</code> element with a <code>spanX</code> attribute
        (<code>spanY</code> is also possible).
      </para>
      <para>The first row has only one component. The second column contains
        an empty cell element.
      </para>
    </example>
  </sect1>
  <sect1 id="themes">
    <title>Themes</title>
    <para></para>
  </sect1>
</chapter>