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