doc about return value of render phase methods

[Rural Hunter <ru...@gmail.com>]

Hi,

I'm reading the doc: http://tapestry.apache.org/component-rendering.html

There are mainly 3 places metioning the return value:

1.
Your methods may be void, or return a boolean value. Returning a value 
can force phases to be skipped, or even be re-visited. In the diagram, 
solid lines show the normal processing path. Dashed lines are alternate 
flows that are triggered when your render phase methods return false 
instead of true (or void).

2.


    Rendering Components

Instead of returning true or false, a render phase method may return a 
component. The component may have been injected via the @Component 
<http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html> 
annotation, or may have been passed to the owning component as a parameter.

In any case, returning a component will queue that component to be 
rendered *before* the active component continues rendering.

The component to render may even be from a completely different page of 
the application.

Recursive rendering of components is not allowed.

This technique allows the rendering of Tapestry pages to be /highly/ 
dynamic.

Returning a component instance does *not* short circuit method 
invocation (as described below), the way returning a boolean would. It 
is possible that multiple methods may return components (this is not 
advised – insanity may ensue).


    Additional Return Types

Render phase methods may also return Blocks 
<http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html>, 
Renderables 
<http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Renderable.html> 
or RenderCommands 
<http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/RenderCommand.html>.

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

3.


      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.

Most render phase methods should return void, to avoid unintentionally 
short circuiting other methods for the same phase.

I think the description is not organized well. Paragraph 2 and 3 make 
paragraph 1 invalid since the mothods can return values other than void 
or boolean. And, after reading all these, I am still wondering if 
returning a block will short circuit the render phase or not.


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org