Tobago is a constantly maturing project with rich potential to fill a unique niche in the MyFaces family — feel free to sign up on the MyFaces mailing lists^[1] or sign up to the JIRA^[2] and participate in the process. Additionally, you can also check out the MyFaces project website to find out about future releases.

To use JSP as a rendering technology Tobago provides two tag libraries which contain the definition of available JSP tags — the Tobago core library and the extension library. The tag library definitions (TLD) for these libraries contain documentation for the tags and define the available required and optional attributes. IDEs can leverage this information to help the developer construct JSP pages.

A basic Tobago page looks like this:

<%@ 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" %>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<f:view>
  <tc:page>
    <f:facet name="layout">
      <tc:gridLayout/>
    </f:facet>
    <tc:out value="Hello World"/>
  </tc:page>
</f:view>

The Tobago project leverages Maven for all build management and Maven is the easiest way to build a web application with Tobago. The project descriptor (pom.xml) or project object model (POM) of Tobago defines all necessary dependencies and the Maven repository server and its mirrors provide the appropriate jars. For more information on Maven see the Maven web site^[3] and the book Better builds with Maven^[4].

The POM for the blank example specifies the packaging of the project as "war". The dependencies for the web application are managed by the <dependencies> element in the POM Maven automatically takes care of the dependencies through its transitivity mechanism. The POM comprises all necessary information needed to compile and package a web application archive. Use the following command in the shell:

mvn package

This results in a WAR archive in the target directory, where Maven stores its build artifacts and intermediary files. Moreover Maven can be used to deploy the WAR on an application server as well. The Tobago example POM, which is the parent POM of the blank example, contains the necessary information to deploy a WAR on an embedded Jetty server. By executing

mvn jetty:run-exploded

a Jetty server is started via Maven and the WAR is deployed on this servlet container. The server listens on the port 8080 and the web application can accessed under the URL http://localhost:8080/tobago-example-blank/.

HTML offers a large set of input controls which form the basis of Tobago's controls. This base includes single line text input fields, text areas, labels, radio buttons, check boxes, links, buttons, and so on. The Tobago demo shows these controls in action. A precompiled WAR for the demo is part of the example distribution and the Tobago web site links to a server with a live version. See Figure 1, “Basic controls”:

Figure 1. Basic controls

Input Control

A single line input control can be rendered with the <tc:in> tag. The extended version can be accessed with <tx:in>. In general the extension library, which is usually referenced by the tx prefix, provides convenience variants of controls. For the <tc:in> control the extended version <tx:in> contains boilerplate code for rendering labels. For form like input views nearly every input control has a corresponding label. The label is connected to the input control. If the label is clicked the input control gains focus.

<tx:in
    label="#{bundle.name}"
    value="#{address.name}"
    required="false" readonly="false"
    disabled="false" rendered="true" />

The label attribute determines the textual description for the control. It is laid out with a grid layout manager. The theme specifies the default label width, but it can be overwritten with the labelWidth attribute. If the label contains an underscore character the following character will become an access key. This is visualized by underlining the access key character. If the access key is pressed together with the Alt key the corresponding input field gains focus. The value attribute contains the content of the input control. The required attribute controls validation and allows the theme to render a special marker for required input. The required feature is rendered as a small box with a check mark inside the input field to inform the user to enter information into this field. Read-only controls do not allow the user to modify the value of the input control. A disabled control cannot gain focus, the label is rendered in a fashion to highlight the disabled nature of the input control and the user cannot copy content from the input control. The rendered attribute manages if the control is rendered at all. If the control is not rendered the layout manager can distribute the resulting space to other controls. For password fields the respective attribute can be set to true. If a page contains multiple input controls the first control will be focused by default. This behavior can be overwritten by setting the focus attribute of an input control to true.

Figure 2. Address editor

<tc:button label="Delete" action="#{controller.delete}"
    image="image/delete.png" defaultCommand="false">
  <f:facet name="confirmation">
    <tc:out value="Do you want to delete it?" />
  </f:facet>
</tc:button>

<tx:selectOneChoice label="#{bundle.footerTheme}" value="#{controller.theme}">
  <f:selectItems value="#{controller.themeItems}" />
  <f:facet name="change">
    <tc:command action="#{controller.themeChanged}"/>
  </f:facet>
</tx:selectOneChoice>

The <tc:sheet> component allows to display tabular data. The address book uses it to provide an overview of all stored addresses.

<tc:sheet columns="1*;1*;1*" value="#{controller.currentAddressList}"
    var="address" state="#{controller.selectedAddresses}"
    sortActionListener="#{controller.sheetSorter}" rows="25"
    showRowRange="left" showPageRange="right" showDirectLinks="center">
  <tc:column id="firstName" label="#{bundle.listFirstName}" sortable="true"
      rendered="#{controller.renderFirstName}">
    <tc:out value="#{address.firstName}" />
  </tc:column>
  <tc:column id="lastName" label="#{bundle.listLastName}" sortable="true"
      rendered="#{controller.renderLastName}">
    <tc:out value="#{address.lastName}" />
  </tc:column>
  <tc:column id="dayOfBirth" label="Birthday" sortable="true"
      rendered="#{controller.renderDayOfBirth}">
    <tc:out value="#{address.dayOfBirth}">
      <f:convertDateTime pattern="#{bundle.editorDatePattern}" />
    </tc:out>
  </tc:column>
</tc:sheet>

The value attribute links to a list model in the controller providing the data for the sheet. The <tc:sheet> contains three <tc:column> tags which describe the columns of the sheet. The label of the column is rendered as a header cell. The var attribute inside <tc:sheet> defines a local variable address, which refers to a row in the data model and can be used in the definition of the columns.

Figure 3. Address list

public String deleteAddresses() throws AddressDaoException {
  List<Integer> selection = selectedAddresses.getSelectedRows();
  if (selection.size() < 1) {
    FacesMessage error 
        = new FacesMessage("Please select at least one address.");
    FacesContext.getCurrentInstance().addMessage(null, error);
    return null;
  }
  for (int i = selection.size() - 1; i >= 0; i--) {
    Address address = currentAddressList.get(selection.get(i));
    addressDao.removeAddress(address);
  }
  // ...
  return OUTCOME_LIST;
}

The <tc:tabGroup> control renders different content on the same area of the view via tab panels. The switching behavior of the panels can be controlled with the switchType attribute. The panels can be switched on the client or the server. If the switching is performed on the server, Tobago can be instructed to only partially exchange the content of the page making use of Ajax. If the switching is done on the client it is faster, but the content of the page is bigger, because the rendering information of all tab panels has to be transferred to the client at once.

<tc:tabGroup switchType="reloadTab" immediate="true">
  <tc:tab label="#{bundle.editorTabPersonal}">
    <jsp:include page="tab/personal.jsp"/>
  </tc:tab>

  <tc:tab label="#{bundle.editorTabBusiness}" rendered="#{!controller.simple}">
    <jsp:include page="tab/business.jsp"/>
  </tc:tab>

  <tc:tab label="#{bundle.editorTabMisc}" rendered="#{!controller.simple}">
    <jsp:include page="tab/misc.jsp"/>
  </tc:tab>
</tc:tabGroup>

In the example application, two of the tab panels are only rendered if a certain condition is met in the controller. These particular tab panels are only rendered if the application is in the expert mode.

To mimic the appearance of a desktop application it is common to place a menu bar at the top of the page. This can be done with the <tc:menuBar> tag inside the menuBar facet of the <tc:page>. A menu bar can contain <tc:menu> tags, which can be nested to produce sub menus. Actions can be bound with method bindings to <tc:menuItem> tags. A menu item can be disabled and can encapsulate icons. An underscore in the label marks the following character as an access key, which can be activated together with the Alt key.

In the address book example the settings menu contains single selections created by <tx:menuRadio> to choose the current theme and language. Additionally it demonstrates how to use a check box menu item <tc:menuCheckbox> to change the mode of the application.

<tc:menuBar id="menuBar">
  <tc:menu label="_File">
    <tc:menuItem label="_New" action="#{controller.createAddress}" image
        ="image/org/tango-project/tango-icon-theme/16x16/actions/contact-new.png"/>
    <tc:menuItem label="_Add Dummy Addresses"
        action="#{controller.addDummyAddresses}"/>
    <tc:menuSeparator/>
    <tc:menuItem label="_Logout" image
        ="image/org/tango-project/tango-icon-theme/16x16/actions/system-log-out.png"/>
  </tc:menu>

  <tc:menu label="_Settings">
    ...
    <tc:menu label="_Theme">
      <tx:menuRadio action="#{controller.themeChanged}"
          value="#{controller.theme}">
        <f:selectItems value="#{controller.themeItems}"/>
      </tx:menuRadio>
    </tc:menu>
    <tc:menuCheckbox label="Simple _Mode" value="#{controller.simple}"/>
  </tc:menu>
  ...
</tc:menuBar>

The <tc:toolBar> tag renders a group of buttons. The tool bar can be configured to render a textual description of the action or an icon in different standard sizes. The buttons are created with the <tc:toolBarCommand> tag, which is a slightly limited version of the standard button tag.

<tc:toolBar iconSize="big">
  <tc:toolBarCommand label="#{bundle.toolbarAddressList}" 
      action="#{controller.search}" immediate="true" image=
 "image/org/tango-project/tango-icon-theme/32x32/mimetypes/x-office-address-book.png"
      disabled="#{facesContext.viewRoot.viewId == '/application/list.jsp'}"/>
  ...
</tc:toolBar>

In the address book example the first toolbar button navigates to the address list. If the address list is already the current view the button is disabled. There is a naming convention to provide disabled versions for image resources by adding an additional Disabled before the file extension. The disabled version has to reside in the same folder as the original image. In the example the resource manager can find a black and white icon x-office-address-bookDisabled.png as a disabled version of the normal address book icon.

A popup is a small modal dialog, which is displayed in the context of the current page. A general use case for a popup is entering new data and confirming or canceling the new data. Popups can be activated by adding a popup facet to commands. Alternatively a popup can be activated programmatically by setting the rendered attribute to true. In this way you can use a popup as a message box.

In the address book example the displayed columns for the address list can be controlled via a popup. This popup is bound to a button in the toolbar for the sheet.

<tc:button label="Open Popup">
  <f:facet name="popup">
    <tc:popup width="300" height="270">
      <tc:box label="Popup Title">
        ...
        <tc:panel>
          <f:facet name="layout">
            <tc:gridLayout columns="*;fixed;fixed"/>
          </f:facet>
          <tc:cell/>
          <tc:button label="OK">
            <tc:attribute name="popupClose" value="afterSubmit"/>
          </tc:button>
          <tc:button label="Cancel">
            <tc:attribute name="popupClose" value="immediate"/>
          </tc:button>
        </tc:panel>
      </tc:box>
    </tc:popup>
  </f:facet>
</tc:button>

The typical semantics of the confirmation and cancel button can be controlled via a <tc:attribute> with the name popupClose. This attribute can have two different values: afterSubmit or immediate. Both buttons close the popup, but only the afterSubmit variant stores the entered data into the model.

A file select control can be created with <tc:file>. The uploaded file is stored inside a FileItem object bound to the value attribute. The class FileItem is provided by commons-fileupload.

The address book allows the user to store photographs associated with the contacts. The user can click on an empty image placeholder to open a popup with the file select control which is created by the following code fragment:

<tc:file value="#{controller.uploadedFile}" required="true">
  <tc:validateFileItem contentType="image/*"/>
</tc:file>

With the validator <tc:validateFileItem> the content type or maximum size of the uploaded file can be restricted. For security reasons the style of an HTML file select control (input field of type file) can only be customized in a very limited way. Therefore the input control for the file name and the upload button may not optimally fit to the theme.

To handle multipart form data requests from the browser either the TobagoMultipartFormdataFilter servlet filter has to be configured in the web.xml or the tobago-fileupload.jar has to be added to the classpath. The address book demo uses the latter approach, which is based on a FacesContextFactory defined in the included faces-config.xml of the jar. The context factory can be configured with two different <env-entry> tags in the web.xml to control maximum upload limit and the directory for uploaded files. See the Javadoc of FileUploadFacesContextFactoryImpl for more information.

For Tobago, resources are images, style sheets, scripts, and string resources. These resources can be dependent on the locale, browser, or the theme. The resource manager collects all resource locations. When a resource is requested, the resource manager determines the inclusion order. A resource can be available in different themes and multiple locales. The resource manager first looks under the selected theme with the used browser and locale. If the resource is not found, the fallback locale is used to continue the search. After all fallback locales are examined the fallback for the browser is used and the locales are searched again. After all fallback browsers are searched the fallback for the theme is used and the search starts again with the locales until all fallback themes are processed. The result is cached for later reuse.

For resources such as images, the resource manager stops with the first match. For style sheets and scripts the resource manager returns a list of resources in the order they were found. This establishes a powerful defaulting mechanism.

By relying on the resource manager the developer can provide localized images with different text values for a button. The locale of the view is used to determine the correct language version of the image. The resource manager supports the XML format for property files, easing the use of special characters in string resources. The evaluation of the theme in inclusion order can be used to support different corporate wordings. If each client has its own theme string resources for the different themes can arrange the words in different ways — for example: email, e-mail, or eMail.

In the tobago-config.xml file, additional paths can be specified for inclusion by the resource manager. In this way you can add your own resources or even overwrite or extend existing resources. But changing existing themes this way may result in compatibility issues when switching to a newer version of Tobago, since the theme files are not stable yet and do not count as an official external API.

<tobago-config>
  <theme-config>
    <default-theme>speyside</default-theme>
  </theme-config>
  <resource-dir>tobago-resource</resource-dir>
</tobago-config>

The resource directory denotes a folder inside the WAR relative to the root. Paths for resources have to follow this pattern:

<content-type>/<theme>/<browser>/<directory>/<resource-name>(_<locale>)?.<extension>

Currently only html is supported as a content type, although the sandbox contains the beginnings for WML support. For the address book example there are two variants of an empty portrait with instructions how to upload a real portrait.

tobago-resource/html/standard/standard/image/empty-portrait.png
tobago-resource/html/standard/standard/image/empty-portrait_de.png

The first image is the default image with instructions in English. In the second image the instructions are localized in German. The first standard in the path denotes the fallback theme and the second standard represents the fallback browser. The directory part in the pattern stands for an arbitrary sub-path — in this example for the folder image.

Several controls like <tc:in>, <tc:panel>, or <tc:column> support the markup attribute. It allows the developer to apply logical styles to a control. Which markup values are supported is defined per theme in the theme-config.xml file. If a theme does not define supported markup for a renderer, it inherits the markup from the fallback theme. The Standard theme defines number for <tc:in> and <tc:out>, and strong and deleted for <tc:out>. The markup number is usually used to format numbers right aligned, strong is used to emphasize content, and deleted marks text as no longer available normally by crossing it out. The visual representation of markup is up to the theme and therefore it will fit to the overall look and feel of the theme.

To add new markup you can write your own theme. Choose the theme you want to extend and specify the selected theme as fallback theme. The Example theme extends Speyside and adds markup for columns.

<tobago-theme>
  <name>example</name>
  <deprecated-name>
    org.apache.myfaces.tobago.context.ExampleTheme
  </deprecated-name>
  <resource-path>org/apache/myfaces/tobago/renderkit</resource-path>
  <fallback>speyside</fallback>
  <renderers>
    <renderer>
      <name>Column</name>
      <supported-markup>
        <markup>new</markup>
      </supported-markup>
    </renderer>
  </renderers>
</tobago-theme>

To realize the visualization of the markup Tobago will add certain CSS style classes into the generated HTML for the marked control. The theme has to provide the styling information. The style class name results from the following naming rule "tobago-" + rendererName.toLower() + "-markup-" + markupName:

.tobago-column-markup-new {
  background-color: yellow;
}

For the Example theme it was decided to render a new column with a yellow background.

The address book example uses a different way to add markup. In this case three markup values — ok, warn, and error — are defined for the <tc:progress> control directly in the tobago-config.xml file. The administration area contains a progress bar to visualize the memory utilization of the virtual machine. Depending on the percentage value of the memory usage the business logic assigns different markup values for the progress bar to classify the state of the memory utilization.

Figure 9. Progress control with markup

We are starting with the user interface component of the control and will name it: UIInputNumberSlider^[6]. Like all JSF components, Tobago components must extend UIComponent^[7]. Because we want to create an input component we can extend UIInput^[8] which is a (non direct) subclass of UIComponent. The class UIInput is already an implementation of EditableValueHolder^[9] which saves us a lot of work.

The JSF runtime environment needs the component type as an identifier for creating instances of components. Tobago components need to store this information in the component itself in the constant COMPONENT_TYPE. This constant is processed by the Tobago annotation visitor that is used in the build process to create the faces-config.xml file.

We also implement some additional properties into our component: min, max, readonly and disabled. The property min specifies the smallest and the property max the largest number that can be entered. With the property readonly set the user cannot modify the value of the slider. The same is true for the property disabled. But in this case the complete control appears deactivated. All properties should be value binding enabled which makes their getters a little bit more complicated. To ensure that our component state is saved between requests we have to override the state holder methods of UIInput.

The following code shows some parts of our component class:

public class UIInputNumberSlider extends javax.faces.component.UIInput {

  public static final String COMPONENT_TYPE
      = "org.apache.myfaces.tobago.InputNumberSlider";

  private Boolean readonly;
  private Boolean disabled;
  private Integer min;
  private Integer max;

  public Boolean isReadonly() {
    if (readonly != null) {
      return readonly;
    }
    ValueBinding vb = getValueBinding(TobagoConstants.ATTR_READONLY);
    if (vb == null) {
      return false;
    } else {
      return (Boolean.TRUE.equals(vb.getValue(getFacesContext())));
    }
  }

  public void setReadonly(Boolean readonly) {
    this.readonly = readonly;
  }
  ...
  public void restoreState(FacesContext context, Object state) {...}
  public Object saveState(FacesContext context) {...}
}

There are two ways in JSF to render a component. The first one is to implement the encoding and decoding between UI component and the view in the UI component directly. This is called the direct implementation programming model. The second method is to delegate the task to an appropriate renderer which is called the delegating programming model. The delegated programming model keeps your components independent from the view technology and is preferred for Tobago components.

A renderer in JSF must be a subclass of type Renderer^[10]. For Tobago components this is different: their renderers must also implement the interface LayoutInformationProvider^[11] to get the renderer to work with the Tobago layout management. With this interface Tobago renderers provide the layout manager with certain information about the sizing of the component that is rendered. The required methods have a default implementation in the class LayoutableRendererBase^[12] which uses properties that are provided by the theme configuration of the used theme (tobago-theme-config.properties). We name our renderer InputNumberSliderRenderer and extend from LayoutableRendererBase. Following the Tobago naming convention the renderer must end with "Renderer".

When using the LayoutableRendererBase the theme configuration is a good place to provide the information needed for the layout. The implementation searches the configuration for properties with the following pattern: renderer name without "Renderer" + "." + key. All values are interpreted as pixels. Table 1, “Recognized keys for LayoutableRendererBase” specifies some of the recognized keys.

If LayoutableRendererBase does not find a value for a renderer it searches for default properties: "Tobago." + key. We could (but will not) specify a width padding of five pixels for our control by adding the property InputNumberSlider.paddingWidth=5 in the theme configuration of the sandbox theme. Please note that the resource location mechanism as described in the section called “Resource Management” is used to find a property.

The Tobago theme configuration is not only used by RendererBase, but properties of own renderers can be specified there. For example we define the percentage of the width of the slider of our control in the tobago-theme-config.xml: InputNumberSlider.sliderWidthPercent=66. This means the slider gets 66 percent of the width of our control and the input field 34 percent. The value can be accessed in the renderer with the following line of code:

int sliderWidthPercent
    = ThemeConfig.getValue(facesContext, component, "sliderWidthPercent");

The Tobago theming mechanism locates renderers by their location in the package structure. Normally all Tobago renderers are located under the root package org.apache.myfaces.tobago.renderkit. Below this, the location depends on the output technology, the theme and browser.

We use the sub package html.sandbox.standard.tag because we are writing an HTML control for the sandbox theme. Package standard means that all browsers (Mozilla, Internet Explorer etc.) will be served by this renderer. The last package tag is obligatory for historical reasons.

The code for encoding/decoding in the renderer is quite long so only some interesting fragments are shown in code snippet. All encoding is done in the method encodeEnd. First the properties of the component are retrieved. Then the response writer is used to generate the HTML input field of our control. The response writer for Tobago components is the TobagoResponseWriter^[13] which is created by the Tobago render kit. It provides the component developer with additional convenience methods and handles escaping. The decoding is done in the method decode and retrieves the value of the input field back from the HTTP request.

package org.apache.myfaces.tobago.renderkit.html.sandbox.standard.tag;

public class InputNumberSliderRenderer extends LayoutableRendererBase {

  public void encodeEnd(FacesContext facesContext, UIComponent component)
      throws IOException {
    String currentValue = getCurrentValue(facesContext, component);
    boolean readonly
        = ComponentUtil.getBooleanAttribute(component, ATTR_READONLY);
    boolean disabled
        = ComponentUtil.getBooleanAttribute(component, ATTR_DISABLED);
    TobagoResponseWriter writer
        = HtmlRendererUtil.getTobagoResponseWriter(facesContext);
    ...
    writer.startElement(HtmlConstants.INPUT);
    String inputIdAndName = getIdForInputField(facesContext, component);
    writer.writeNameAttribute(inputIdAndName);
    writer.writeIdAttribute(inputIdAndName);
    if (currentValue != null) {
      writer.writeAttribute(HtmlAttributes.VALUE, currentValue, false);
    }
    writer.writeAttribute(HtmlAttributes.READONLY, readonly);
    writer.writeAttribute(HtmlAttributes.DISABLED, disabled);
    writer.endElement(HtmlConstants.INPUT);
    ...
  }

  public void decode(FacesContext context, UIComponent component) {
    UIInput uiInput = (UIInput) component;
    ...
    String inputId = getIdForInputField(context, component);
    Map requestParameterMap
        = context.getExternalContext().getRequestParameterMap();
    if (requestParameterMap.containsKey(inputId)) {
      String newValue = (String) requestParameterMap.get(inputId);
      uiInput.setSubmittedValue(newValue);
    }
  }

  private String getIdForInputField(
        FacesContext context, UIComponent component) {...}
}

HtmlStyleMap style = (HtmlStyleMap) component.getAttributes().get("style");
int width = style.getInt("width");

All JSF implementations must support JSP as page description language for JSF pages. This is also standard for writing Tobago pages. A different view technology that does not depend on JSP is also available — Facelets. To allow an author to use our control we need to define a JSP tag — a custom action. This is done by writing one class and one interface: the tag class itself and a tag declaration interface which is Tobago specific.

We start with the tag class. All JSP custom actions in JSF that correspond to a UI component in the component tree must either subclass UIComponentTag^[14] or UIComponentBodyTag^[15] depending on whether they need support for body content functionality or not. Our action has no body content so we want to subclass UIComponentTag. Again there is an opportunity to save some effort if we extend from TobagoTag^[16] which extends from UIComponentTag. This class already implements the handling for the properties readonly and disabled.

Our tag is named InputNumberSliderTag^[17] and consists of four new properties (min, max, value and valueChangeListener) with their getter/setters, an implementation of getComponentType, a release method and a setProperties method.

Tag classes in Tobago are dumb gateways between the view technology (JSP) and the render independent UI component. No output should be generated in the JSP tag directly. This is done only in appropriate renderers. The advantage with this approach is that we can use a different view technology like Facelets without changing our code.

Next thing is the declaration of the tag. Therefore it implements an interface InputNumberSliderTagDeclaration^[18]. This interface describes our tag and its attributes with annotations. Tobago's build process uses this declaration to generate a faces-config.xml and a tag library description (TLD) for our component with the help of the annotation processing tool (apt). The interface is annotated with a @Tag annotation with a name attribute. The specified value "numberSlider" is the name of the JSP tag. The next annotation @UIComponentTag makes it clear that the tag belongs to a component with an associated renderer. The attributes rendererType and uiComponent specify the type of the renderer and the class of the UI component. Please note that the Tobago render kit will add the suffix "Renderer" to the renderer type to find a matching renderer class.

After the interface, the properties that are defined for the tag are annotated. By convention, the setter of the property is used. The @TagAttribute annotation describes a property that is part of the JSP tag. The @UIComponentTagAttribute annotation specifies a component property. Our properties appear in both the tag and the component. With the additional annotation attribute type we define the type of the properties.

Tobago has many predefined tag attribute declarations. We make use of them by extending the needed interfaces like IsReadonly or HasValue:

@Tag(name = "numberSlider")
@UIComponentTag(rendererType = "InputNumberSlider",
    uiComponent = "org.apache.myfaces.tobago.component.UIInputNumberSlider")
public interface InputNumberSliderTagDeclaration extends
  HasIdBindingAndRendered, IsReadonly, IsDisabled,
  HasValue, HasValueChangeListener {
  
  @TagAttribute()
  @UIComponentTagAttribute(type="java.lang.Integer", defaultValue="0")
  void setMin(String min);

  @TagAttribute()
  @UIComponentTagAttribute(type="java.lang.Integer", defaultValue="100")
  void setMax(String max);
}

After performing all four steps that are needed to create a Tobago control (UI component, renderer, tag and tag declaration) we are ready to build. This is done with a simple mvn install in the sandbox directory; the classes are compiled, the faces-config.xml and the tag library description is generated, everything is packaged and stored in the target directory. Depending on the Tobago version the package is called something like tobago-sandbox-i.j.k.jar. When this jar file is put into the classpath of a web application, the control can be used on a JSP page. It is important to switch to the Sandbox theme in the Tobago configuration.

<%@ taglib uri="http://myfaces.apache.org/tobago/sandbox" prefix="tcs" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<f:view>
  ...
  <tcs:numberSlider value="#{controller.value}" min="0" max="200"/>
  ...
</f:view>

We have not talked about the HTML layout of the control. There is a significant amount of work required for layouts when creating new Tobago controls, particularly with regard to browser compatibility and using Ajax. Additionally — there is also individual coding for every new control. Everything covered so far deals with aspects that are common to all Tobago component development.

The Tobago theming mechanism is not the only aspect that locates renderers with a predefined pattern. Almost everything (styles, images, scripts and properties) is organized within a tree structure and located in a similar way.