Tapestry Components</>
<para>
Tapestry components are "black boxes" that are involved with both rendering
HTML responses and responding to HTTP requests.
</>
<para>
A Tapestry component is defined by its specification.
The specification is an XML file that defines the type of the component, it parameters,
the template used by the component, any components embedded within it and
how they are 'wired up', and (less often) any assets used by the component.
</>
<para>
At runtime, the specification is used to identify and instantiate a class
for the component. When the page containing the component is rendered, the
component will access its HTML template (whose location is defined
in the specification) to find the static HTML and embedded
components it will render.
</>
<section id="components.params">
<title>Parameters and Bindings</>
<para>
Tapestry components are designed to work with each other,
within the context of a page and application. The process of rendering a page
is largely about pulling information from a source into a component
and doing something with it.
</>
<para>
For example, on a welcome page, a component might get the <varname>userName</> property from
the <varname>visit</> object and insert it into the HTML response.
</>
<para>
Each component has a specific set of parameters.
Parameters have a name, a type and may be required or optional.
</>
<para>
To developers experienced with Java GUIs, it may appear that Tapestry
component parameters are the same as JavaBeans properties. This is not actually true.
JavaBeans properties are set-and-forget; the designer sets a value
for the property using a visual editor and the value
is saved with the bean until it is used at runtime.
</>
<para>
Parameters define the type of value needed, but not the actual value.
This value is provided by a special object called a binding.
The binding is responsible for providing the value
for the parameter as it is needed.
</>
<para>
A binding is a source and sink of data. A component
uses a binding to import or export a data value.
</>
<para>
There are two types of bindings: static and dynamic.
Static bindings are read-only; the value for the binding is
specified in the component specification.
</>
<para>
Dynamic bindings are more prevalent and useful. A dynamic
binding uses a JavaBeans property name to retrieve the value when needed
by the component. The source of this data is a property of some component.
</>
<para>
In fact, dynamic bindings use something more powerful than just a
property name, they can use a property path.
A property path is a series of property names separated by periods.
We've already seen an example: <literal>visit.userName</>.
This is equivalent to the Java code <function>getVisit().getUserName()</>,
except that the actual class of each object is used,
rather than the declared type of each method<footnote>
<para>In other words, property paths are not typesafe.</para></footnote>.
</>
<para>
Property paths can be very useful, since they can allow a binding to
'crawl' deeply through an object graph to access the value it needs.
This frees the components from relying totally on the properties of their container,
instead they are free to access properties of more distant objects.
</>
<para>
Let's change the example: now the <varname>visit</> object contains a <varname>user</> property,
which is an object of class <classname>User</> that has a number of
properties related to the real-life user (such as name, e-mail, account number, etc.).
</>
<para>
We can still use an <classname>Insert</> component to display the user's name;
we just have to extend the property path to <literal>visit.user.name</>,
which is approximately equivalent to <function>getVisit().getUser().getName()</>.
</section>
<section id="components.embedded">
<title>Embedded Components</>
<para>
Under Tapestry, it is common to define new components
by combining existing components. The existing components are
embedded in the containing component.
</>
<para>
Each embedded component has an <varname>id</> (an identifying string)
that must be unique within the containing component.
Every non-page component is embedded inside some other
component forming a hierarchy that can get quite deep
(in real Tapestry applications, some pages have components nested three to five levels deep).
</>
<para>
In some cases, a component will be referenced by its id path.
This is a series of component ids separated by periods, representing a path from
the page to a specific component. The same notation as a property path
is used, but the information being represented is quite different.
</>
<para>
For example, the id path <literal>border.navbar.homeLink</>
represents the component named <varname>homeLink</>,
embedded inside a component named <varname>navbar</>,
embedded inside a component named <varname>border</>, embedded inside some page.
</>
<para>
Tapestry components are "black boxes". They have a set of parameters that may
be bound, but their internals, how they are implemented, is not revealed.
</>
<para>
Primitive components may not embed other components, or even
have a template. Nearly all the built-in components are primitive; they are
building blocks for constructing more complex components.
</>
<para>
Alternately, a component may be implemented using a template and embedded components.
In either case, the names, types or very existence of embedded components is private,
hidden inside the containing component's "black box".
</>
</section>
<section id="components.html-template">
<title>HTML Templates</>
<para>Nearly all Tapestry components combine static HTML
<footnote>
<para>
The initial relase of Tapestry is specifically oriented around HTML. Some support for
non-HTML languages, such as XML, XHTML or WML is already present
and will be expanded in the future.
</>
</>
from a template with additional dynamic content
(some few components are just dynamic content).
Often, a Tapestry component embeds other Tapestry components.
These inner components are referenced in the containing component's template.
</>
<para>
Templates look like standard HTML files, though they are rarely complete
HTML documents; usually they are snippets.
In addition, a new element, &jwc-tag; (for Java Web Component),
is added to represent a component in the HTML template.
</>
<para>
The &jwc-tag; element has two forms:
</>
&start-listing;<jwc id="<replaceable>component id</>"> <replaceable>body</> </jwc>&end-listing;
<para>or
</>
&start-listing;<jwc id="<replaceable>component id</>"/>&end-listing;
<para>
The parser used by Tapestry is relatively forgiving about case
and white space. Also, the component id can be enclosed in
double quotes (as above) or single quotes.
</>
<para>
The body listed above can be either static HTML or other Tapestry
components or both. Elements in the body of a component are
wrapped by the containing component. The containing component controls the
rendering of the elements it wraps in its body. For example,
the <classname>Conditional</> component may decide not to
render its body and the <classname>Foreach</> component may render
its body multiple times.
</>
<para>
Not all Tapestry components should have a body.
For example, the <classname>TextField</> component creates an
<sgmltag class=starttag>input type=text</>
form element and it makes no sense for it to contain anything else.
Whether a component can have a body (and wrap other elements) is defined in the
component's specification.
</>
<para>
Tapestry includes a special component, <classname>InsertWrapped</>,
which is used to render the body of a component.
It makes it easy to create components that wrap other components.
</>
<para>
In many scripting systems, scripting constructs are one-dimensional....
they appear at a certain point on the page and dynamically
insert some content into a stream of HTML that eventually
ends up on the client web browser.
</>
<para>
Tapestry components are more powerful ... they have open and
close tags and thus can contain a body. This body is made up
of static HTML from the template and other Tapestry components. The outer component
wraps the inner elements.
</>
<para>
An example of this is the <classname>Border</> component in the Tapestry Tutorial
<footnote>
<para>
The Border tutorial has changed slightly since this
was initially written, but the basic ideas still hold.
</para>
</footnote>.
It shows how a component can wrap the entire content of a page.
</>
<figure>
<title>Border Component</>
<mediaobject>
<imageobject>
<imagedata fileref="images/Border-Screenshot.jpg" format=jpeg>
</>
</>
</>
<para>
Here, the <varname>border</> component provides the application title ("Reusable Component Tutorial",
in the title bar of the window), the page title (upper left corner) and navigation
controls (left side). The page provides the content in the light gray box in the center.
In this example, the page content is simply static HTML but in a real application the
content would include other components.
</>
<para>
The Home page component has the following HTML template:
</>
<figure>
<title>Home Page HTML Template</>
<programlisting>
&start-jwc; id="border"&end-jwc;<![CDATA[
Nothing much doing here on the <b>home</b> page. Visit one of our other fine
pages.
]]>&close-jwc;</programlisting>
</figure>
<para>
In other words, the <varname>border</>
component gets to produce HTML first. At some point, the page's content
(wrapped inside the <varname>border</> component) will be produced.
Afterwards, the <varname>border</> component will have an opportunity to produce more HTML.
The <classname>Border</> component has a much larger HTML template:
</>
<figure>
<title>Border component HTML template</>
<programlisting><![CDATA[
<HTML>
<head>
<title>Reusable Component Tutorial