1 /* 2 * Copyright (c) 2019, 2020, 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.BodyContents; 29 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; 30 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 31 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 32 import jdk.javadoc.internal.doclets.formats.html.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 /** 50 * Constructs the AbstractOverviewIndexWriter. 51 * 52 * @param configuration The current configuration 53 * @param filename Name of the module index file to be generated. 54 */ AbstractOverviewIndexWriter(HtmlConfiguration configuration, DocPath filename)55 public AbstractOverviewIndexWriter(HtmlConfiguration configuration, 56 DocPath filename) { 57 super(configuration, filename); 58 } 59 60 /** 61 * Adds the overview summary comment for this documentation. Add one line 62 * summary at the top of the page and generate a link to the description, 63 * which is added at the end of this page. 64 * 65 * @param main the documentation tree to which the overview header will be added 66 */ addOverviewHeader(Content main)67 protected void addOverviewHeader(Content main) { 68 addConfigurationTitle(main); 69 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) { 70 addOverviewComment(main); 71 } 72 } 73 74 /** 75 * Adds the overview comment as provided in the file specified by the 76 * "-overview" option on the command line. 77 * 78 * @param htmltree the documentation tree to which the overview comment will 79 * be added 80 */ addOverviewComment(Content htmltree)81 protected void addOverviewComment(Content htmltree) { 82 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) { 83 addInlineComment(configuration.overviewElement, htmltree); 84 } 85 } 86 87 /** 88 * Generate and prints the contents in the index file. 89 * 90 * @param title the title of the window 91 * @param description the content for the description META tag 92 * @throws DocFileIOException if there is a problem building the package index file 93 */ buildOverviewIndexFile(String title, String description)94 protected void buildOverviewIndexFile(String title, String description) 95 throws DocFileIOException { 96 String windowOverview = resources.getText(title); 97 Content body = getBody(getWindowTitle(windowOverview)); 98 Content main = new ContentBuilder(); 99 addOverviewHeader(main); 100 addIndex(main); 101 body.add(new BodyContents() 102 .setHeader(getHeader(PageMode.OVERVIEW)) 103 .addMainContent(main) 104 .setFooter(getFooter())); 105 printHtmlDocument( 106 configuration.metakeywords.getOverviewMetaKeywords(title, configuration.getOptions().docTitle()), 107 description, body); 108 } 109 110 /** 111 * Adds the index to the documentation tree. 112 * 113 * @param main the document tree to which the packages/modules list will be added 114 */ addIndex(Content main)115 protected abstract void addIndex(Content main); 116 117 /** 118 * Adds the doctitle to the documentation tree, if it is specified on the command line. 119 * 120 * @param body the document tree to which the title will be added 121 */ addConfigurationTitle(Content body)122 protected void addConfigurationTitle(Content body) { 123 String doctitle = configuration.getOptions().docTitle(); 124 if (!doctitle.isEmpty()) { 125 Content title = new RawHtml(doctitle); 126 Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, 127 HtmlStyle.title, title); 128 Content div = HtmlTree.DIV(HtmlStyle.header, heading); 129 body.add(div); 130 } 131 } 132 } 133