001// Copyright 2014, 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. 014package org.apache.tapestry5.services; 015 016import org.apache.tapestry5.Block; 017import org.apache.tapestry5.alerts.Alert; 018import org.apache.tapestry5.dom.Document; 019import org.apache.tapestry5.dom.Element; 020import org.apache.tapestry5.ioc.services.TypeCoercer; 021import org.apache.tapestry5.runtime.RenderCommand; 022 023/** 024 * <p> 025 * Service that provides methods that render {@link Block}s (<code><t:block>>)</code>, 026 * component instances and {@link RenderCommand}s to a {@link String} or 027 * {@link Document org.apache.tapestry5.dom.Document} in a programatic way. 028 * </p> 029 * <p> 030 * This service was created for situations in which a page or component needs to generate some markup 031 * that wouldn't be rendered normally, but for external use, such as e-mails, returning 032 * HTML for AJAX requests or passing HTML instead of plain string for an {@link Alert}. 033 * </p> 034 * <p> 035 * The name of this interface comes from <a href="https://issues.apache.org/jira/browse/TAP5-938">TAP5-938</a>: 036 * <em>Expose ability to render a portion of a page (a Block, Component, etc.) without using internal services</em>. 037 * </p> 038 * @since 5.4 039 */ 040public interface PartialTemplateRenderer 041{ 042 043 /** 044 * <p> 045 * Renders an object, probably a {@link Block} or component instance, to a string. 046 * This method supposes any kind of initialization needed 047 * was already done. CSS and JavaScript inclusions or importings are ignored. 048 * The object must implement {@link RenderCommand} or being able to be coerced to it 049 * by {@link TypeCoercer}. 050 * <p> 051 * @param object an object, probably a {@link Block} or component instance or {@link RenderCommand}. 052 * @throws IllegalArgumentException if the object isn't a {@link RenderCommand} and cannot be coerced to it by {@link TypeCoercer}. 053 */ 054 String render(Object object); 055 056 /** 057 * Renders an object to a {@link Document} following the same rules as {@link #render(Object)} 058 * This method supposes any kind of initialization needed 059 * was already done. CSS and JavaScript inclusions or importings are ignored. 060 * 061 * @param renderCommand a {@link RenderCommand}. 062 * @return a {@link Document}. 063 */ 064 Document renderAsDocument(Object object); 065 066}