001// Copyright 2004, 2005 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry.components;
016
017import org.apache.tapestry.AbstractComponent;
018import org.apache.tapestry.IMarkupWriter;
019import org.apache.tapestry.IRequestCycle;
020
021/**
022 * Renders the text and components wrapped by a {@link Block}component. [ <a
023 * href="../../../../../ComponentReference/RenderBlock.html">Component Reference </a>]
024 * <p>
025 * It is possible for an RenderBlock to obtain a Block from a page <em>other than</em> the render
026 * page. This works, even when the Block contains links, forms and form components. The action and
027 * direct services will create URLs that properly address this situation.
028 * <p>
029 * However, because the rendering page can't know ahead of time about these foreign Blocks,
030 * {@link org.apache.tapestry.event.PageBeginRenderListener} and
031 * {@link org.apache.tapestry.event.PageEndRenderListener} methods (for components and objects of the
032 * foreign page) via RenderBlock will <em>not</em> be executed. This specifically affects the
033 * methods of the {@link org.apache.tapestry.event.PageBeginRenderListener} and
034 * {@link org.apache.tapestry.event.PageEndRenderListener} interfaces.
035 * <p>
036 * Before rendering its {@link Block}, RenderBlock will set itself as the Block's inserter, and
037 * will reset the inserter after the {@link Block}is rendered. This gives the components contained
038 * in the {@link Block}access to its inserted environment via the RenderBlock. In particular this
039 * allows the contained components to access the informal parameters of the RenderBlock which
040 * effectively allows parameters to be passed to the components contained in a Block.
041 * 
042 * @author Howard Lewis Ship
043 */
044
045public abstract class RenderBlock extends AbstractComponent
046{
047    /**
048     * If block is not null, then
049     * {@link Block#renderForComponent(IMarkupWriter, IRequestCycle, IComponent)} is invoked.
050     */
051
052    protected void renderComponent(IMarkupWriter writer, IRequestCycle cycle)
053    {
054        Block block = getBlock();
055
056        if (block == null)
057            return;
058
059        block.renderForComponent(writer, cycle, this);
060    }
061
062    public abstract Block getBlock();
063
064}