org.apache.tapestry
Interface IComponent

All Superinterfaces:

IRender, org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder

All Known Subinterfaces:

IDirect, IDirectEvent, IExternalPage, IForm, IFormComponent, IFormWidget, ILinkComponent, IPage, ITableModelSource, ITableRendererListener, ITemplateComponent, ITreeModelSource, IWidget, TranslatedField, ValidatableField, ValidatableFieldExtension

All Known Implementing Classes:

AbstractComponent, AbstractFormComponent, AbstractFormWidget, AbstractLinkComponent, AbstractPage, AbstractPostfield, AbstractTableRowComponent, AbstractTableViewComponent, AbstractWidget, AjaxStatus, Any, Autocompleter, BaseComponent, BasePage, Block, Body, Button, Card, Checkbox, CheckboxGroup, Choose, Conditional, ControlCheckbox, ControlledCheckbox, DateField, DatePicker, Deck, Delegator, Describe, Dialog, DirectLink, Do, DropdownDatePicker, DropdownTimePicker, DumpObject, ElseBean, Exception, ExceptionDisplay, ExternalLink, FieldLabel, ForBean, Form, FormConditional, FormTable, Frame, GenericLink, Go, GTimePicker, Hidden, IfBean, Image, Image, ImageSubmit, InlineEditBox, Input, Insert, InsertText, Inspector, InspectorButton, InvokeListener, LinkSubmit, ListEdit, MaskEdit, MultiplePropertySelection, NumericField, OnEvent, Option, Option, PageLink, Palette, Postfield, PropertySelection, PropertySelection, Radio, RadioGroup, Relation, RenderBlock, RenderBody, RequestDisplay, Rollover, Script, ScriptIncludes, Select, Select, SelectionField, Selector, ServiceLink, Setvar, Shell, ShowEngine, ShowProperties, ShowSpecification, ShowTemplate, SimpleTableColumnComponent, SimpleTableColumnFormComponent, SimpleTableColumnSortImage, SimpleTableColumnSortLink, StaleLink, Style, Submit, Suggest, Table, TableColumns, TableFormPages, TableFormRows, TablePages, TableRows, TableValues, TableView, TextArea, TextField, Timeout, Timer, Tree, TreeDataView, TreeNodeView, TreeTable, TreeTableDataView, TreeTableNodeViewDelegator, TreeView, Upload, ValidatingTextField, ValidField, ViewTabs, When, WMLException, WMLStaleLink, XTile

public interface IComponent
extends IRender, org.apache.hivemind.LocationHolder

Defines an object which may be used to provide dynamic content on a Tapestry web page.

Components are created dynamically from thier class names (part of the IComponentSpecification).

Author:

Howard Lewis Ship

Method Summary

void	addAsset(String name, IAsset asset) Adds an asset to the component.
void	addBody(IRender element) Adds a new renderable element to the receiver's body.
void	addComponent(IComponent component) Adds a component to a container.
void	enterActiveState() Invoked after finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)to switch the component from its initial construction state into its active state.
void	finishLoad(IRequestCycle cycle, IPageLoader loader, IComponentSpecification specification) Allows a component to finish any setup after it has been constructed.
IAsset	getAsset(String name) Returns the named asset, or null if not found.
Map	getAssets() Returns the asset map for the component, which may be empty but will not be null.
IBeanProvider	getBeans() Returns a IBeanProvider from which managed beans can be obtained.
IBinding	getBinding(String name) Returns the binding with the given name or null if not found.
Collection	getBindingNames() Returns a Collectionof the names of all bindings (which includes bindings for both formal and informal parameters).
Map	getBindings() Returns a Mapof the bindingsfor this component; this includes informal parameters as well as formal bindings.
String	getClientId() Returns the component's client-side element id.
IComponent	getComponent(String id) Retrieves an contained component by its id.
Map	getComponents() Returns the contained components as an unmodifiable Map.
IContainedComponent	getContainedComponent() Returns the IContainedComponent.
IComponent	getContainer() Returns the component which embeds the receiver.
IComponentEventInvoker	getEventInvoker() Returns the event connection manager services that handles creating/accepting browser events associated with various properties of components.
String	getExtendedId() Returns a string identifying the name of the page and the id path of the reciever within the page (seperated by a slash).
String	getId() Returns the simple id of the component, as defined in its specification.
String	getIdPath() Returns the qualified id of the component.
ListenerMap	getListeners() Returns a ListenerMap for the component.
org.apache.hivemind.Messages	getMessages() Returns component strings for the component.
INamespace	getNamespace() Returns the INamespacein which the component was defined (as an alias).
IPage	getPage() Returns the page which ultimately contains the receiver.
IComponentSpecification	getSpecification() Returns the specification which defines the component.
String	getSpecifiedId() Returns either the normal getId() value OR the value of any binding named id - if one exists.
String	getTemplateTagName() Though most component implementations ignore the specific html tag used to reference a component, this value may be used for those components that do wish to use the same tag that was provided when rendering a component.
boolean	isRendering() Returns true if the component is currently rendering.
String	peekClientId() Used internally to "peek" at what the next generated client id will be for this component when it renders.
void	renderBody(IMarkupWriter writer, IRequestCycle cycle) Invoked to make the receiver render its body (the elements and components its tag wraps around, on its container's template).
void	setBinding(String name, IBinding binding) Adds a binding to a container.
void	setClientId(String id) Sets the client ID.
void	setContainedComponent(IContainedComponent containedComponent) Sets the getContainedComponent() property; this may only be done once.
void	setContainer(IComponent value) Sets the container of the component.
void	setId(String value) Sets the id of the component.
void	setNamespace(INamespace namespace) Sets the INamespacefor the component.
void	setPage(IPage value) Sets the page which ultimiately contains the component.
void	setTemplateTagName(String tag) Sets the template tag name used to reference this component.

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

getLocation

Method Detail

addAsset

void addAsset(String name,
              IAsset asset)

Adds an asset to the component. This is invoked from the page loader.

Parameters:

name - The lookup name the asset will be bound to and referenacable as.

asset - The asset to add.

addComponent

void addComponent(IComponent component)

Adds a component to a container. Should only be called during the page loading process, which is responsible for doing all the necessary work of managing component state.

Parameters:

component - The component to add.

See Also:

IPageLoader

addBody

void addBody(IRender element)

Adds a new renderable element to the receiver's body. The element may be either another component, or static HTML. Such elements come from inside the receiver's tag within its container's template, and represent static text and other components.

The method renderBody(IMarkupWriter, IRequestCycle)is used to render these elements.

Since:

2.2

getAssets

Map getAssets()

Returns the asset map for the component, which may be empty but will not be null.

The return value is unmodifiable.

getAsset

IAsset getAsset(String name)

Returns the named asset, or null if not found.

getBinding

IBinding getBinding(String name)

Returns the binding with the given name or null if not found.

Bindings are added to a component using setBinding(String,IBinding).

getBindingNames

Collection getBindingNames()

Returns a Collectionof the names of all bindings (which includes bindings for both formal and informal parameters).

The return value is unmodifiable. It will be null for a page, or may simply be empty for a component with no bindings.

getBindings

Map getBindings()

Returns a Mapof the bindingsfor this component; this includes informal parameters as well as formal bindings.

Since:

1.0.5

getComponent

IComponent getComponent(String id)

Retrieves an contained component by its id. Contained components have unique ids within their container.

Throws:

org.apache.hivemind.ApplicationRuntimeException - runtime exception thrown if the named component does not exist.

getContainer

IComponent getContainer()

Returns the component which embeds the receiver. All components are contained within other components, with the exception of the root page component.

A page returns null.

setContainer

void setContainer(IComponent value)

Sets the container of the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

getExtendedId

String getExtendedId()

Returns a string identifying the name of the page and the id path of the reciever within the page (seperated by a slash). Note that this extended id is indetned primarily for identifying the component to the user (since slashes are legal characters within page names). Pages simply return their name.

See Also:

getIdPath()

getId

String getId()

Returns the simple id of the component, as defined in its specification.

An id will be unique within the component which contains this component.

A pagewill always return null.

setId

void setId(String value)

Sets the id of the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

getSpecifiedId

String getSpecifiedId()

Returns either the normal getId() value OR the value of any binding named id - if one exists. Higher precedence is given to bound id values.

Returns:

The bound or normal component id, or null if neither exists.

getIdPath

String getIdPath()

Returns the qualified id of the component. This represents a path from the page to this component, showing how components contain each other.

A pagewill always return null. A component contained on a page returns its simple id. Other components return their container's id path followed by a period and their own name.

See Also:

getId()

getClientId

String getClientId()

Returns the component's client-side element id. This has traditionally been an IFormComponent only binding but now applies to all components. The method should check to see if any id parameter/property has been set already and use that above all others, falling back to getId() if nothing else is found.

Returns:

the id, or null if the component doesn't support a client id.

Since:

4.1

setClientId

void setClientId(String id)

Sets the client ID. It is strongly discouraged for you to try setting this unless you understand the ramifications of how the rest of the system relies on this functioning.

Parameters:

id - The client id to set.

peekClientId

String peekClientId()

Used internally to "peek" at what the next generated client id will be for this component when it renders. Similar to the logic found in IRequestCycle.peekUniqueId(String).

Returns:

The next possible client ID for this component.

getTemplateTagName

String getTemplateTagName()

Though most component implementations ignore the specific html tag used to reference a component, this value may be used for those components that do wish to use the same tag that was provided when rendering a component.

Example:

  <fieldset jwcid="@If" condition="true" >
      <input type="text" />
  </fieldset>
 

In the example above, the value of the template tag would be "fieldset" for the If component.

Returns:

The html element tag name originally specified when referencing the component.

Since:

4.1

setTemplateTagName

void setTemplateTagName(String tag)

Sets the template tag name used to reference this component.

Set by the component template loader automatically, people shouldn't normally have any reason to try setting this.

Parameters:

tag - The tag name to set.

getPage

IPage getPage()

Returns the page which ultimately contains the receiver. A page will return itself.

setPage

void setPage(IPage value)

Sets the page which ultimiately contains the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

getSpecification

IComponentSpecification getSpecification()

Returns the specification which defines the component.

renderBody

void renderBody(IMarkupWriter writer,
                IRequestCycle cycle)

Invoked to make the receiver render its body (the elements and components its tag wraps around, on its container's template). This method is public so that the RenderBodycomponent may operate.

Since:

2.2

setBinding

void setBinding(String name,
                IBinding binding)

Adds a binding to a container. Should only be called during the page loading process (which is responsible for eror checking).

See Also:

IPageLoader

getComponents

Map getComponents()

Returns the contained components as an unmodifiable Map. This allows peer components to work together without directly involving their container ... the classic example is to have an Insertwork with an enclosing ForBean.

This is late addition to Tapestry, because it also opens the door to abuse, since it is quite possible to break the "black box" aspect of a component by interacting directly with components it embeds. This creates ugly interelationships between components that should be seperated.

Returns:

A Map of components keyed on component id. May return an empty map, but won't return null.

finishLoad

void finishLoad(IRequestCycle cycle,
                IPageLoader loader,
                IComponentSpecification specification)

Allows a component to finish any setup after it has been constructed.

The exact timing is not specified, but any components contained by the receiving component will also have been constructed before this method is invoked.

Since:

0.2.12

getMessages

org.apache.hivemind.Messages getMessages()

Returns component strings for the component. Starting in release 4.0, this method is unimplemented (and is automatically injected into each component implementation).

Since:

3.0

getNamespace

INamespace getNamespace()

Returns the INamespacein which the component was defined (as an alias).

Since:

2.2

setNamespace

void setNamespace(INamespace namespace)

Sets the INamespacefor the component. The namespace should only be set once.

Since:

2.2

isRendering

boolean isRendering()

Returns true if the component is currently rendering.

Since:

4.0

enterActiveState

void enterActiveState()

Invoked after finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)to switch the component from its initial construction state into its active state. The difference concerns parameters, whose defaults values may be set from inside finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).

Since:

4.0

getBeans

IBeanProvider getBeans()

Returns a IBeanProvider from which managed beans can be obtained.

Since:

4.0

getListeners

ListenerMap getListeners()

Returns a ListenerMap for the component. The map contains a number of synthetic read-only properties that implement the IActionListener interface, but in fact, cause public instance methods to be invoked (via reflection).

Since:

4.0

getContainedComponent

IContainedComponent getContainedComponent()

Returns the IContainedComponent. This will be null for pages. This property is set when a component is constructed, and links the component instance to the reference in the containing page or component's template or specification. This is useful to allow a component to know its type or the meta-data associated with the component.

Returns:

the contained component, or null for a page.

Since:

4.0

setContainedComponent

void setContainedComponent(IContainedComponent containedComponent)

Sets the getContainedComponent() property; this may only be done once.

Parameters:

containedComponent - may not be null

Since:

4.0

getEventInvoker

IComponentEventInvoker getEventInvoker()

Returns the event connection manager services that handles creating/accepting browser events associated with various properties of components.

Returns:

eventInvoker, may not be null

Since:

4.1