001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  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 distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.html;
014
015/**
016 * Defines the interface for rendering the contents of an HTML page produced by the {@link HtmlDocSerializer}
017 * serializer.
018 *
019 * <p>
020 * The HTML doc serializer produces the following document structure with the typical contents:
021 * <p class='bxml'>
022 *    <xt>&lt;html&gt;
023 *       &lt;head&gt;
024 *          &lt;style&gt;
025 *             <xv>CSS styles and links to stylesheets</xv>
026 *          &lt;/style&gt;
027 *          &lt;script&gt;
028 *             <xv>Javascript</xv>
029 *          &lt;/script&gt;
030 *       &lt;/head&gt;
031 *       &lt;body&gt;
032 *          &lt;header&gt;
033 *             &lt;h1&gt;<xv>Page title</xv>&lt;/h1&gt;
034 *             &lt;h2&gt;<xv>Page description</xv>&lt;/h2&gt;
035 *             <xv>Arbitrary page branding</xv>
036 *          &lt;/header&gt;
037 *          &lt;nav&gt;
038 *             <xv>Page links</xv>
039 *          &lt;/nav&gt;
040 *          &lt;aside&gt;
041 *             <xv>Side-bar page links</xv>
042 *          &lt;/aside&gt;
043 *          &lt;article&gt;
044 *             <xv>Contents of serialized object</xv>
045 *          &lt;/article&gt;
046 *          &lt;footer&gt;
047 *             <xv>Footer message</xv>
048 *          &lt;/footer&gt;
049 *       &lt;/body&gt;
050 *    &lt;/html&gt;</xt>
051 * </p>
052 *
053 * <p>
054 * This interface allows you to control how these sections get rendered.
055 *
056 * <h5 class='section'>See Also:</h5><ul>
057 *    <li class='link'><a class="doclink" href="../../../../index.html#jm.HtmlDetails">HTML Details</a>
058 * </ul>
059 */
060public interface HtmlDocTemplate {
061
062   /**
063    * Represents a non-existent doc template.
064    */
065   public interface Void extends HtmlDocTemplate {}
066
067   /**
068    * Renders the contents of the <code><xt>&lt;head&gt;</xt></code> element.
069    *
070    * @param session The current serializer session.
071    * @param w The writer being written to.
072    * @param o The object being serialized.
073    * @throws Exception Any exception can be thrown.
074    */
075   void writeTo(HtmlDocSerializerSession session, HtmlWriter w, Object o) throws Exception;
076}