001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (C) Alkacon Software (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.loader;
029
030import org.opencms.file.CmsObject;
031import org.opencms.file.CmsResource;
032import org.opencms.main.CmsException;
033import org.opencms.util.CmsUUID;
034
035import java.util.Locale;
036import java.util.Map;
037import java.util.Set;
038
039import javax.servlet.http.HttpServletRequest;
040
041/**
042 * Interface for template context providers.<p>
043 *
044 * Implementations of this class are used to dynamically determine a template used for rendering
045 * a page at runtime, e.g. there could be one template for desktop browsers and another for mobile
046 * browsers.
047 *
048 * It is possible to override the template using a cookie containing the name of the template context
049 * which should be used as a value. The cookie name is determined by the template context provider.<p>
050 */
051public interface I_CmsTemplateContextProvider {
052
053    /**
054     * Gets a map of all template contexts, with the template context names as keys.<p>
055     *
056     * @return the map of template context providers
057     */
058    Map<String, CmsTemplateContext> getAllContexts();
059
060    /**
061     * Customizes the label for the default template context option.
062     *
063     * <p>If null is returned, the default label for the default template will be used.
064     *
065     * If null is returned, a default
066     * @param locale the locale for i18n
067     * @return the label for the default template context option
068     */
069    default String getDefaultLabel(Locale locale) {
070
071        return null;
072    }
073
074    /**
075     * Returns the style sheet to be used for the editor.<p>
076     *
077     * @param cms the current CMS context
078     * @param editedResourcePath the path of the edited resource
079     *
080     * @return the path of the style sheet to be used for the resource
081     */
082    String getEditorStyleSheet(CmsObject cms, String editedResourcePath);
083
084    /**
085     * Returns a set of structure ids of dynamic functions that are allowed to appear in the gallery dialog search results, or null if the dynamic function results should not be restricted.
086     *
087     *  <p>Note: Functions may be  excluded from the gallery dialog search results for other reasons even if they appear in the set returned by this method.
088     *
089     * @param cms the current CMS context
090     * @param templateContext the current template context key
091     * @return the set of ids of dynamic functions to allow in the gallery search results, or null if function results shouldn't be restricted
092     */
093    default Set<CmsUUID> getFunctionsForGallery(CmsObject cms, String templateContext) {
094
095        return null;
096    }
097
098    /**
099     * Gets the label to use for the menu entry in the given locale.
100     *
101     *  <p>If this returns null, the default menu entry label is used.
102     *
103     * @param locale the locale for which we want the menu entry label
104     * @return the menu entry label
105     */
106    default String getMenuLabel(Locale locale) {
107
108        return null;
109    }
110
111    /**
112     * Special integer that indicates the position for the template context selection in the context menu.
113     *
114     * <p>Currently can only return 0 or 1.
115     *
116     * @return the context menu position
117     */
118    default int getMenuPosition() {
119
120        return 0;
121    }
122
123    /**
124     * Gets the name of the cookie which should be used for overriding the template context.<p>
125     *
126     * @return the name of the cookie used for overriding the template context
127     */
128    String getOverrideCookieName();
129
130    /**
131     * Gets the template compatibility for the given template context key.
132     *
133     * <p>The template compatibility controls which elements are visible as gallery search results when the template
134     * with the given key is active. If the template.compatibility property on a resource is set (possibly inherited from a parent folder), but does not contain the
135     * compatibility value returned by this method, it will not show up in gallery search results when the template referenced by
136     * templateContextKey is active.
137     *
138     * @param templateContextKey the key for a template context
139     * @return a template compatibility string (should not contain whitespace or punctuation)
140     */
141    default String getTemplateCompatibility(String templateContextKey) {
142
143        return null;
144    }
145
146    /**
147     * Determines the template context from the current CMS context, request, and resource.<p>
148     *
149     * @param cms the CMS context
150     * @param request the current request
151     * @param resource the resource being rendered
152     *
153     * @return the current template context
154     */
155    CmsTemplateContext getTemplateContext(CmsObject cms, HttpServletRequest request, CmsResource resource);
156
157    /**
158     * Initializes the context provider using a CMS object.<p>
159     *
160     * <p>Initialization always happens in the Online project.
161     *
162     * @param cms the current CMS context
163     * @param config the template context provider configuration
164     */
165    void initialize(CmsObject cms, String config);
166
167    /**
168     * Checks if the template context should be hidden in the GUI.
169     *
170     * @param key the key of a template context
171     * @return true if the template context should be hidden in the GUI
172     */
173    default boolean isHiddenContext(String key) {
174
175        return false;
176    }
177
178    /**
179     * Checks if the 'templateContexts' setting should be ignored when rendering container elements (i.e. they will be rendered by default, regardless of the setting value).
180     *
181     * @return true if the templateContexts setting should be ignored by the cms:container tag
182     */
183    default boolean isIgnoreTemplateContextsSetting() {
184        return false;
185    }
186
187    /**
188     * Gets the value which should be used instead of a property which was read from the template resource.<p>
189     *
190     * This is needed because before template context providers, it was common to store template-specific configuration in
191     * a property on the template JSP. Since template context providers make the result ambiguous, this method is intended
192     * as a replacement.<p>
193     *
194     * @param cms the CMS context to use
195     * @param propertyName the name of the property
196     * @param fallbackValue the value to return if no value is found or an error occurs
197     *
198     * @return the common property value
199     *
200     * @throws CmsException if something goes wrong
201     */
202    String readCommonProperty(CmsObject cms, String propertyName, String fallbackValue) throws CmsException;
203
204    /**
205     * Checks if the context menu option for switching the template should be shown for the given user context.
206     *
207     * @param cms the CmsObject to check
208     * @return true if the context menu option should be visible
209     */
210    default boolean shouldShowContextMenuOption(CmsObject cms) {
211
212        return true;
213    }
214
215    /**
216     * Controls whether template context select options should be shown in the element settings dialog.
217     *
218     * @param cms the CmsObject for the current user
219     * @return true if the template context select options should be shown in the element settings dialog
220     */
221    default boolean shouldShowElementTemplateContextSelection(CmsObject cms) {
222
223        return true;
224    }
225
226}