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.services;
016
017import org.apache.tapestry.IComponent;
018import org.apache.tapestry.IRequestCycle;
019import org.apache.tapestry.parse.ComponentTemplate;
020
021/**
022 * A source of localized HTML templates for components.  
023 * The cache is the means of access for components to load thier templates,
024 * which they need not do until just before rendering.
025 *
026 * <p>The template cache must be able to locate and parse templates as needed.
027 * It may maintain templates in memory.
028 *
029 * @author Howard Ship
030 */
031
032public interface TemplateSource
033{
034    /**
035     *  Name of an {@link org.apache.tapestry.IAsset} of a component that provides the template
036     *  for the asset.  This overrides the default (that the template is in
037     *  the same directory as the specification).  This allows
038     *  pages or component templates to be located properly, relative to static
039     *  assets (such as images and stylesheets).
040     * 
041     *  @since 2.2
042     * 
043     */
044    
045    public static final String TEMPLATE_ASSET_NAME = "$template";
046
047    /**
048     *  Name of the component parameter that will be automatically bound to
049     *  the HTML tag that is used to insert the component in the parent template.
050     *  If the parent component does not have a template (i.e. it extends 
051     *  AbstractComponent, not BaseComponent), then this parameter is bound to null.
052     * 
053     *  @since 3.0
054     * 
055     */
056    
057    public static final String TEMPLATE_TAG_PARAMETER_NAME = "templateTag";
058    
059    /**
060     *  Locates the template for the component.
061     * 
062     *  @param cycle The request cycle loading the template; this is required
063     *  in some cases when the template is loaded from an {@link org.apache.tapestry.IAsset}.
064     *  @param component The component for which a template should be loaded.
065     *
066     *  @throws org.apache.tapestry.ApplicationRuntimeException if the resource cannot be located or loaded.
067     * 
068     */
069
070    public ComponentTemplate getTemplate(IRequestCycle cycle, IComponent component);
071
072}