Page History

Rendering of components in Tapestry 5 is based on a state machine and a queue (instead of the tail recursion used in Tapestry 4). This breaks the rendering process up into tiny pieces that can easily be implemented or overridden. Don't worry, in practice, writing components requires a breathtakingly small amount of code.

Rendering Phases

The rendering of each component is divided into a number of phases, illustrated below.

Image AddedImage Removed
Each of the orange phases (SetupRender, BeginRender, BeforeRenderBody, etc.) corresponds to an annotation you may place on one or more methods of your class. The annotation directs Tapestry to invoke your method as part of that phase.

...

All Render phase methods are optional; a default behavior is associated with each phase.

The large number of phases reflects the need for precise control of components from component mixins. Several of the phases exist almost exclusively for mixins.

...

Here's the source for a looping component that counts up or down between two values, renders its body a number of times, and stores the current index value in a parameter:

package org.example.app.components;

import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.AfterRender;
import org.apache.tapestry5.annotations.SetupRender;

public class Count
{
    @Parameter
    private int start = 1;

    @Parameter(required = true)
    private int end;

    @Parameter
    private int value;

    private boolean increment;

    @SetupRender
    void initializeValue()

...

    {
        value = start;

        increment = start < end;
    }

    @AfterRender
    boolean next()
    {
        if (increment)
        {
            int newValue = value + 1;

            if (newValue <= end)
            {
                value = newValue;
                return false;
            }
        }
        else
        {
            int newValue = value - 1;

            if (newValue >= end)
            {
                value = newValue;
                return false; 
            }
        }

        return true;
    }
}

Returning false from next() causes Tapestry to re-run the BeginRender phase, and from there, re-render the component's body (this component does not have a template). Returning true transitions to the CleanupRender phase.

...

What's really mind blowing is that the template and body of a component will often contain ... more components! That means that many different components will be in different phases of their own state machine.

Render Phases in Detail

...

...

...

...

...

...

...

SetupRender

The SetupRender phase (see @SetupRender) is where you can perform any one-time per-render setup for your component. This is a good place to read component parameters and use them to set temporary instance variables.

...

Using this mechanism, the earlier example can be rewritten as:

package org.example.app.components;

import org.apache.tapestry5.annotations.Parameter;

public class Count
{
    @Parameter
    private int start = 1;

    @Parameter(required = true)
    private int end;

    @Parameter
    private int value;

    private boolean increment;

    void setupRender()

...

    {
        value = start;

        increment = start < end;
    }

    boolean afterRender()
    {
        if (increment)
        {
            int newValue = value + 1;

            if (newValue <= end)
            {
                value = newValue;
                return false;
            }
        }
        else
        {
            int newValue = value - 1;

            if (newValue >= end)
            {
                value = newValue;
                return false; 
            }
        }

        return true;
    }
}

This style is a trade off: on the gain side, the code is even simpler and shorter, and the method names will, by design, be more consistent from one class to the next. The down side is that the names are very generic, and may in some cases, be less descriptive than using annotated methods (initializeValue() and next() are, to some eyes, more descriptive).

...

The following component returns a Renderable in the BeginRender phase and skips the BeforeRenderTemplate phase:

public class OutputValueComponent
{
    @Parameter
    private String

...

 value;
    
    Object beginRender()
    {
        return new Renderable()
        {
            public void render(MarkupWriter

...

 writer)
            {
                writer.write(value);
            }
        };
    }
}

Short Circuiting

If a method returns a true or false value, this will short circuit processing. Other methods within the phase that would ordinarily be invoked will not be invoked.

...

To turn on rendering comments only for a particular request, add the query parameter t:component-trace=true to the URL:

  http://www.example.com/myapp/mypage?t:component-trace=true