001// Copyright 2011 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.tapestry5.corelib.components;
016
017import org.apache.tapestry5.BindingConstants;
018import org.apache.tapestry5.Block;
019import org.apache.tapestry5.ComponentResources;
020import org.apache.tapestry5.annotations.Parameter;
021import org.apache.tapestry5.annotations.SupportsInformalParameters;
022import org.apache.tapestry5.ioc.annotations.Inject;
023import org.apache.tapestry5.ioc.util.AvailableValues;
024import org.apache.tapestry5.ioc.util.UnknownValueException;
025import org.apache.tapestry5.runtime.RenderCommand;
026import org.apache.tapestry5.services.dynamic.DynamicDelegate;
027import org.apache.tapestry5.services.dynamic.DynamicTemplate;
028import org.apache.tapestry5.services.dynamic.DynamicTemplateParser;
029
030/**
031 * The Dynamic component allows a component to render itself differently at different times, by making use of
032 * an external template file.
033 * <p>
034 * The content of the template file replaces the Dynamic component entirely with one exception: certain elements will be
035 * replaced with {@linkplain Block}s passed to the Dynamic component as informal parameters; this is triggered by
036 * <strong>id</strong> of the element. When the id attribute has the prefix {@code param:}, the remainder is the name of
037 * a Block parameter. There are no limitations on what can appear inside such a Block: text, components, forms, even the
038 * {@literal <t:body/>} directive.
039 * <p>
040 * Dynamic templates emulate how expansions work in standard Tapestry templates: Expansions (the <code>${ ... }</code>
041 * syntax) can appear in attribute values or interspersed in element text. This allows container properties, messages,
042 * assets, and so forth to be referenced within the external template. It should be noted that such access is quite a
043 * bit less efficient than putting such expansions inside a referenced Block, but this should not be a big concern
044 * outside of some kind of tight rendering loop.
045 * 
046 * @since 5.3
047 * @see DynamicTemplate
048 * @see DynamicTemplateParser
049 * @tapestrydoc
050 */
051@SupportsInformalParameters
052public class Dynamic
053{
054    /** The dynamic template containing the content to be rendered by the component. */
055    @Parameter(required = true, allowNull = false, defaultPrefix = BindingConstants.ASSET)
056    private DynamicTemplate template;
057
058    @Inject
059    private ComponentResources resources;
060
061    private final DynamicDelegate delegate = new DynamicDelegate()
062    {
063        public ComponentResources getComponentResources()
064        {
065            return resources;
066        }
067
068        public Block getBlock(String name)
069        {
070            Block result = resources.getBlockParameter(name);
071
072            if (result != null)
073                return result;
074
075            throw new UnknownValueException(String.format(
076                    "Component %s does not have an informal Block parameter with id '%s'.", resources.getCompleteId(),
077                    name), null, null, new AvailableValues("Available Blocks", resources.getInformalParameterNames()));
078        }
079    };
080
081    RenderCommand beginRender()
082    {
083        // Probably some room for caching here as well. It shouldn't be necessary to re-create the outermost
084        // RenderCommand every time, unless the template has changed from the previous render.
085        return template.createRenderCommand(delegate);
086    }
087}