001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://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: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://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     * Gets the CSS head includes.<p>
079     *
080     * @return the CSS head includes
081     */
082    Set<String> getCssHeadIncludes();
083
084    /**
085     * Gets the formatter description.<p>
086     *
087     * If a locale is passed in, macros in the configured description will be resolved with a macro resolver set to that locale.
088     * If null is passed in as a locale, the raw configured description will be returned.
089     *
090     * @param locale the locale (may be null)
091     *
092     * @return the formatter description
093     */
094    String getDescription(Locale locale);
095
096    /**
097     * The display type of this formatter or <code>null</code> in case this is not a display formatter.<p>
098     *
099     * @return the display type
100     */
101    String getDisplayType();
102
103    /**
104     * Returns the id of this formatter.<p>
105     *
106     * This method may return null because the id is not always defined for formatters, e.g. for those formatters declared in a schema.<p>
107     *
108     * @return the formatter id
109     */
110    String getId();
111
112    /**
113     * Gets the inline CSS snippets.<p>
114     *
115     * @return the inline CSS snippets
116     */
117    String getInlineCss();
118
119    /**
120     * Gets the inline JS snippets.<p>
121     *
122     * @return the inline JS snippets
123     */
124    String getInlineJavascript();
125
126    /**
127     * Gets the Javascript head includes.<p>
128     *
129     * @return the head includes
130     */
131    List<String> getJavascriptHeadIncludes();
132
133    /**
134     * Returns the root path of the formatter JSP in the OpenCms VFS.<p>
135     *
136     * @return the root path of the formatter JSP in the OpenCms VFS.<p>
137     */
138    String getJspRootPath();
139
140    /**
141     * Returns the structure id of the JSP resource for this formatter.<p>
142     *
143     * @return the structure id of the JSP resource for this formatter
144     */
145    CmsUUID getJspStructureId();
146
147    /**
148     * Gets the formatter key, or null if no formatter key is set.
149     *
150     * <p>A formatter key is used to allow dynamic switching between formatters with the same key by enabling/disabling the formatters
151     * in the sitemap configuration. I.e. if a formatter referenced in a container page has been disabled in the sitemap configuration,
152     * but a different formatter with the same key is enabled, the second formatter will be used instead when rendering the page .
153     *
154     * @return the formatter key, or null
155     */
156    String getKey();
157
158    /**
159     * Helper method for getting either the key, if it exists, or the ID (as a string) if it does not.
160     *
161     * @return the formatter key or id
162     */
163    default String getKeyOrId() {
164
165        if (getKey() != null) {
166            return getKey();
167        }
168        return getId();
169    }
170
171    /**
172     * Returns the location this formatter was defined in.<p>
173     *
174     * This will be an OpenCms VFS root path, either to the XML schema XSD, or the
175     * configuration file this formatter was defined in, or to the JSP that
176     * makes up this formatter.<p>
177     *
178     * @return the location this formatter was defined in
179     */
180    String getLocation();
181
182    /**
183     * Returns the maximum formatter width.<p>
184     *
185     * If this is not set, then {@link Integer#MAX_VALUE} is returned.<p>
186     *
187     * @return the maximum formatter width
188     */
189    int getMaxWidth();
190
191    /**
192     * Returns the meta mappings.<p>
193     *
194     * @return the meta mappings
195     */
196    List<CmsMetaMapping> getMetaMappings();
197
198    /**
199     * Returns the minimum formatter width.<p>
200     *
201     * If this is not set, then <code>-1</code> is returned.<p>
202     *
203     * @return the minimum formatter width
204     */
205    int getMinWidth();
206
207    /**
208     * Gets the nice name for this formatter.<p>
209     *
210     * @param locale the locale
211     *
212     * @return the nice name for this formatter
213     */
214    String getNiceName(Locale locale);
215
216    /**
217     * Gets the rank.<p>
218     *
219     * @return the rank
220     */
221    int getRank();
222
223    /**
224     * Gets the resource type names.<p>
225     *
226     * @return the resource type names
227     */
228    Collection<String> getResourceTypeNames();
229
230    /**
231     * Gets the defined settings.<p>
232     *
233     * @param sitemapConfig the sitemap configuration for which the settings should be retrieved
234     *
235     * @return the defined settings
236     */
237    Map<String, CmsXmlContentProperty> getSettings(CmsADEConfigData sitemapConfig);
238
239    /**
240     * Gets the template plugins.
241     *
242     * @return the template plugins
243     */
244    List<CmsTemplatePlugin> getTemplatePlugins();
245
246    /**
247     * Returns if nested formatter settings should be displayed.<p>
248     *
249     * @return <code>true</code> if nested formatter settings should be displayed
250     */
251    boolean hasNestedFormatterSettings();
252
253    /**
254     * Returns whether this formatter allows settings to be edited in the content editor.<p>
255     *
256     * @return <code>true</code> in case editing the settings is allowed in the content editor
257     */
258    boolean isAllowsSettingsInEditor();
259
260    /**
261     * Returns true if the formatter is automatically enabled.<p>
262     *
263     * @return true if the formatter is automatically enabled
264     */
265    boolean isAutoEnabled();
266
267    /**
268     * Returns true if the formatter can be used for detail views.<p>
269     *
270     * @return true if the formatter can be used for detail views
271     */
272    boolean isDetailFormatter();
273
274    /**
275     * Returns whether this formatter should be used by the 'display' tag.<p>
276     *
277     * @return <code>true</code> if this formatter should be used by the 'display' tag
278     */
279    boolean isDisplayFormatter();
280
281    /**
282     * Returns true if the formatter is from a formatter configuration file.<p>
283     *
284     * @return formatter f
285     */
286    boolean isFromFormatterConfigFile();
287
288    /**
289     * Returns true if this formatter should match all type/width combinations.<p>
290     *
291     * @return true if this formatter should match all type/width combinations
292     */
293    boolean isMatchAll();
294
295    /**
296     * Indicates if this formatter is to be used as preview in the ADE gallery GUI.
297     *
298     * @return <code>true</code> if this formatter is to be used as preview in the ADE gallery GUI
299     */
300    boolean isPreviewFormatter();
301
302    /**
303     * Returns <code>true</code> in case an XML content formatted with this formatter should be included in the
304     * online full text search.<p>
305     *
306     * @return <code>true</code> in case an XML content formatted with this formatter should be included in the
307     * online full text search
308     */
309    boolean isSearchContent();
310
311    /**
312     * Returns <code>true</code> in case this formatter is based on type information.<p>
313     *
314     * @return <code>true</code> in case this formatter is based on type information
315     */
316    boolean isTypeFormatter();
317
318    /**
319     * Sets the JSP structure id.<p>
320     *
321     * @param structureId the jsp structure id
322     */
323    void setJspStructureId(CmsUUID structureId);
324
325    /**
326     * Returns true if meta mappings should be evaluated for normal container elements using this formatter, not just detail elements.<p>
327     *
328     * @return true if meta mappings should be evaluated for normal container elements
329     */
330    boolean useMetaMappingsForNormalElements();
331
332    /**
333     * If possible, returns a formatter bean that is basically a copy of this one, but has the keys supplied
334     * as a parameter.
335     *
336     * <p>Note that this only works for formatters which already have a key, and can not replace the main key. If the keys
337     * already match, the current instance may be returned rather than a copy.
338     *
339     * <p>If the formatter bean implementation does not support key replacement, or an error occurs, an empty Optional is returned
340     *
341     * @param keys the keys to use (should include the current key of the formatter
342     * @return the copy with the replaced keys
343     */
344    Optional<I_CmsFormatterBean> withKeys(Collection<String> keys);
345
346}