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.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.HtmlTag;
32 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
33 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation;
34 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation.PageMode;
35 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
36 import jdk.javadoc.internal.doclets.toolkit.Content;
37 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
38 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
39
40 /**
41 * Abstract class to generate the overview files.
42 *
43 * <p><b>This is NOT part of any supported API.
44 * If you write code that depends on this, you do so at your own risk.
45 * This code and its internal interfaces are subject to change or
46 * deletion without notice.</b>
47 *
48 */
49 public abstract class AbstractOverviewIndexWriter extends HtmlDocletWriter {
50
51 protected Navigation navBar;
52
53 /**
54 * Constructs the AbstractOverviewIndexWriter.
55 *
56 * @param configuration The current configuration
57 * @param filename Name of the module index file to be generated.
58 */
59 public AbstractOverviewIndexWriter(HtmlConfiguration configuration,
60 DocPath filename) {
61 super(configuration, filename);
62 this.navBar = new Navigation(null, configuration, PageMode.OVERVIEW, path);
63 }
64
65 /**
66 * Adds the top text (from the -top option), the upper
67 * navigation bar, and then the title (from the"-header"
68 * option), at the top of page.
69 *
70 * @param header the documentation tree to which the navigation bar header will be added
71 */
72 protected void addNavigationBarHeader(Content header) {
73 addTop(header);
74 navBar.setUserHeader(getUserHeaderFooter(true));
75 header.add(navBar.getContent(true));
76 }
77
78 /**
79 * Adds the lower navigation bar and the bottom text
80 * (from the -bottom option) at the bottom of page.
81 *
82 * @param footer the documentation tree to which the navigation bar footer will be added
83 */
84 protected void addNavigationBarFooter(Content footer) {
85 navBar.setUserFooter(getUserHeaderFooter(false));
86 footer.add(navBar.getContent(false));
87 addBottom(footer);
88 }
89
90 /**
91 * Adds the overview summary comment for this documentation. Add one line
92 * summary at the top of the page and generate a link to the description,
93 * which is added at the end of this page.
94 *
95 * @param main the documentation tree to which the overview header will be added
96 */
97 protected void addOverviewHeader(Content main) {
98 addConfigurationTitle(main);
99 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) {
100 HtmlTree div = new HtmlTree(HtmlTag.DIV);
101 div.setStyle(HtmlStyle.contentContainer);
102 addOverviewComment(div);
103 main.add(div);
104 }
105 }
106
107 /**
108 * Adds the overview comment as provided in the file specified by the
109 * "-overview" option on the command line.
110 *
111 * @param htmltree the documentation tree to which the overview comment will
112 * be added
113 */
114 protected void addOverviewComment(Content htmltree) {
115 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) {
116 addInlineComment(configuration.overviewElement, htmltree);
117 }
118 }
119
120 /**
121 * Generate and prints the contents in the index file.
122 *
123 * @param title the title of the window
124 * @param description the content for the description META tag
125 * @throws DocFileIOException if there is a problem building the package index file
126 */
127 protected void buildOverviewIndexFile(String title, String description)
128 throws DocFileIOException {
129 String windowOverview = resources.getText(title);
130 Content body = getBody(getWindowTitle(windowOverview));
131 Content header = new ContentBuilder();
132 addNavigationBarHeader(header);
133 Content main = new ContentBuilder();
134 addOverviewHeader(main);
135 addIndex(main);
136 Content footer = HtmlTree.FOOTER();
137 addNavigationBarFooter(footer);
138 body.add(new BodyContents()
139 .setHeader(header)
140 .addMainContent(main)
141 .setFooter(footer)
142 .toContent());
143 printHtmlDocument(
144 configuration.metakeywords.getOverviewMetaKeywords(title, configuration.doctitle),
145 description, body);
146 }
147
148 /**
149 * Adds the index to the documentation tree.
150 *
151 * @param main the document tree to which the packages/modules list will be added
152 */
153 protected abstract void addIndex(Content main);
154
155 /**
156 * Adds the doctitle to the documentation tree, if it is specified on the command line.
157 *
158 * @param body the document tree to which the title will be added
159 */
160 protected void addConfigurationTitle(Content body) {
161 if (configuration.doctitle.length() > 0) {
162 Content title = new RawHtml(configuration.doctitle);
163 Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING,
164 HtmlStyle.title, title);
165 Content div = HtmlTree.DIV(HtmlStyle.header, heading);
166 body.add(div);
167 }
168 }
169 }