1 /*
2 * Metis: Java Data Framework
3 * Copyright 2012-2026. Tony Washer
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
6 * use this file except in compliance with the License. You may obtain a copy
7 * of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14 * License for the specific language governing permissions and limitations under
15 * the License.
16 */
17 package io.github.tonywasher.joceanus.metis.help;
18
19 import io.github.tonywasher.joceanus.metis.help.MetisHelpEntry.MetisHelpId;
20 import io.github.tonywasher.joceanus.oceanus.base.OceanusException;
21 import io.github.tonywasher.joceanus.oceanus.resource.OceanusResourceLoader;
22 import io.github.tonywasher.joceanus.tethys.api.control.TethysUIHTMLManager.TethysUIStyleSheetId;
23
24 import java.util.ArrayList;
25 import java.util.List;
26
27 /**
28 * The help module that is implemented by each Help System.
29 */
30 public abstract class MetisHelpModule {
31 /**
32 * Document name for Help Contents.
33 */
34 protected static final String DOC_NAME = "HelpContents";
35
36 /**
37 * Attribute name for Initial page.
38 */
39 protected static final String ATTR_INITIAL = "initial";
40
41 /**
42 * The Help Entries.
43 */
44 private final List<MetisHelpEntry> theEntries;
45
46 /**
47 * The title of the Help System.
48 */
49 private final String theTitle;
50
51 /**
52 * The CSS of the help system.
53 */
54 private TethysUIStyleSheetId theCSS;
55
56 /**
57 * The initial entry of the help system.
58 */
59 private String theInitial;
60
61 /**
62 * Constructor.
63 *
64 * @param pTitle the title
65 */
66 protected MetisHelpModule(final String pTitle) {
67 /* Store parameters */
68 theTitle = pTitle;
69
70 /* Create entry list */
71 theEntries = new ArrayList<>();
72 }
73
74 /**
75 * Set the initial name.
76 *
77 * @param pInitial the initial name
78 */
79 public void setInitialName(final String pInitial) {
80 theInitial = pInitial;
81 }
82
83 /**
84 * Obtain the initial name.
85 *
86 * @return the initial name
87 */
88 protected String getInitialName() {
89 return theInitial;
90 }
91
92 /**
93 * Obtain the title.
94 *
95 * @return the title
96 */
97 protected String getTitle() {
98 return theTitle;
99 }
100
101 /**
102 * Obtain the CSS.
103 *
104 * @return the CSS
105 */
106 protected TethysUIStyleSheetId getCSS() {
107 return theCSS;
108 }
109
110 /**
111 * Obtain the help entries.
112 *
113 * @return the help entries
114 */
115 public List<MetisHelpEntry> getHelpEntries() {
116 return theEntries;
117 }
118
119 /**
120 * Add root entry.
121 *
122 * @param pEntry the entry
123 * @return the HelpEntry
124 */
125 public MetisHelpEntry addRootEntry(final MetisHelpEntry pEntry) {
126 theEntries.add(pEntry);
127 return pEntry;
128 }
129
130 /**
131 * Define Standard Help entry.
132 *
133 * @param <K> the type of the key
134 * @param pName the name
135 * @param pHelpId the helpId
136 * @return the HelpEntry
137 */
138 public static <K extends Enum<K> & MetisHelpId> MetisHelpEntry defineHelpEntry(final String pName,
139 final K pHelpId) {
140 return defineTitledHelpEntry(pName, pName, pHelpId);
141 }
142
143 /**
144 * Define Titled Help entry.
145 *
146 * @param <K> the type of the key
147 * @param pName the name
148 * @param pTitle the title
149 * @param pHelpId the helpId
150 * @return the HelpEntry
151 */
152 public static <K extends Enum<K> & MetisHelpId> MetisHelpEntry defineTitledHelpEntry(final String pName,
153 final String pTitle,
154 final K pHelpId) {
155 return new MetisHelpEntry(pName, pTitle, pHelpId);
156 }
157
158 /**
159 * Define Contents Help entry.
160 *
161 * @param pName the name
162 * @return the HelpEntry
163 */
164 public static MetisHelpEntry defineContentsEntry(final String pName) {
165 return defineTitledContentsEntry(pName, pName);
166 }
167
168 /**
169 * Define Contents Help entry.
170 *
171 * @param pName the name
172 * @param pTitle the title
173 * @return the HelpEntry
174 */
175 public static MetisHelpEntry defineTitledContentsEntry(final String pName,
176 final String pTitle) {
177 return new MetisHelpEntry(pName, pTitle);
178 }
179
180 /**
181 * Load Help entries from the file system.
182 *
183 * @throws OceanusException on error
184 */
185 protected void loadHelpPages() throws OceanusException {
186 loadHelpPages(theEntries);
187 }
188
189 /**
190 * Load CSS.
191 *
192 * @param <K> the keyType
193 * @param pKey the styleSheetKey
194 * @throws OceanusException on error
195 */
196 protected <K extends Enum<K> & TethysUIStyleSheetId> void loadCSS(final K pKey) throws OceanusException {
197 theCSS = pKey;
198 }
199
200 /**
201 * Load Help entries from the file system.
202 *
203 * @param pEntries the Help Entries
204 * @throws OceanusException on error
205 */
206 private static void loadHelpPages(final List<MetisHelpEntry> pEntries) throws OceanusException {
207 /* Loop through the entities */
208 for (MetisHelpEntry myEntry : pEntries) {
209 /* If we have a helpId */
210 if (myEntry.getHelpId() != null) {
211 /* Reset the builder */
212 final String myPage = OceanusResourceLoader.loadResourceToString(myEntry.getHelpId());
213
214 /* Set the HTML for the entry */
215 myEntry.setHtml(myPage);
216 }
217
218 /* If we have children */
219 if (myEntry.getChildren() != null) {
220 /* Load the entries */
221 loadHelpPages(myEntry.getChildren());
222 }
223 }
224 }
225 }