    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>&ltt:block&gt>)</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}