Component Specifications

Every component has a component specification, a file ending with a .jwc extension, whose root element is <component-specification> .

Each component's specification defines the basic characteristics of the component:

• The Java class for the component (which defaults to BaseComponent )
• Whether the component uses its body, or discards it (the allow-body attribute, which defaults to yes)
• The name, type and other information for each formal parameter.
• Whether the component allows informal parameters or discards them (the allow-informal-parameters attribute, which defaults to yes)
• The names of any reserved parameters which may not be used as informal parameters.

Tapestry searches for components in the following places:

• As specified in a <component-type> element (within the application specification).
• In the same folder as the application specification, which is typically the WEB-INF folder.
• In the WEB-INF/ servlet-name folder ( servlet-name is the name of the Tapestry ApplicationServlet for the application).
• In the WEB-INF folder.
• In the root context directory.

Coding components

protected void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
{
  . . .
}	

For example, to create a <a> link:

public void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
{
  . . .
  
  writer.begin("a");
  writer.attribute("url", url);
  writer.attribute("class", styleClass);

  renderBody(writer, cycle);

  writer.end(); // close the <a>	
}

The begin() method renders an open tag (the <a>, in this case). The end() method renders the corresponding </a>. As you can see, writing attributes into the tag is equally simple.

The call to renderBody() is used to render this component's body. A component doesn't have to render its body; the standard Image component doesn't render its body (and its component specification indicates that it discards its body). The If component decides whether or not to render its body, and the For component may render its body multiple times.

A component that allows informal parameters can render those as well:

  writer.beginEmpty("img");
  writer.attribute("src", imageURL);
  renderInformalParameters(writer, cycle);

This example will add any informal parameters for the component as additional attributes within the <img> element. These informal parameters can be specified in the page's HTML template, or within the <component> tag of the page's specification. Note the use of the beginEmpty() method, for creating a start tag that is not balanced with an end tag (or a call to the end() method).

Component Parameters

A Tapestry page consists of a number of components. These components communicate with, and coordinate with, the page (and each other) via parameters .

A formal component parameter has a unique name, and may be optional or required. Optional parameters may have a default value. The <parameter> component specification element is used to define formal component parameters.

In a traditional desktop application, components have properties . A controller may set the properties of a component, but that's it: properties are write-and-forget.

The Tapestry model is a little more complex. A component's parameters are bound to properties of the enclosing page (or component). The component is allowed to read its parameter, to access the page property the parameter is bound to. A component may also update its parameter, to force a change to the bound page property. In fact, behind the scenes, each component parameter has a binding object, an instance of type IBinding , that is used to read or update the property.

The vast majority of components simply read their parameters. Updating parameters is more rare; the most common components that update their parameters are form element components such as TextField or Checkbox .

Because bindings are often in the form of OGNL expressions, the property bound to a component parameter may not directly be a property of the page ... using a property sequence allows great flexibility.

Using OGNL , the TextField component's value parameter is bound to the LineItem's quantity property, using the OGNL expression lineItem.quantity, and the Insert component's value parameter is bound to the Product's name property using the OGNL expression lineItem.product.name.

When using localized messages (the message: prefix) or literal strings (no prefix), there is still a binding object, just a binding of a different type. Not all bindings are writable. OGNL expressions may be writeable, if the expression identifies a property that is itself writeable. Most other types of bindings are read only.

To access a component parameter inside Java code is simply a matter of defining an accessor method. For example, if your component has a title parameter, then you define a getTitle() accessor method:

public abstract String getTitle();
  
public void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
{
  writer.begin("a");
  writer.attribute("href", . . .);
  writer.attribute("title", getTitle());
  
  . . .
}

When your code invokes getTitle(), the binding for the title parameter will be used to obtain a value, which is returned. Likewise, invoking setTitle() will use the binding for the title parameter to update the bound value.

There are two ways to set default values for parameters. You may provide a default-value attribute in the <parameter> element. This is, effectively, a binding to use if no binding is provided.

  <parameter name="title" default-value="literal:Link to current thread"/>

Remember that outside of the template, all binding reference s, including the default-value attribute, default to OGNL expressions. Therefore, it is necessary to prefix the default value with the literal: prefix to ensure that Tapestry doesn't treat it as an expression.

What's nice is that the default value doesn't have to be a simple string; it can be a computed OGNL expression, or a reference to a localized message:

  <parameter name="title"  default-value="message:link-title"/>  

link-title=Link to current thread

The second approach to defining default values for parameters is to set the parameter's property from the component's finishLoad() method.

public abstract void setTitle(String title);

protected void finishLoad()
{
  super.finishLoad();
  
  setTitle("Link to current thread");
} 

Even with parameter defaults, there are times when you want to behave differently depending on whether a parameter is bound or not bound. The method isParameterBound() exists for those cases:

public abstract String getTitle();
  
public void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
{
  writer.begin("a");
  writer.attribute("href", . . .);
  
  if (isParameterBound("title"))
    writer.attribute("title", getTitle());
  
  . . .
}

Using isParameterBound() is most useful with parameters whose type is a primitive type. In the previous example, we could simply invoke getTitle() and see if the result is null. For, say, an int property, we would need a way to distinguish between 0 and no value provided ... that's what isParameterBound() is for.

Note that you always pass the name of the parameter to the isParameterBound() method, even when you've used the property attribute of the <parameter> element to use a different property name:

<parameter name="title" property="titleParameter"/>  

public abstract String getTitleParameter();
  
public void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
{
  writer.begin("a");
  writer.attribute("href", . . .);
  
  if (isParameterBound("title"))
    writer.attribute("title", getTitleParameter());
  
  . . .
}

When Tapestry enhances a class to add a component property, it (by default) caches the value of the binding for the duration of the component's render. That is, while a component is rendering, it will (at most) use the parameter's binding once, and store the result internally, clearing the cached value as the component finishes rendering. The parameter property can be accessed when the component is not rendering (an important improvement from Tapestry 3.0), the result simply is not cached (each access to the property when the component is not rendering is another access via the binding object).

This caching behavior is not always desired; in some cases, the component operates best with caching disabled. The <parameter> element's cache parameter can be set to "false" to defeat this caching.

However, for the majority of binding types (most types except for "ognl"), the value obtained is invariant ... it will always be the same value. Values obtained from invariant bindings are always cached indefinately (not just for the component's render). In other words, literal string values, localized messages and so forth are accessed via the binding just once. This is great for efficiency ; after "warming up", a Tapestry page will render faster the second time through, because so many component parameters are invariant and already in place inside component properties.

On the other hand, informal parameters are not cached at all; the values for such parameters are always re-obtained from the binding object on each use.

Component Libraries

Tapestry has a very advanced concept of a component library . A component library contains both Tapestry components and Tapestry pages (not to mention engine services).

<application name="Example Application">
      
  <library id="contrib" specification-path="/org/apache/tapestry/contrib/Contrib.library"/>
  	
</application>

	
<span jwcid="palette@contrib:Palette" . . . />

<component id="palette" type="contrib:Palette">
  . . .
</component>

	
  <asset name="logo" path="images/logo_200.png"/>
  
  <component id="image" type="Image">
    <binding name="image" value="asset:logo"/>
  </component>

<!DOCTYPE library-specification PUBLIC 
  "-//Apache Software Foundation//Tapestry Specification 3.0//EN" 
  "http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd">
	
<library-specification/>

  <a href="#" jwcid="@PageLink" page="OtherPage" namespace="ognl:namespace"> ... </a>