| <!-- |
| * 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> |