001    /**
002     * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
013     */
014    
015    package com.liferay.portal.kernel.template;
016    
017    import aQute.bnd.annotation.ProviderType;
018    
019    import com.liferay.portal.kernel.xml.Element;
020    
021    import java.util.List;
022    import java.util.Locale;
023    import java.util.Map;
024    
025    /**
026     * @author Juan Fern??ndez
027     */
028    @ProviderType
029    public interface TemplateHandler {
030    
031            /**
032             * Returns the template handler's class name.
033             *
034             * @return the template handler's class name
035             */
036            public String getClassName();
037    
038            public Map<String, Object> getCustomContextObjects();
039    
040            /**
041             * Returns the elements containing the information of the portlet display
042             * templates to be installed by default.
043             *
044             * @return the elements containing the information of the portlet display
045             *         templates to be installed by default. These templates are
046             *         installed when registering the portlet.
047             * @throws Exception if an exception occurred assembling the default
048             *         template elements
049             */
050            public List<Element> getDefaultTemplateElements() throws Exception;
051    
052            /**
053             * Returns the key of the template handler's default template.
054             *
055             * @return the key of the template handler's default template
056             */
057            public String getDefaultTemplateKey();
058    
059            /**
060             * Returns the template handler's name.
061             *
062             * @param  locale the locale of the template handler name to get
063             * @return the template handler's name
064             */
065            public String getName(Locale locale);
066    
067            /**
068             * Returns the name of the resource associated with the template.
069             * Permissions on the resource are checked when adding a new template.
070             *
071             * @return the name of the resource associated with the template
072             */
073            public String getResourceName();
074    
075            /**
076             * Returns the restricted variables that are excluded from the template's
077             * context.
078             *
079             * @param  language the template's scripting language. Acceptable values for
080             *         the FreeMarker, Velocity, or XSL languages are {@link
081             *         TemplateConstants#LANG_TYPE_FTL}, {@link
082             *         TemplateConstants#LANG_TYPE_VM}, or {@link
083             *         TemplateConstants#LANG_TYPE_XSL}, respectively.
084             * @return the restricted variables that are excluded from the template's
085             *         context
086             */
087            public String[] getRestrictedVariables(String language);
088    
089            /**
090             * Returns initial template content for helping the user create a new
091             * template.
092             *
093             * @param  language the template's scripting language. Acceptable values for
094             *         the FreeMarker, Velocity, or XSL languages are {@link
095             *         TemplateConstants#LANG_TYPE_FTL}, {@link
096             *         TemplateConstants#LANG_TYPE_VM}, or {@link
097             *         TemplateConstants#LANG_TYPE_XSL}, respectively.
098             * @return initial template content for helping the user create a new
099             *         template
100             */
101            public String getTemplatesHelpContent(String language);
102    
103            /**
104             * Returns the path to the template's help content.
105             *
106             * @param  language the template's scripting language. Acceptable values for
107             *         the FreeMarker, Velocity, or XSL languages are {@link
108             *         TemplateConstants#LANG_TYPE_FTL}, {@link
109             *         TemplateConstants#LANG_TYPE_VM}, or {@link
110             *         TemplateConstants#LANG_TYPE_XSL}, respectively.
111             * @return the path to the template's help content
112             */
113            public String getTemplatesHelpPath(String language);
114    
115            /**
116             * Returns the name of the property in <code>portal.properties</code> that
117             * defines the path to the template's help content.
118             *
119             * @return the name of the property in <code>portal.properties</code> that
120             *         defines the path to the template's help content
121             */
122            public String getTemplatesHelpPropertyKey();
123    
124            /**
125             * Returns the template's map of script variable groups for which hints are
126             * displayed in the template editor palette.
127             *
128             * <p>
129             * Script variables can be grouped arbitrarily. As examples, a group of
130             * entity fields could be mapped to the keyword <code>Fields</code>, or a
131             * group of general variables portal variables could be mapped to the phrase
132             * <code>General Variables</code>, etc.
133             * </p>
134             *
135             * @param  classPK the primary key of the entity that defines the variable
136             *         groups for the template. For example, consider specifying the
137             *         primary key of the structure associated to the template.
138             * @param  language the template's scripting language. Acceptable values for
139             *         the FreeMarker, Velocity, or XSL languages are {@link
140             *         TemplateConstants#LANG_TYPE_FTL}, {@link
141             *         TemplateConstants#LANG_TYPE_VM}, or {@link
142             *         TemplateConstants#LANG_TYPE_XSL}, respectively.
143             * @param  locale the locale of the variable groups to get
144             * @return the template's map of script variable groups for which hints are
145             *         displayed in the template editor palette
146             * @throws Exception if an exception occurred retrieving the template
147             *         variable groups
148             */
149            public Map<String, TemplateVariableGroup> getTemplateVariableGroups(
150                            long classPK, String language, Locale locale)
151                    throws Exception;
152    
153            public boolean isDisplayTemplateHandler();
154    
155    }