001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (https://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software, please see the
018 * company website: https://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: https://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.xml.containerpage;
029
030import org.opencms.ade.configuration.CmsADEConfigData;
031import org.opencms.ade.configuration.plugins.CmsTemplatePlugin;
032import org.opencms.util.CmsUUID;
033import org.opencms.xml.content.CmsXmlContentProperty;
034
035import java.util.Collection;
036import java.util.List;
037import java.util.Locale;
038import java.util.Map;
039import java.util.Optional;
040import java.util.Set;
041
042/**
043 * Interface representing a configured formatter.<p>
044 */
045public interface I_CmsFormatterBean {
046
047    /**
048     * Gets the set of alias keys for the formatter.
049     *
050     * @return the set of alias keys
051     */
052    Set<String> getAliasKeys();
053
054    /**
055     * Gets the complete set of keys for the formatter, i.e. its main key and all alias keys.
056     *
057     * @return the complete set of keys
058     */
059    Set<String> getAllKeys();
060
061    /**
062     * Gets the map of attributes.<p>
063     *
064     * @return the attribute map
065     */
066    Map<String, String> getAttributes();
067
068    /**
069     * Returns the formatter container type.<p>
070     *
071     * If this is "*", then the formatter is a width based formatter.<p>
072     *
073     * @return the formatter container type
074     */
075    Set<String> getContainerTypes();
076
077    /**
078     * Returns the content extraction policy, or <code>null</code> if not configured.<p>
079     *
080     * @return the content extraction policy
081     */
082    default String getContentExtractionPolicy() {
083
084        return null;
085    }
086
087    /**
088     * Gets the CSS head includes.<p>
089     *
090     * @return the CSS head includes
091     */
092    Set<String> getCssHeadIncludes();
093
094    /**
095     * Gets the formatter description.<p>
096     *
097     * If a locale is passed in, macros in the configured description will be resolved with a macro resolver set to that locale.
098     * If null is passed in as a locale, the raw configured description will be returned.
099     *
100     * @param locale the locale (may be null)
101     *
102     * @return the formatter description
103     */
104    String getDescription(Locale locale);
105
106    /**
107     * The display type of this formatter or <code>null</code> in case this is not a display formatter.<p>
108     *
109     * @return the display type
110     */
111    String getDisplayType();
112
113    /**
114     * Returns the id of this formatter.<p>
115     *
116     * This method may return null because the id is not always defined for formatters, e.g. for those formatters declared in a schema.<p>
117     *
118     * @return the formatter id
119     */
120    String getId();
121
122    /**
123     * Gets the inline CSS snippets.<p>
124     *
125     * @return the inline CSS snippets
126     */
127    String getInlineCss();
128
129    /**
130     * Gets the inline JS snippets.<p>
131     *
132     * @return the inline JS snippets
133     */
134    String getInlineJavascript();
135
136    /**
137     * Gets the Javascript head includes.<p>
138     *
139     * @return the head includes
140     */
141    List<String> getJavascriptHeadIncludes();
142
143    /**
144     * Returns the root path of the formatter JSP in the OpenCms VFS.<p>
145     *
146     * @return the root path of the formatter JSP in the OpenCms VFS.<p>
147     */
148    String getJspRootPath();
149
150    /**
151     * Returns the structure id of the JSP resource for this formatter.<p>
152     *
153     * @return the structure id of the JSP resource for this formatter
154     */
155    CmsUUID getJspStructureId();
156
157    /**
158     * Gets the formatter key, or null if no formatter key is set.
159     *
160     * <p>A formatter key is used to allow dynamic switching between formatters with the same key by enabling/disabling the formatters
161     * in the sitemap configuration. I.e. if a formatter referenced in a container page has been disabled in the sitemap configuration,
162     * but a different formatter with the same key is enabled, the second formatter will be used instead when rendering the page .
163     *
164     * @return the formatter key, or null
165     */
166    String getKey();
167
168    /**
169     * Helper method for getting either the key, if it exists, or the ID (as a string) if it does not.
170     *
171     * @return the formatter key or id
172     */
173    default String getKeyOrId() {
174
175        if (getKey() != null) {
176            return getKey();
177        }
178        return getId();
179    }
180
181    /**
182     * Returns the location this formatter was defined in.<p>
183     *
184     * This will be an OpenCms VFS root path, either to the XML schema XSD, or the
185     * configuration file this formatter was defined in, or to the JSP that
186     * makes up this formatter.<p>
187     *
188     * @return the location this formatter was defined in
189     */
190    String getLocation();
191
192    /**
193     * Returns the maximum formatter width.<p>
194     *
195     * If this is not set, then {@link Integer#MAX_VALUE} is returned.<p>
196     *
197     * @return the maximum formatter width
198     */
199    int getMaxWidth();
200
201    /**
202     * Returns the meta mappings.<p>
203     *
204     * @return the meta mappings
205     */
206    List<CmsMetaMapping> getMetaMappings();
207
208    /**
209     * Returns the minimum formatter width.<p>
210     *
211     * If this is not set, then <code>-1</code> is returned.<p>
212     *
213     * @return the minimum formatter width
214     */
215    int getMinWidth();
216
217    /**
218     * Gets the nice name for this formatter.<p>
219     *
220     * @param locale the locale
221     *
222     * @return the nice name for this formatter
223     */
224    String getNiceName(Locale locale);
225
226    /**
227     * Gets the rank.<p>
228     *
229     * @return the rank
230     */
231    int getRank();
232
233    /**
234     * Gets the resource type names.<p>
235     *
236     * @return the resource type names
237     */
238    Collection<String> getResourceTypeNames();
239
240    /**
241     * Gets the defined settings.<p>
242     *
243     * @param sitemapConfig the sitemap configuration for which the settings should be retrieved
244     *
245     * @return the defined settings
246     */
247    Map<String, CmsXmlContentProperty> getSettings(CmsADEConfigData sitemapConfig);
248
249    /**
250     * Gets the template plugins.
251     *
252     * @return the template plugins
253     */
254    List<CmsTemplatePlugin> getTemplatePlugins();
255
256    /**
257     * Returns if nested formatter settings should be displayed.<p>
258     *
259     * @return <code>true</code> if nested formatter settings should be displayed
260     */
261    boolean hasNestedFormatterSettings();
262
263    /**
264     * Returns whether this formatter allows settings to be edited in the content editor.<p>
265     *
266     * @return <code>true</code> in case editing the settings is allowed in the content editor
267     */
268    boolean isAllowsSettingsInEditor();
269
270    /**
271     * Returns true if the formatter is automatically enabled.<p>
272     *
273     * @return true if the formatter is automatically enabled
274     */
275    boolean isAutoEnabled();
276
277    /**
278     * Returns true if the formatter can be used for detail views.<p>
279     *
280     * @return true if the formatter can be used for detail views
281     */
282    boolean isDetailFormatter();
283
284    /**
285     * Returns whether this formatter should be used by the 'display' tag.<p>
286     *
287     * @return <code>true</code> if this formatter should be used by the 'display' tag
288     */
289    boolean isDisplayFormatter();
290
291    /**
292     * Returns true if the formatter is from a formatter configuration file.<p>
293     *
294     * @return formatter f
295     */
296    boolean isFromFormatterConfigFile();
297
298    /**
299     * Returns true if this formatter should match all type/width combinations.<p>
300     *
301     * @return true if this formatter should match all type/width combinations
302     */
303    boolean isMatchAll();
304
305    /**
306     * Indicates if this formatter is to be used as preview in the ADE gallery GUI.
307     *
308     * @return <code>true</code> if this formatter is to be used as preview in the ADE gallery GUI
309     */
310    boolean isPreviewFormatter();
311
312    /**
313     * Returns <code>true</code> in case an XML content formatted with this formatter should be included in the
314     * online full text search.<p>
315     *
316     * @return <code>true</code> in case an XML content formatted with this formatter should be included in the
317     * online full text search
318     */
319    boolean isSearchContent();
320
321    /**
322     * Returns <code>true</code> in case this formatter is based on type information.<p>
323     *
324     * @return <code>true</code> in case this formatter is based on type information
325     */
326    boolean isTypeFormatter();
327
328    /**
329     * Sets the JSP structure id.<p>
330     *
331     * @param structureId the jsp structure id
332     */
333    void setJspStructureId(CmsUUID structureId);
334
335    /**
336     * Returns true if meta mappings should be evaluated for normal container elements using this formatter, not just detail elements.<p>
337     *
338     * @return true if meta mappings should be evaluated for normal container elements
339     */
340    boolean useMetaMappingsForNormalElements();
341
342    /**
343     * If possible, returns a formatter bean that is basically a copy of this one, but has the keys supplied
344     * as a parameter.
345     *
346     * <p>Note that this only works for formatters which already have a key, and can not replace the main key. If the keys
347     * already match, the current instance may be returned rather than a copy.
348     *
349     * <p>If the formatter bean implementation does not support key replacement, or an error occurs, an empty Optional is returned
350     *
351     * @param keys the keys to use (should include the current key of the formatter
352     * @return the copy with the replaced keys
353     */
354    Optional<I_CmsFormatterBean> withKeys(Collection<String> keys);
355
356}