Component Reference

Tapestry includes more than 65 built-in components and mixins. In addition, there are hundreds of Tapestry components freely available from others. Of course, Tapestry makes it trivially easy to create your own custom components, so if you don't see what you need, just develop them yourself.

Contents

Tapestry-provided Components

Most Tapestry-provided components are found in the org.apache.tapestry5.corelib.components package. Other components are included in the separate org.apache.tapestry5.kaptcha.components and org.apache.tapestry5.upload.components packages.

AJAX-specific Components

Main Article: Ajax and Zones

AjaxFormLoop

A special form of the Loop component that adds Ajax support to handle adding new rows and removing existing rows dynamically.

AddRowLink, RemoveRowLink

Used inside an AjaxFormLoop component to spur the addition or removal of a row.

ProgressiveDisplay

Used to implement the progressive enhancement web design strategy; the component renders itself with a simplified initial content (i.e., "loading ...") and an Ajax request then supplies the component's true body.

Zone

A region of a page marked for dynamic updating via Ajax or other client-side effects.

Bean Displaying & Editing

Main Article: BeanEditForm Guide

BeanDisplay

Displays the properties of a bean, using an underlying BeanModel, as a dl element with dt/dd pairs.

BeanEditForm

Creates an entire form for editing the properties of a particular bean

BeanEditor

The central component of BeanEditForm, this generates a user interface for editing the properties of a bean

PropertyDisplay

Outputs a single property value. Overrides for individual properties come from block parameters whose name matches the property id. This component is used by the BeanDisplay component.

PropertyEditor

Used to edit a single property of a bean. This is used primarily by BeanEditForm.

Conditional and Looping Components

If

Conditionally renders its body. May render its tag and any informal parameters

Case

Not really a component, but a technique to emulate a "case" statement using a delegate

Loop

Loops over a number of items (provided by its source parameter), rendering its body for each one]

Unless

Inverse of the If component, renders its body if the condition is false.

Delegate

Does not do any rendering of its own, but will delegate to some other object that can do rendering

Form Components

Checkbox

Renders a standard <input type="checkbox"> element

Checklist

Renders a vertical list of <input type="checkbox"> elements

DateField

Collect a provided date from the user using a client-side JavaScript calendar

Form

An HTML form, which will enclose other components to render out the various types of fields.

FormFragment

A portion of a Form that may be selectively displayed

FormInjector

Adds new content to an existing Form

Hidden

Used to record a page property as a value into the form

Label

Generates a label element for a particular field

KaptchaField

Part of a Captcha based authentication scheme; a KaptchaField is paired with a KaptchaImage to ensure that the user has provided the correct value

KaptchaImage

Part of a Captcha based authentication scheme; a KaptchaImage generates a new text image whenever it renders and can provide the previously rendred text subsequently (it is stored persistently in the session)

Palette

A multiple selection component. Generates a UI consisting of two select elements configured for multiple selection; the one on the left is the list of "available" elements, the one on the right is "selected".

PasswordField

A version of TextField, but rendered out as an <input type="password"> element.

Radio

A radio button (i.e., <input type="radio">). Radio buttons must operate within a RadioContainer (normally, the RadioGroup component).

RadioGroup

Groups together a set of radio components that all affect the same property

Select

Renders a <select> element for selecting an item from a list of values

SubmitNotifier

A non visual component used to provide notifications to its container during a form submission

TextArea

Renders a <textarea> element for editing multi-line text

TextField

Renders an <input type="text"> element to edit single-line text

Upload

A file upload component (i.e., <input type="file">) based on Apache Commons FileUpload

Grids, Tables and Trees

Grid

Presents tabular data in a <table> element by iterating over a List or array

GridCell

Part of Grid, renders the markup inside a single data cell

GridColumns

Part of Grid, renders out the column headers for the grid, including links (where appropriate) to control column sorting

GridPager

Generates a series of links used to jump to a particular page index within the overall data set

GridRows

Renders out a series of rows within the table

Tree

A component used to render a recursive tree structure, with expandable/collapsable/selectable nodes.

Links and Buttons

ActionLink

Triggers an action on the server with a subsequent full page refresh

EventLink

Like ActionLink except that the event that it triggers is explicitly controlled, rather than always "action", and the event is triggered in its container

LinkSubmit

Generates a client-side hyperlink that submits the enclosing form

Submit

Corresponds to <input type="submit"> or <input type="image">, a client-side element that can force the enclosing form to submit

PageLink

Generates a render request link to some other page in the application

Output and Messages

Alerts

Renders out an empty <div> element and provides JavaScript initialization to make the element the container for alerts.

Dynamic

Allows a component to render itself differently at different times, by making use of an external template file.

Error

Presents validation errors of a single field. Must be enclosed by a Form component

Errors

Standard validation error presenter. Must be enclosed by a Form component. If errors are present, renders a div element around a banner message and around an unnumbered list of error messages

ExceptionDisplay

Integral part of the default ExceptionReport page used to break apart and display the properties of the exception

Output

A component for formatting output. If the component is represented in the template using an element, then the element (plus any informal parameters) will be output around the formatted value.

OutputRaw

Output raw markup to the client. Unlike an expansion, the output from OutputRaw is unfiltered, with any special characters or entities left exactly as is.

TextOutput

Outputs paragraph oriented text, typically collected via a TextArea component. The TextArea is split into lines, and each line it output inside its own p element.

Miscellaneous

Any

Renders an arbitrary element including informal parameters

Doctype

Overrides the DOCTYPE of the rendered document (via Document.dtd(String, String, String) which can be useful when different component templates that render to the same document disagree about what the correct DOCTYPE is.

RenderObject

Renders out an object using the ObjectRenderer service. Used primarily on the ExceptionReport page

Trigger

Triggers an arbitrary event during rendering. This is often useful to add JavaScript to a page or a component (via calls to the JavaScriptSupport environmental).

Tapestry Mixins

Main Article: Component Mixins

Mixins allow you to add behaviors to existing components. The core mixins are found in the org.apache.tapestry5.corelib.mixins package.

Tapestry includes the following mixins out-of-the-box.

Autocomplete

modifies a text field to provide for auto-completion of text using values retrieved from the server as the user types. See instructions.

DiscardBody

discards a component's body. Returns false from the BeforeRenderBody phase, which prevents the rendering of the body.

FormFieldFocus

instruments the outer Form on which component the focus should be activated. Replaced by OverrideFieldFocus starting in Tapestry 5.4.

NotEmpty

attaches to any component that renders an element. At the end of the render, if the element is empty, then a non-breaking space (&nbsp;) is injected into the element.

OverrideFieldFocus

when attached to a form field, causes that field to gain focus. Starting in Tapestry 5.4, this supersedes FormFieldFocus.

RenderClientId

forces a client element to render its client id by ensuring that "getClientId" is called.

RenderDisabled

renders an "disabled" attribute if the containing component is disabled

RenderInformals

renders out all informal parameters, at the end of the BeginRender phase. This mixin can be used with components that render a single tag inside the BeginRender phase.

RenderNotification

triggers event notifications to identify when it enters the BeginRender and AfterRender render phases

TriggerFragment

when applied to a Checkbox or Radio component, links the input field and a FormFragment, making the field control the client-side visibility of the FormFragment

ZoneRefresh

periodically refreshes a Zone by triggering an event on the server using ajax requests.

Tapestry Pages

Tapestry provides several special pages that provide status information. Most of these are found in the org.apache.tapestry5.corelib.pages package.

ExceptionReport

Responsible for reporting runtime exceptions. This page is quite verbose and is usually overridden in a production application.

PageCatalog

Lists out the currently loaded pages, with some statistics.

PropertyDisplayBlocks

Contains blocks for displaying basic property types; the blocks are contributed to the BeanBlockSource service.

PropertyEditBlocks

A page that exists to contain blocks used to edit different types of properties. The blocks on this page are contributed into the BeanBlockSource service configuration.

ServiceStatus

A page used to see the status of all services defined by the Registry.

Base Components

The base components, in the org.apache.tapestry5.corelib.base package, are intended to be extended by other components rather than used directly in templates.

AbstractComponentEventLink

Base class for link-generating components that are based on a component event request. Such events have an event context and may also update a Zone.

AbstractConditional

Base class for If and Unless. Will render its body or the block from its else parameter. If it renders anything and it has an element name, then it renders the element and its informal parameters.

AbstractField

Provides initialization of the clientId and elementName properties. In addition, adds the RenderInformals, RenderDisabled and DiscardBody mixins.

AbstractLink

Provides base utilities for classes that generate clickable links.

AbstractPropertyOutput

Base class for components that output a property value using a PropertyModel

AbstractTextField

Abstract class for a variety of components that render some variation of a text field. Most of the hooks for user input validation are in this class

BaseMessages

Base class for components that output messages

Other Component Libraries

See Modules