~~ 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. ------ Guide to Tobago ------ {Guide to Tobago} ==================== Tobago is a JavaServer Faces (JSF) framework and component library. It provides a comfortable way to layout screens of desktop-like applications with a consistent look & feel. Tobago emphasizes the separation of structure and design of screens. Screens are developed independently of the view technology -- no HTML, CSS, or JavaScript. Because of strict separation a screen can be displayed with different themes. These themes can be used to render screens according to different corporate design without changing the sources of the screens. This guide assumes basic knowledge about JSF. For more information about JSF see one of the various books about JSF, the {{{http://java.sun.com/javaee/5/docs/tutorial/doc/bnaph.html}Sun Java 5 Tutorial}} or the {{{http://java.sun.com/javaee/javaserverfaces/download.html}JSF Specification.}} {Content} \ %{toc|fromDepth=0|toDepth=4} {Environment} * {Building and Deploying the Tobago Examples} Tobago uses Maven as a build management system. The provided examples are normally build with Maven, but it would be easy to use an alternative build system. The necessary artifacts can be downloaded {{{./download.html}here}} or from the Maven repository. We will use the address book demo as an example in this guide. Since the address book example is currently not part of the Tobago distribution, you have to check-out the sources from the Apache Subversion repository. We will use the latest release tag for this. +------------------------------------------+ svn co https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/addressbook/ tobago-addressbook +------------------------------------------+ You will need Java 5 and Maven 2.0.9 or later to build the address book example. Use the following command to compile the sources and deploy the web application on an embedded Jetty server: +------------------------------------------+ mvn jetty:run-exploded +------------------------------------------+ If you point your browser to {{http://localhost:8080/}} and you will be directed to the login dialog of the address book example.\ \ [images/guide-addressbook-login.png] Address Book Login You can click on the guest/guest or admin/admin links or fill in the authentication information yourself and press the 'Login' button. After displaying a splash screen for a while the application will direct you to the address list page.\ \ [images/guide-addressbook-list.png] Address List A freshly started instance of the address book example will not contain any addresses in the list. But you can add addresses by pressing the 'New' button in the tool bar. The addresses will be stored in an embedded Derby database. * {Building Tobago} To use the latest version of Tobago you can use the snapshot artifacts build by our continuous integration server Continuum, which are available in the {{{https://repository.apache.org/content/repositories/snapshots/org/apache/myfaces/tobago/}Apache snapshot repository.}} Alternatively, you can build Tobago yourself. You will need Java 5 and Maven 2.0.9 or later. Check-out Tobago from the Apache Subversion repository +------------------------------------------+ svn co https://svn.apache.org/repos/asf/myfaces/tobago/trunk/ tobago +------------------------------------------+ To build the complete project with all sub-modules you have to enter the following command +------------------------------------------+ mvn install +------------------------------------------+ For more information on building Tobago -- especially the 1.0.x branch -- see {{{./getting-started.html}Getting Started.}} * {Building your own Tobago Application} The Tobago example distribution contains the tobago-example-blank WAR, which can act as starting point for your own Tobago application. Since Tobago is based on JSF you need a JSF implementation if the application server you are targeting doesn't contain one. If you cannot use Java 5 or higher you can use retrotranslated JARs from the Tobago distribution to develop and run Tobago applications with Java\ 1.4 (only Tobago 1.0.x). A Tobago application is a web application which is packaged as a WAR. For a JSF application the <<>> needs to be configured in the <<>>. To serve the internal resources of Tobago directly from the Tobago JARs the Tobago <<>> has to configured, too. The configuration of a Tobago application is controlled by the <<>> file. This can be used to declare the available themes and the default theme. Additionally, it can be used to locally add markup -- see the {{Themes}} section for further information. * {A Minimal Tobago Page} You can use JSP or Facelets to write Tobago pages. For Facelets support the extension module tobago-facelets has to be added as a dependency. Because the address book example uses JSP as rendering technology we will focus on JSP for now. Tobago provides two tag libraries -- the core library and the extension library. The corresponding TLDs contain documentation for the provided tags which is generated from annotations on the underlying tag classes. The core tag library contains basic controls and the extension library convenience tags for pre-assembled tag compositions -- for example a composition of a label and an input control. A minimal Tobago JSP page looks like this: +------------------------------------------+ <%@ page contentType="text/html;charset=UTF-8" language="java" %> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %> <%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %> +------------------------------------------+ A similar page is part of the blank WAR: \ {{https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/blank/src/main/webapp/helloWorld.jsp}} {Creating a Tobago page} The address book example needs an address editing page to add new addresses to the address book and to update existing ones. A simple version of an address editor allows to edit the first and last name of a person and basic address data like street, house number and city. Such an editor could look like this:\ \ [images/guide-simple-editor.png] Simple Address Editor This page is generated by the following code: +------------------------------------------+ <%@ page contentType="text/html;charset=UTF-8" language="java" %> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %> <%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %> +------------------------------------------+ We have a box with the label "Address" containing four rows of input controls for first name, last name, street, house number, and city. * {Basic Controls} HTML offers a decent set of basic controls. These controls form the basis of the Tobago controls including single-line input controls, text areas, check boxes, radio buttons, links, buttons, labels, and others. The Tobago demo contains an overview page for the basic controls.\ \ [images/guide-basic-controls.png] Basic Controls Live demo of the basic controls: {{http://www.irian.biz/tobago-example-demo-2.0.x/faces/content/01-basic/basic.xhtml}} The basic controls page also shows two variants of a normal input control: the date input control and the time input control. * {Text Input} The single-line text input control comes in two flavors: the <<<\>>> tag from the core tag library (<<>> is the preferred prefix for the core tag library) and the <<<\>>> from the extension tag library (<<>>). The extension tag library provides convenient shorthands for boilerplate code. For every input control there is for example an extended version, which layouts a label next before the input field. The label is connected with the field. If the label is clicked the related field is focused. A code fragment from the address book example: +------------------------------------------+ +------------------------------------------+ The <<>> attribute refers the content of the control. If a value binding is used, this content can be written back into a bean property. The <<