Component Index
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| anchor | String | | | literal | An anchor value to append to the generated URL (the hash separator will be added automatically).
|
| context | java.util.List | | | prop | The context for the link (optional parameter). This list of values will be converted into strings and included in
the URI. The strings will be coerced back to whatever their values are and made available to event handler
methods.
|
| disabled | boolean | | false | prop | If true, then then no link element is rendered (and no informal parameters as well). The body is, however, still
rendered.
|
| zone | String | | | literal | Binding zone turns the link into a an Ajax control that causes the related zone to be updated.
|
Provides initialization of the clientId and elementName properties. In addition, adds the org.apache.tapestry.corelib.mixins.RenderInformals,
org.apache.tapestry.corelib.mixins.RenderDisabled and org.apache.tapestry.corelib.mixins.DiscardBody mixins.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
Provides base utilities for classes that generate clickable links.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| anchor | String | | | literal | An anchor value to append to the generated URL (the hash separator will be added automatically).
|
Base class for components that output a property value using a org.apache.tapestry.beaneditor.PropertyModel. There's a
relationship between such a component and its container, as the container may provide messages in
its message catalog needed by the org.apache.tapestry.Blocks that render the values. In addition, the
component may be passed Block parameters that are output overrides for specified properties.
Subclasses will implement a beginRender() method that invokes
org.apache.tapestry.corelib.base.AbstractPropertyOutput#renderPropertyValue(MarkupWriter, String).
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| model | org.apache.tapestry.beaneditor.PropertyModel | Required | | prop | Model for property displayed by the cell.
|
| object | Object | Required | | prop | Identifies the object being rendered. The component will extract a property from the object
and render its value (or delegate to a org.apache.tapestry.Block that will do so).
|
| overrides | org.apache.tapestry.ComponentResources | Required | | prop | Resources used to search for block parameter overrides (this is normally the enclosing Grid
component's resources).
|
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.
In particular, all subclasses support the "toclient" and "parseclient" events. These two events allow the normal
org.apache.tapestry.Translator (specified by the translate parameter, but often automatically derived by Tapestry) to be
augmented.
If the component container (i.e., the page) provides an event handler method for the "toclient" event, and that
handler returns a non-null string, that will be the string value sent to the client. The context passed to the event
handler method is t he current value of the value parameter.
Likewise, on a form submit, the "parseclient" event handler method will be passed the string provided by the client,
and may provide a non-null value as the parsed value. Returning null allows the normal translator to operate. The
event handler may also throw org.apache.tapestry.ValidationException.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| nulls | org.apache.tapestry.NullFieldStrategy | | default | nullfieldstrategy | Defines how nulls on the server side, or sent from the client side, are treated. The selected strategy may
replace the nulls with some other value. The default strategy leaves nulls alone. Another built-in strategy,
zero, replaces nulls with the value 0.
|
| translate | org.apache.tapestry.Translator | Required | | prop | The object which will perform translation between server-side and client-side representations. If not specified,
a value will usually be generated based on the type of the value parameter.
|
| validate | org.apache.tapestry.FieldValidator | | | validate | The object that will perform input validation (which occurs after translation). The translate binding prefix is
generally used to provide this object in a declarative fashion.
|
| value | Object | Required | | prop | The value to be read and updated. This is not necessarily a string, a translator may be provided to convert
between client side and server side representations. If not bound, a default binding is made to a property of the
container matching the component's id. If no such property exists, then you will see a runtime exception due to
the unbound value parameter.
|
Component that triggers an action on the server with a subsequent full page refresh.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| anchor | String | | | literal | An anchor value to append to the generated URL (the hash separator will be added automatically).
|
| context | java.util.List | | | prop | The context for the link (optional parameter). This list of values will be converted into strings and included in
the URI. The strings will be coerced back to whatever their values are and made available to event handler
methods.
|
| disabled | boolean | | false | prop | If true, then then no link element is rendered (and no informal parameters as well). The body is, however, still
rendered.
|
| zone | String | | | literal | Binding zone turns the link into a an Ajax control that causes the related zone to be updated.
|
Used to display the properties of a bean, using an underlying org.apache.tapestry.beaneditor.BeanModel. The output is a
series of div elements for the property names and property values.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| model | org.apache.tapestry.beaneditor.BeanModel | | | prop | The model that identifies the parameters to be displayed, their order, and every other
aspect. If not specified, a default bean model will be created from the type of the object
bound to the object parameter.
|
| object | Object | Required | | prop | The object to be rendered; if not explicitly bound, a default binding to a property whose
name matches this component's id will be used.
|
| overrides | org.apache.tapestry.ComponentResources | | componentResources | prop | Where to search for local overrides of property display blocks as block parameters. Further,
the container of the overrides is used as the source for overridden validation messages. This
is normally the component itself, but when the component is used within a BeanEditForm, it
will be the BeanEditForm's block parameter that will be searched.
|
| remove | String | | | literal | A comma-separated list of property names to be removed from the org.apache.tapestry.beaneditor.BeanModel. The names
are case-insensitive.
|
| reorder | String | | | literal | A comma-separated list of property names indicating the order in which the properties should
be presented. The names are case insensitive. Any properties not indicated in the list will
be appended to the end of the display order.
|
A component that creates an entire form editing the properties of a particular bean. Inspired by
Trails and BeanForm (both for Tapestry 4). Generates a simple
UI for editing the properties of a JavaBean, with the flavor of UI for each property (text field,
checkbox, drop down list) determined from the property type, and the order and validation for the
properties determined from annotations on the property's getter and setter methods.
You may add t:parameters to the component; when the name matches (case insensitive) the
name of a property, then the corresponding Block is renderered, rather than any of the built in
property editor blocks. This allows you to override specific properties with your own customized
UI, for cases where the default UI is insufficient, or no built-in editor type is appropriate.
This component is likely to change more than any other thing in Tapestry! What's available now is
a very limited preview of its eventual functionality.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientValidation | boolean | | | prop | If true, the default, then the embedded Form component will use client-side validation.
|
| model | org.apache.tapestry.beaneditor.BeanModel | | | prop | The model that identifies the parameters to be edited, their order, and every other aspect.
If not specified, a default bean model will be created from the type of the object bound to
the object parameter.
|
| object | Object | Required | | prop | The object to be edited by the BeanEditor. This will be read when the component renders and
updated when the form for the component is submitted. Typically, the container will listen
for a "prepare" event, in order to ensure that a non-null value is ready to be read or
updated.
|
| remove | String | | | literal | A comma-separated list of property names to be removed from the org.apache.tapestry.beaneditor.BeanModel. The names
are case-insensitive.
|
| reorder | String | | | literal | A comma-separated list of property names indicating the order in which the properties should
be presented. The names are case insensitive. Any properties not indicated in the list will
be appended to the end of the display order.
|
| submitLabel | String | | message:submit-label | literal | The text label for the submit button of the form, by default "Create/Update".
|
A component that generates a user interface for editing the properties of a bean. This is the
central component of the org.apache.tapestry.corelib.components.BeanEditForm, and utilizes a org.apache.tapestry.corelib.components.PropertyEditor for much of
its functionality.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| model | org.apache.tapestry.beaneditor.BeanModel | | | prop | The model that identifies the parameters to be edited, their order, and every other aspect.
If not specified, a default bean model will be created from the type of the object bound to
the object parameter.
|
| object | Object | | | prop | The object to be edited by the BeanEditor. This will be read when the component renders and
updated when the form for the component is submitted. Typically, the container will listen
for a "prepare" event, in order to ensure that a non-null value is ready to be read or
updated.
|
| overrides | org.apache.tapestry.ComponentResources | | componentResources | prop | Where to search for local overrides of property editing blocks as block parameters. Further,
the container of the overrides is used as the source for overridden validation messages. This
is normally the component itself, but when the component is used within a BeanEditForm, it
will be the BeanEditForm's block parameter that will be searched.
|
| remove | String | | | literal | A comma-separated list of property names to be removed from the org.apache.tapestry.beaneditor.BeanModel. The names
are case-insensitive.
|
| reorder | String | | | literal | A comma-separated list of property names indicating the order in which the properties should
be presented. The names are case insensitive. Any properties not indicated in the list will
be appended to the end of the display order.
|
A Checkbox component is simply a input type="checkbox".
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| value | boolean | Required | | prop | The value to be read or updated. If not bound, the Checkbox will attempt to edit a property of its container
whose name matches the component's id.
|
A component used to collect a provided date from the user. This is a wrapper around the LGPL dynarch.com DHTML/JavaScript Calendar.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| editTime | boolean | | | prop | If true, then the client-side calendar will show the time as well as the date. You will probably need to bind
the format parameter as well when this is true, say to %m/%d/%y %H:%M.
|
| format | String | | | literal |
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| validate | org.apache.tapestry.FieldValidator | | | validate | The object that will perform input validation (which occurs after translation). The translate binding prefix is
generally used to provide this object in a declarative fashion.
|
| value | java.util.Date | Required | | prop | The value parameter of a DateField must be a java.util.Date.
|
A component that does not do any rendering of its own, but will delegate to some other object
that can do rendering. This other object may be a component or a org.apache.tapestry.Block (among other
things).
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| to | Object | Required | | prop | Th object which will be rendered in place of the Delegate component. This is typically a
specific component instance, or a org.apache.tapestry.Block.
|
Standard validation error presenter. Must be enclosed by a org.apache.tapestry.corelib.components.Form component. If errors are
present, renders a div element around a banner message and around an unnumbered list of error
messages. Renders nothing if the org.apache.tapestry.ValidationTracker shows no errors.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| banner | String | | message:default-banner | prop | The banner message displayed above the errors. The default value is "You must correct the
following errors before you may continue.".
|
| class | String | | | prop | The CSS class for the div element rendered by the component. The default value is "t-error".
|
A close relative of org.apache.tapestry.corelib.components.ActionLink except in two ways.
First, the event that it triggers is explicitly controlled, rather than always "action".
Second, the event is triggered in its container.
This allows slightly shorter URLs but also allows multiple components within the same container to generate identical
URLs for common actions.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| anchor | String | | | literal | An anchor value to append to the generated URL (the hash separator will be added automatically).
|
| context | java.util.List | | | prop | The context for the link (optional parameter). This list of values will be converted into strings and included in
the URI. The strings will be coerced back to whatever their values are and made available to event handler
methods.
|
| disabled | boolean | | false | prop | If true, then then no link element is rendered (and no informal parameters as well). The body is, however, still
rendered.
|
| event | String | Required | | literal | The name of the event to be triggered in the parent component. An org.apache.tapestry.corelib.components.ActionLink
triggers an "action" event on itself, and EventLink component triggers any arbitrary event on its
container.
|
| zone | String | | | literal | Binding zone turns the link into a an Ajax control that causes the related zone to be updated.
|
An HTML form, which will enclose other components to render out the various types of fields.
A Form emits many notification events. When it renders, it fires a org.apache.tapestry.corelib.components.Form#PREPARE_FOR_RENDER notification, followed
by a org.apache.tapestry.corelib.components.Form#PREPARE notification.
When the form is submitted, the component emits several notifications: first a org.apache.tapestry.corelib.components.Form#PREPARE_FOR_SUBMIT, then a
org.apache.tapestry.corelib.components.Form#PREPARE: these allow the page to update its state as necessary to prepare for the form submission, then
(after components enclosed by the form have operated), a org.apache.tapestry.corelib.components.Form#VALIDATEevent is emitted, to allow for cross-form
validation. After that, either a org.apache.tapestry.corelib.components.Form#SUCCESS OR org.apache.tapestry.corelib.components.Form#FAILURE event (depending on whether the org.apache.tapestry.ValidationTracker has recorded any errors). Lastly, a org.apache.tapestry.corelib.components.Form#SUBMIT event, for any listeners that care only about
form submission, regardless of success or failure.
For all of these notifications, the event context is derived from the context parameter. This
context is encoded into the form's action URI (the parameter is not read when the form is submitted, instead the
values encoded into the form are used).
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientValidation | boolean | | true | prop | If true (the default) then client validation is enabled for the form, and the default set of JavaScript libraries
(Prototype, Scriptaculous and the Tapestry library) will be added to the rendered page, and the form will
register itself for validation. This may be turned off when client validation is not desired; for example, when
many validations are used that do not operate on the client side at all.
|
| context | java.util.List | | | prop | The context for the link (optional parameter). This list of values will be converted into strings and included in
the URI. The strings will be coerced back to whatever their values are and made available to event handler
methods.
|
| tracker | org.apache.tapestry.ValidationTracker | | defaultTracker | prop | The object which will record user input and validation errors. The object must be persistent between requests
(since the form submission and validation occurs in an component event request and the subsequent render occurs
in a render request). The default is a persistent property of the Form component and this is sufficient for
nearly all purposes (except when a Form is rendered inside a loop).
|
A grid presents tabular data. It is a composite component, created in terms of several sub-components. The
sub-components are statically wired to the Grid, as it provides access to the data and other models that they need.
A Grid may operate inside a org.apache.tapestry.corelib.components.Form. By overriding the cell renderers of properties, the default output only
behavior can be changed to produce a complex form with individual control for editing properties of each row. This is
currently workable but less than ideal -- if the order of rows provided by the org.apache.tapestry.grid.GridDataSource changes between
render and form submission, then there's the possibility that data will be applied to the wrong server-side objects.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| empty | org.apache.tapestry.Block | | block:empty | prop | A Block to render instead of the table (and pager, etc.) when the source is empty. The default is simply the text
"There is no data to display". This parameter is used to customize that message, possibly including components to
allow the user to create new objects.
|
| lean | boolean | | | prop | If true, then the CSS class on each TD and TH cell will be omitted, which can reduce the amount
of output from the component overall by a considerable amount. Leave this as false, the default, when you are
leveraging the CSS to customize the look and feel of particular columns.
|
| model | org.apache.tapestry.beaneditor.BeanModel | | | prop | The model used to identify the properties to be presented and the order of presentation. The model may be
omitted, in which case a default model is generated from the first object in the data source (this implies that
the objects provided by the source are uniform). The model may be explicitly specified to override the default
behavior, say to reorder or rename columns or add additional columns.
|
| pagerPosition | org.apache.tapestry.corelib.data.GridPagerPosition | | bottom | literal | Defines where the pager (used to navigate within the "pages" of results) should be displayed: "top", "bottom",
"both" or "none".
|
| remove | String | | | literal | A comma-separated list of property names to be removed from the org.apache.tapestry.beaneditor.BeanModel. The names are
case-insensitive.
|
| reorder | String | | | literal | A comma-separated list of property names indicating the order in which the properties should be presented. The
names are case insensitive. Any properties not indicated in the list will be appended to the end of the display
order.
|
| row | Object | | | prop | Used to store the current object being rendered (for the current row). This is used when parameter blocks are
provided to override the default cell renderer for a particular column ... the components within the block can
use the property bound to the row parameter to know what they should render.
|
| rowClass | String | NOT Cached | | prop | The CSS class for the tr element for each data row. This can be used to highlight particular rows, or cycle
between CSS values (for the "zebra effect"). If null or not bound, then no particular CSS class value is used.
|
| rowsPerPage | int | | 25 | prop | The number of rows of data displayed on each page. If there are more rows than will fit, the Grid will divide up
the rows into "pages" and (normally) provide a pager to allow the user to navigate within the overall result
set.
|
| source | Object | Required | | prop | The source of data for the Grid to display. This will usually be a List or array but can also be an explicit
org.apache.tapestry.grid.GridDataSource. For Lists and Arrays, a GridDataSource is created automatically as a wrapper around the
underlying List.
|
| volatile | boolean | | | prop | If true and the Loop is enclosed by a Form, then the normal state persisting logic is turned off. Defaults to
false, enabling state saving persisting within Forms. If a Grid is present for some reason within a Form, but
does not contain any form control components (such as org.apache.tapestry.corelib.components.TextField), then binding volatile to false will
reduce the amount of client-side state that must be persisted.
|
Part of org.apache.tapestry.corelib.components.Grid that renders the markup inside a single data cell. GridCell is used inside a
pair of loops; the outer loop for each row, the inner loop for each property of the row.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| model | org.apache.tapestry.beaneditor.PropertyModel | Required | | prop | Model for property displayed by the cell.
|
| object | Object | Required | | prop | Identifies the object being rendered. The component will extract a property from the object
and render its value (or delegate to a org.apache.tapestry.Block that will do so).
|
| overrides | org.apache.tapestry.ComponentResources | Required | | prop | Resources used to search for block parameter overrides (this is normally the enclosing Grid
component's resources).
|
Renders out the column headers for the grid. Eventually, this will include control over column sorting, perhaps even
column ordering.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| dataProvider | org.apache.tapestry.grid.GridModelProvider | | componentResources.container | prop | The object that provides access to bean and data models, which is typically the enclosing Grid component.
|
| lean | boolean | | | prop | If true, then the CSS class on each TH cell will be omitted, which can reduce the amount of output from
the component overall by a considerable amount. Leave this as false, the default, when you are leveraging the CSS
to customize the look and feel of particular columns.
|
| sortAscending | boolean | Required | | prop | If true, then the sort is ascending (A - Z), if false the descending (Z - A).
|
| sortColumnId | String | Required | | prop | The column which is currently being sorted. This value is the column's id, not its
name. This parameter may be null, in which case no column is being used
for sorting.
|
Generates a series of links used to jump to a particular page index within the overall data set.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| currentPage | int | Required | | prop | The current page number (indexed from 1).
|
| range | int | | 5 | prop | Number of pages before and after the current page in the range. The pager always displays
links for 2 * range + 1 pages, unless that's more than the total number of available pages.
|
| rowsPerPage | int | Required | | prop | The number of rows displayed per page.
|
| source | org.apache.tapestry.grid.GridDataSource | Required | | prop | The source of the data displayed by the grid (this is used to determine
how many rows are available, which in turn
determines the page count).
|
Renders out a series of rows within the table.
Inside a org.apache.tapestry.corelib.components.Form, a series of row index numbers are stored into the form ( ). This is not ideal ... in a situation where the data set can shift between the
form render and the form submission, this can cause unexpected results, including applying changes to the wrong
objects.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| currentPage | int | Required | | prop | The current page number within the available pages (indexed from 1).
|
| lean | boolean | | | prop | If true, then the CSS class on each TD cell will be omitted, which can reduce the amount of output from
the component overall by a considerable amount. Leave this as false, the default, when you are leveraging the CSS
to customize the look and feel of particular columns.
|
| provider | org.apache.tapestry.grid.GridModelProvider | | componentResources.container | prop | Object that provides access to the bean and data models used to render the Grid.
|
| row | Object | Required | | prop | The current row being rendered, this is primarily an output parameter used to allow the Grid, and the Grid's
container, to know what object is being rendered.
|
| rowClass | String | NOT Cached | | prop | Parameter used to set the CSS class for each row (each tr element) within the tbody). This is not
cached, so it will be recomputed for each row.
|
| rowsPerPage | int | Required | | prop | Number of rows displayed on each page. Long result sets are split across multiple pages.
|
| sortAscending | boolean | Required | | prop | If true, then the sort is ascending (A - Z), if false the descending (Z - A).
|
| sortColumnId | String | Required | | prop | The column which is currently being sorted. This value is the column's id, not its
name. This parameter may be null, in which case no column is being used
for sorting.
|
| volatile | boolean | | | prop | If true and the Loop is enclosed by a Form, then the normal state saving logic is turned off. Defaults to false,
enabling state saving logic within Forms.
|
Conditionally renders its body.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| else | org.apache.tapestry.Block | | | prop | An alternate org.apache.tapestry.Block to render if the test parameter is false. The default, null, means render nothing in
that situation.
|
| negate | boolean | | | prop | Optional parameter to invert the test. If true, then the body is rendered when the test parameter is false (not
true).
|
| test | boolean | Required | | prop | If true, then the body of the If component is rendered. If false, the body is omitted.
|
Generates a label element for a particular field.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| for | org.apache.tapestry.Field | Required | | component | The for parameter is used to identify the org.apache.tapestry.Field linked to this label (it is named this way because it
results in the for attribute of the label element).
|
Basic looping class; loops over a number of items (provided by its source parameter), rendering
its body for each one. It turns out that gettting the component to not store its state
in the Form is very tricky and, in fact, a series of commands for starting and ending heartbeats,
and advancing through the iterator, are still stored. For a non-volatile Loop inside the form,
the Loop stores a series of commands that start and end heartbeats and store state (either as
full objects when there is not encoder, or as client-side objects when there is an encoder).
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| elementName | String | | prop:componentResources.elementName | literal | The element to render. If not null, then the loop will render the indicated element around
its body (on each pass through the loop). The default is derived from the component template.
|
| encoder | org.apache.tapestry.PrimaryKeyEncoder | | | prop | Optional primary key converter; if provided and inside a form and not volatile, then each
iterated value is converted and stored into the form.
|
| index | int | | | prop | The index into the source items.
|
| source | Iterable | Required | | prop | Defines the collection of values for the loop to iterate over.
|
| value | Object | | | prop | The current value, set before the component renders its body.
|
| volatile | boolean | | | prop | If true and the Loop is enclosed by a Form, then the normal state saving logic is turned off.
Defaults to false, enabling state saving logic within Forms.
|
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.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| elementName | String | | componentResources.elementName | prop | The element name, derived from the component template. This can even be overridden manually
if desired (for example, to sometimes render a surrounding element and other times not).
|
| format | java.text.Format | Required | | prop | The format to be applied to the object.
|
| value | Object | Required | | prop | The value to be output (before formatting). If the formatted value is blank, no output is
produced.
|
Used to output raw markup to the client. Unlike, say, an expansion, the output from OutputRaw is
unfiltered, with any special characters or entities left exactly as is. This is used in
situations where the markup is provided externally, rather than constructed within Tapestry.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| value | String | Required | | prop | The value to to render. If unbound, and a property of the container matches the component's
id, then that property will be the source of the value.
|
Generates a render request link to some other page in the application. If an activation context is supplied (as the
context parameter), then the context values will be encoded into the URL. If no context is supplied, then the target
page itself will supply the context via a passivate event.
Pages are not required to have an activation context. When a page does have an activation context, the value
typically represents the identity of some object displayed or otherwise manipulated by the page.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| anchor | String | | | literal | An anchor value to append to the generated URL (the hash separator will be added automatically).
|
| context | java.util.List | | | prop | If provided, this is the activation context for the target page (the information will be encoded into the URL).
If not provided, then the target page will provide its own activation context.
|
| disabled | boolean | | false | prop | If true, then then no link element is rendered (and no informal parameters as well). The body is, however, still
rendered.
|
| page | String | Required | | literal | The logical name of the page to link to.
|
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". Elements can be moved between the lists by clicking a button, or double
clicking an option (and eventually, via drag and drop).
The items in the available list are kept ordered as per org.apache.tapestry.SelectModel order. When items are
moved from the selected list to the available list, they items are inserted back into their
proper positions.
The Palette may operate in normal or re-orderable mode, controlled by the reorder parameter.
In normal mode, the items in the selected list are kept in the same "natural" order as the items
in the available list.
In re-order mode, items moved to the selected list are simply added to the bottom of the list. In
addition, two extra buttons appear to move items up and down within the selected list.
Much of the look and feel is driven by CSS, the default Tapestry CSS is used to set up the
columns, etc. By default, the select element's widths are driven by the length of the
longest option, and it is common to override this to a fixed value:
style
DIV.t-palette SELECT { width: 300px; }
/style
This ensures that the two columns are the same width, and that the column widths don't change as
items move back and forth.
Option groups within the org.apache.tapestry.SelectModel will be rendered, but are not supported by the many
browsers, and are not fully handled on the client side.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| deselect | org.apache.tapestry.Asset | | asset:deselect.png | prop | The image to use for the deselect button (the default is a left pointing arrow).
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| encoder | org.apache.tapestry.ValueEncoder | Required | | prop | Encoder used to translate between server-side objects and client-side strings.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| model | org.apache.tapestry.SelectModel | Required | | prop | Model used to define the values and labels used when rendering.
|
| moveDown | org.apache.tapestry.Asset | | asset:move_down.png | prop | The image to use for the move down button (the default is a downward pointing arrow).
|
| moveUp | org.apache.tapestry.Asset | | asset:move_up.png | prop | The image to use for the move up button (the default is an upward pointing arrow).
|
| reorder | boolean | | false | prop | If true, then additional buttons are provided on the client-side to allow for re-ordering of
the values.
|
| select | org.apache.tapestry.Asset | | asset:select.png | prop | The image to use for the select button (the default is a right pointing arrow).
|
| selected | java.util.List | Required | | prop | The list of selected values from the org.apache.tapestry.SelectModel. This will be updated when the form
is submitted. If the value for the parameter is null, a new list will be created, otherwise
the existing list will be cleared. If unbound, defaults to a property of the container
matching this component's id.
|
| size | int | | 10 | prop | Number of rows to display.
|
A version of org.apache.tapestry.corelib.components.TextField, but rendered out as an input type="password" element.
Further, the output value for a PasswordField is always blank.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| nulls | org.apache.tapestry.NullFieldStrategy | | default | nullfieldstrategy | Defines how nulls on the server side, or sent from the client side, are treated. The selected strategy may
replace the nulls with some other value. The default strategy leaves nulls alone. Another built-in strategy,
zero, replaces nulls with the value 0.
|
| translate | org.apache.tapestry.Translator | Required | | prop | The object which will perform translation between server-side and client-side representations. If not specified,
a value will usually be generated based on the type of the value parameter.
|
| validate | org.apache.tapestry.FieldValidator | | | validate | The object that will perform input validation (which occurs after translation). The translate binding prefix is
generally used to provide this object in a declarative fashion.
|
| value | Object | Required | | prop | The value to be read and updated. This is not necessarily a string, a translator may be provided to convert
between client side and server side representations. If not bound, a default binding is made to a property of the
container matching the component's id. If no such property exists, then you will see a runtime exception due to
the unbound value parameter.
|
Outputs a single property value. Overrides for individual properties come from block parameters
whose name matches the . This component is rarely
used on its own, but is a critical piece of the org.apache.tapestry.corelib.components.BeanDisplay component.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| model | org.apache.tapestry.beaneditor.PropertyModel | Required | | prop | Model for property displayed by the cell.
|
| object | Object | Required | | prop | Identifies the object being rendered. The component will extract a property from the object
and render its value (or delegate to a org.apache.tapestry.Block that will do so).
|
| overrides | org.apache.tapestry.ComponentResources | Required | | prop | Resources used to search for block parameter overrides (this is normally the enclosing Grid
component's resources).
|
Used to edit a single property of a bean. This is used primarily by org.apache.tapestry.corelib.components.BeanEditForm. Unlike BeanEditForm, the
object to be edited must already exist and the must be passed in explicitly.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| model | org.apache.tapestry.beaneditor.BeanModel | Required | | prop | The model that identifies the parameters to be edited, their order, and every other aspect.
|
| object | Object | Required | | prop | The object to be edited by the BeanEditor. This will be read when the component renders and updated when the form
for the component is submitted. Typically, the container will listen for a "prepare" event, in order to ensure
that a non-null value is ready to be read or updated.
|
| overrides | org.apache.tapestry.ComponentResources | | componentResources | prop | Where to search for local overrides of property editing blocks as block parameters. Further, the container of the
overrides is used as the source for overridden validation messages. This is normally the component itself, but
when the component is used within a BeanEditForm, it will be the BeanEditForm's block parameter that will be
searched.
|
| property | String | Required | | prop | Identifies the property to be edited by the editor.
|
A radio button (i.e., input type="radio"). Radio buttons must operate within a org.apache.tapestry.RadioContainer (normally, the org.apache.tapestry.corelib.components.RadioGroup component).
If the value parameter is not bound, then the default value is a property of the container component whose name
matches the Radio component's id.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| value | Object | Required | | prop | The value associated with this radio button. This is used to determine which radio button will be selected when
the page is rendered, and also becomes the value assigned when the form is submitted.
|
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| encoder | org.apache.tapestry.ValueEncoder | Required | | prop | Allows a specific implementation of org.apache.tapestry.ValueEncoder to be supplied. This is used to create client-side
string values for the different radio button values.
|
| value | Object | Required | | prop | The property read and updated by the group as a whole.
|
Renders out an object using the org.apache.tapestry.services.ObjectRenderer service. Used primarily on the
org.apache.tapestry.corelib.pages.ExceptionReport page. This is focused on objects that have a specific
org.apache.tapestry.services.ObjectRenderer strategy. The org.apache.tapestry.corelib.components.BeanDisplay component is used for displaying the
contents of arbitrary objects in terms of a series of property names and values.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| object | Object | Required | | prop |
|
Select an item from a list of values, using an [X]HTML select element on the client side. An validation
decorations will go around the entire select element.
A core part of this component is the org.apache.tapestry.ValueEncoder (the encoder parameter) that is used to convert between
server-side values and client-side strings. In many cases, a org.apache.tapestry.ValueEncoder can be generated automatically from
the type of the value parameter. The org.apache.tapestry.services.ValueEncoderSource service provides an encoder in these situations; it
can be overriden by binding the encoder parameter, or extended by contributing a org.apache.tapestry.services.ValueEncoderFactory into the
service's configuration.
[JavaDoc]
Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| encoder | org.apache.tapestry.ValueEncoder | | | prop | Allows a specific implementation of org.apache.tapestry.ValueEncoder to be supplied. This is used to create client-side
string values for the different options.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| model | org.apache.tapestry.SelectModel | Required | | prop | The model used to identify the option groups and options to be presented to the user. This can be generated
automatically for Enum types.
|
| validate | org.apache.tapestry.FieldValidator | | | validate | Performs input validation on the value supplied by the user in the form submission.
|
| value | Object | Required | | prop | The value to read or update.
|
Corresponds to input type="submit", a client-side element that can force the enclosing
form to submit. The submit responsible for the form submission will post a notification that
allows the application to know that it was the responsible entity. The notification is named
"selected" and has no context.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| defer | boolean | | | prop | If true, then any notification sent by the component will be deferred until the end of the
form submission (this is usually desirable).
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
TextArea component corresponds to a textarea element. The value parameter is almost
always bound to a string, but this is not an absolute requirement.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| nulls | org.apache.tapestry.NullFieldStrategy | | default | nullfieldstrategy | Defines how nulls on the server side, or sent from the client side, are treated. The selected strategy may
replace the nulls with some other value. The default strategy leaves nulls alone. Another built-in strategy,
zero, replaces nulls with the value 0.
|
| translate | org.apache.tapestry.Translator | Required | | prop | The object which will perform translation between server-side and client-side representations. If not specified,
a value will usually be generated based on the type of the value parameter.
|
| validate | org.apache.tapestry.FieldValidator | | | validate | The object that will perform input validation (which occurs after translation). The translate binding prefix is
generally used to provide this object in a declarative fashion.
|
| value | Object | Required | | prop | The value to be read and updated. This is not necessarily a string, a translator may be provided to convert
between client side and server side representations. If not bound, a default binding is made to a property of the
container matching the component's id. If no such property exists, then you will see a runtime exception due to
the unbound value parameter.
|
TextField component corresponds to input type="text" element. The value parameter will be
editted. TextField is generally used with string values, but other values are acceptible, as long
as they can be freely converted back and forth to strings.
[JavaDoc]Component inheritance
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| clientId | String | | prop:componentResources.id | literal | The id used to generate a page-unique client-side identifier for the component. If a component renders multiple
times, a suffix will be appended to the to id to ensure uniqueness. The uniqued value may be accessed via the
clientId property.
|
| disabled | boolean | | false | prop | If true, then the field will render out with a disabled attribute (to turn off client-side behavior). Further, a
disabled field ignores any value in the request when the form is submitted.
|
| label | String | | | literal | The user presentable label for the field. If not provided, a reasonable label is generated from the component's
id, first by looking for a message key named "id-label" (substituting the component's actual id), then by
converting the actual id to a presentable string (for example, "userId" to "User Id").
|
| nulls | org.apache.tapestry.NullFieldStrategy | | default | nullfieldstrategy | Defines how nulls on the server side, or sent from the client side, are treated. The selected strategy may
replace the nulls with some other value. The default strategy leaves nulls alone. Another built-in strategy,
zero, replaces nulls with the value 0.
|
| translate | org.apache.tapestry.Translator | Required | | prop | The object which will perform translation between server-side and client-side representations. If not specified,
a value will usually be generated based on the type of the value parameter.
|
| validate | org.apache.tapestry.FieldValidator | | | validate | The object that will perform input validation (which occurs after translation). The translate binding prefix is
generally used to provide this object in a declarative fashion.
|
| value | Object | Required | | prop | The value to be read and updated. This is not necessarily a string, a translator may be provided to convert
between client side and server side representations. If not bound, a default binding is made to a property of the
container matching the component's id. If no such property exists, then you will see a runtime exception due to
the unbound value parameter.
|
Outputs paragraph oriented text, typically collected via a org.apache.tapestry.corelib.components.TextArea
component. The TextArea is split into lines, and each line it output inside its own p element.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| value | String | Required | | prop |
|
A close relative of the org.apache.tapestry.corelib.components.If component that inverts the meaning of its
test. This is easier than an If component with the negate parameter set to true.
[JavaDoc]Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| test | boolean | Required | | prop | If true, then the body of the If component is rendered. If false, the body is omitted.
|
A Zone is portion of the output page designed for easy dynamic updating via Ajax or other
client-side effects. A Zone renders out as a div element and may have content initially,
or may only get its content as a result of client side activity.
Often, Zone's are initially invisible, in which case the visible parameter may be set to false (it defaults to false).
When a user clicks an org.apache.tapestry.corelib.components.ActionLink whose zone parameter is set,
the corresponding client-side Tapestry.Zone object is located. It will update the content of the Zone's div and
then invoke either a show method (if the div is not visible) or an update method (if the div is visible). The show and update
parameters are the names of functions attached to the Tapestry.ZoneEffects object.
Renders informal parameters, adding CSS class "t-zone" and possibly, "t-invisible".
[JavaDoc]
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| show | String | | | prop | Name of a function on the client-side Tapestry.ZoneEffects object that is invoked to
make the Zone's div visible before being updated. If not specified, then
the basic "show" method is used.
|
| update | String | | | prop | Name of a function on the client-side Tapestry.ZoneEffects object that is invoked
after the Zone's content has been updated. If not specified, then the basic "highlight"
method is used, which performs a classic "yellow fade" to indicate to the user
that and update has taken place.
|
| visible | boolean | | | prop | If true (the default) then the zone will render normally. If false, then the "t-invisible"
CSS class is added, which will make the zone initially invisible.
|
A mixin for a text field that allows for autocompletion of text fields. This is based on Prototype's autocompleter
control.
The mixin renders an (initially invisible) progress indicator after the field (it will also be after the error icon
most fields render). The progress indicator is made visible during the request to the server. The mixin then renders
a div that will be filled in on the client side with dynamically obtained selections.
Multiple selection on the client is enabled by binding the tokens parameter (however, the mixin doesn't help split
multiple selections up on the server, that is still your code's responsibility).
The container is responsible for providing an event handler for event "providecompletions". The context will be the
partial input string sent from the client. The return value should be an array or list of completions, in
presentation order. I.e.
String[] onProvideCompletionsFromMyField(String input)
{
return . . .;
}
[JavaDoc]
Parameters
| Name | Type | Flags | Default | Default Prefix | Description |
|---|
| frequency | double | | | literal | Overrides the default check frequency for determining whether to send a server request. The default is .4
seconds.
|
| minChars | int | | | literal | Overwrites the default minimum characters to trigger a server round trip (the default is 1).
|
| tokens | String | | | literal | If given, then the autocompleter will support multiple input values, seperated by any of the individual
characters in the string.
|
