Component Parameters

Component parameters are a critical aspect of Tapestry. It is not enough that an instance of a component class exists, it must be configured to do the right thing. Configuration is in terms of the parameters of the component.

...

Parameters are defined by placing a Parameter annotation onto using the @Parameter annotation on a private field.

In Tapestry, a parameter is not a slot into which data is pushed: it is a connection between a field of the component (marked with the @Parameter annotation) and a property or resource of the component's container. In most simple examples, the container is the page, but since components can have themselves have templates, sometime the container of a component is another component.

...

Component parameters may also be bound using the Component @Component annotation inside the component class.

...

A special prefix, "inherit:", is used to support Inherted Inherited Parameter Bindings.

Render Variables

...

Some components support informal parameters, additional parameters beyond the formally defined parameters. Informal parameters will be rendered into the output as additional attributes on the tag rendered by the component. Generally speaking, components that have a 1:1 relationship with a particular HTML tag (such as TextField <TextField> and <input> will support informal parameters.

Only components whose class is annotated with SupportsInformalParameters @SupportsInformalParameters will support informal parameters.

...

The default binding prefix for informal parameters depends on where the parameter binding is specified. If the parameter is bound inside a Java class, within the Component @Component annotation, then the default binding prefix is "prop:". If the parameter is bound inside the component template, then the default binding prefix is "literal:". This reflects the fact that a parameter specified in the Java class, using the annotation, is most likely a computed value, whereas a value in the template should simply be copied, as is, into the result HTML stream.

...

Assets bindings are normally relative to the component class. This can be overriden overridden by prefixing the path with "context:", in which case, the path is a context path from the root of the web application context.

...

Only components which area annotated with SupportsInformalParameters @SupportsInformalParameters may have informal parameters. Tapestry silently drops informal parameters that are specified for components that do not have this annotation.

...

Parameter Binding Defaults

The Parameter @Parameter annotation's value() attribute can be used to specify a binding expression that will be the default binding for the parameter is otherwise left unbound. Typically, this is the name of a property that that will compute the value on the fly.

...

Obviously, this is a lot more work than simply specifying a default value as part of the Parameter @Parameter annotation. In the few real cases where this is approach is used, the default binding method will usually deduce a proper binding, typically in terms of the component's id. For example, the TextField component will deduce a value parameter that binds to a property of its container with the same name.

A default binding method will only be invoked if the Parameter @Parameter annotation does not provide a default value.

...

In rare cases, it is desirable to defeat the caching; this can be done by setting the cache() attribute of the Parameter @Parameter annotation to false.

Parameter Type Coercion

Tapestry includes a mechanism for coercing types automatically. Most often, this is used to convert literal strings into appropriate values, but in many cases, more complex conversions will occur.

...

By default, Tapestry converts from the field name to the parameter name, by stripping off leading "$" and "_" characters.

This can be overriden overridden using the name() attribute of the Parameter @Parameter annotation.

Determining if Bound

In rare cases, you may want to take different behaviors based on whether a parameter is bound or not. This can be accomplished by querying the component's resources, which can be injected into the component using the Inject @Inject annotation:

public class MyComponent
{
  @Parameter
  private int myParam;
  
  @Inject
  private ComponentResources resources;
  
  @BeginRender
  void setup()
  {
      if (resources.isBound("myParam"))
      {
        . . .
      }
  }
}

The above sketch illustrates the approach. Because the parameter type is a primitive type, int, it is hard to distinguish between no binding, and binding explicitly to the value 0.

The Inject @Inject annotation will inject the ComponentResources for the component. These resources are the linkage between the Java class you provide, and the infrastructure Tapestry builds around your class. In any case, once the resources are injected, they can be queried.

...

In Tapestry 5.1, you may use the publishParameters attribute of the Component @Component annotation. List one or more parameters separated by commas: those parameters of the inner/embedded component become parameters of the outer component. You should not define a parameter field in the outer component.

...