1 /*
   2  * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.javadoc.internal.doclets.formats.html;
  27 
  28 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  29 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  30 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  31 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation;
  32 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation.PageMode;
  33 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
  34 import jdk.javadoc.internal.doclets.toolkit.Content;
  35 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
  36 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
  37 
  38 /**
  39  * Abstract class to generate the overview files.
  40  *
  41  *  <p><b>This is NOT part of any supported API.
  42  *  If you write code that depends on this, you do so at your own risk.
  43  *  This code and its internal interfaces are subject to change or
  44  *  deletion without notice.</b>
  45  *
  46  */
  47 public abstract class AbstractOverviewIndexWriter extends HtmlDocletWriter {
  48 
  49     protected Navigation navBar;
  50 
  51     /**
  52      * Constructs the AbstractOverviewIndexWriter.
  53      *
  54      * @param configuration  The current configuration
  55      * @param filename Name of the module index file to be generated.
  56      */
  57     public AbstractOverviewIndexWriter(HtmlConfiguration configuration,
  58                                       DocPath filename) {
  59         super(configuration, filename);
  60         this.navBar = new Navigation(null, configuration, fixedNavDiv, PageMode.OVERVIEW, path);
  61     }
  62 
  63     /**
  64      * Adds the top text (from the -top option), the upper
  65      * navigation bar, and then the title (from the"-title"
  66      * option), at the top of page.
  67      *
  68      * @param header the documentation tree to which the navigation bar header will be added
  69      */
  70     protected void addNavigationBarHeader(Content header) {
  71         addTop(header);
  72         navBar.setUserHeader(getUserHeaderFooter(true));
  73         header.add(navBar.getContent(true));
  74     }
  75 
  76     /**
  77      * Adds the lower navigation bar and the bottom text
  78      * (from the -bottom option) at the bottom of page.
  79      *
  80      * @param footer the documentation tree to which the navigation bar footer will be added
  81      */
  82     protected void addNavigationBarFooter(Content footer) {
  83         navBar.setUserFooter(getUserHeaderFooter(false));
  84         footer.add(navBar.getContent(false));
  85         addBottom(footer);
  86     }
  87 
  88     /**
  89      * Adds the overview summary comment for this documentation. Add one line
  90      * summary at the top of the page and generate a link to the description,
  91      * which is added at the end of this page.
  92      *
  93      * @param main the documentation tree to which the overview header will be added
  94      */
  95     protected void addOverviewHeader(Content main) {
  96         addConfigurationTitle(main);
  97         if (!utils.getFullBody(configuration.overviewElement).isEmpty()) {
  98             HtmlTree div = new HtmlTree(HtmlTag.DIV);
  99             div.setStyle(HtmlStyle.contentContainer);
 100             addOverviewComment(div);
 101             main.add(div);
 102         }
 103     }
 104 
 105     /**
 106      * Adds the overview comment as provided in the file specified by the
 107      * "-overview" option on the command line.
 108      *
 109      * @param htmltree the documentation tree to which the overview comment will
 110      *                 be added
 111      */
 112     protected void addOverviewComment(Content htmltree) {
 113         if (!utils.getFullBody(configuration.overviewElement).isEmpty()) {
 114             addInlineComment(configuration.overviewElement, htmltree);
 115         }
 116     }
 117 
 118     /**
 119      * Generate and prints the contents in the index file.
 120      *
 121      * @param title the title of the window
 122      * @param description the content for the description META tag
 123      * @throws DocFileIOException if there is a problem building the package index file
 124      */
 125     protected void buildOverviewIndexFile(String title, String description)
 126             throws DocFileIOException {
 127         String windowOverview = resources.getText(title);
 128         Content body = getBody(getWindowTitle(windowOverview));
 129         Content header = HtmlTree.HEADER();
 130         addNavigationBarHeader(header);
 131         Content main = HtmlTree.MAIN();
 132         addOverviewHeader(main);
 133         addIndex(main);
 134         Content footer = HtmlTree.FOOTER();
 135         addNavigationBarFooter(footer);
 136         body.add(header);
 137         body.add(main);
 138         body.add(footer);
 139         printHtmlDocument(
 140                 configuration.metakeywords.getOverviewMetaKeywords(title, configuration.doctitle),
 141                 description, body);
 142     }
 143 
 144     /**
 145      * Adds the index to the documentation tree.
 146      *
 147      * @param main the document tree to which the packages/modules list will be added
 148      */
 149     protected abstract void addIndex(Content main);
 150 
 151     /**
 152      * Adds the doctitle to the documentation tree, if it is specified on the command line.
 153      *
 154      * @param body the document tree to which the title will be added
 155      */
 156     protected void addConfigurationTitle(Content body) {
 157         if (configuration.doctitle.length() > 0) {
 158             Content title = new RawHtml(configuration.doctitle);
 159             Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING,
 160                     HtmlStyle.title, title);
 161             Content div = HtmlTree.DIV(HtmlStyle.header, heading);
 162             body.add(div);
 163         }
 164     }
 165 }