View Javadoc

1   /**
2    * This file Copyright (c) 2003-2010 Magnolia International
3    * Ltd.  (http://www.magnolia-cms.com). All rights reserved.
4    *
5    *
6    * This file is dual-licensed under both the Magnolia
7    * Network Agreement and the GNU General Public License.
8    * You may elect to use one or the other of these licenses.
9    *
10   * This file is distributed in the hope that it will be
11   * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
12   * implied warranty of MERCHANTABILITY or FITNESS FOR A
13   * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
14   * Redistribution, except as permitted by whichever of the GPL
15   * or MNA you select, is prohibited.
16   *
17   * 1. For the GPL license (GPL), you can redistribute and/or
18   * modify this file under the terms of the GNU General
19   * Public License, Version 3, as published by the Free Software
20   * Foundation.  You should have received a copy of the GNU
21   * General Public License, Version 3 along with this program;
22   * if not, write to the Free Software Foundation, Inc., 51
23   * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
24   *
25   * 2. For the Magnolia Network Agreement (MNA), this file
26   * and the accompanying materials are made available under the
27   * terms of the MNA which accompanies this distribution, and
28   * is available at http://www.magnolia-cms.com/mna.html
29   *
30   * Any modifications to this file must keep this entire header
31   * intact.
32   *
33   */
34  package info.magnolia.module.templating;
35  
36  import info.magnolia.cms.core.Content;
37  import info.magnolia.cms.i18n.Messages;
38  import info.magnolia.cms.i18n.MessagesManager;
39  import info.magnolia.cms.security.AccessManager;
40  import info.magnolia.cms.security.Permission;
41  import info.magnolia.cms.util.DeprecationUtil;
42  import info.magnolia.context.MgnlContext;
43  
44  import java.util.HashMap;
45  import java.util.Map;
46  
47  /**
48   * Represents a template definition.
49   * Following are some of the most common properties you can use to configure your templates. Of course, if you're using specific subclasses, other properties could be available.
50   * <br/>
51   * <br/>
52   * <table border="1">
53   * <tbody>
54   * <tr>
55   * <th>Name of Property</th>
56   * <th>Default Value</th>
57   * <th>Value Example or Range</th>
58   * <th>Description</th>
59   * </tr>
60   * <tr>
61   * <td>class</td>
62   * <td>{@link Template}</td>
63   * <td>&nbsp;</td>
64   * <td>&nbsp;</td>
65   * </tr>
66   * <tr>
67   * <td>type</td>
68   * <td> <code>jsp</code></td>
69   * <td> <code>jsp</code>, <code>freemarker</code>, …</td>
70   * <td>Determines which <code>TemplateRenderer</code> to use. Out of the box,
71   * Magnolia provides support for JSP and FreeMarker.</td>
72   * </tr>
73   * <tr>
74   * <td>templatePath</td>
75   * <td>&nbsp;</td>
76   * <td>Conventional path syntax is used for this property.</td>
77   * <td>This property defines the URI to the template which is normally a JSP.
78   * The path for the template is relative to the root and structure of the webapp
79   * folder.</td>
80   * </tr>
81   * <tr>
82   * <td>visible</td>
83   * <td><code>true</code></td>
84   * <td><code>true</code>, <code>false</code></td>
85   * <td>This property determines if the template is visible in the template
86   * drop-down list. If a template is to be restricted so that only certain users
87   * can see it in the drop-down list, a role needs to be defined in security
88   * which denies access to the particular template definition content node.</td>
89   * </tr>
90   * <tr>
91   * <td>modelClass</td>
92   * <td>&nbsp;</td>
93   * <td>The fully qualified name of a class implementing {@link RenderingModel}
94   * </td>
95   * <td>The bean created by the renderer based on the modelClass defined on the
96   * paragraph or template definition. The current content, definition and the
97   * parent model are passed to the constructor. This object is instantiated for
98   * each rendering of a template or a paragraph.</td>
99   * </tr>
100  * <tr>
101  * <td>subTemplates</td>
102  * <td>&nbsp;</td>
103  * <td>Any valid node identifier.</td>
104  * <td>This property designates a node containing any subtemplates to be used by
105  * the template.</td>
106  * </tr>
107  * <tr>
108  * <td>name</td>
109  * <td>nodeName</td>
110  * <td>Naming conventions should be followed using standard alphanumerical
111  * characters only.</td>
112  * <td>This property lists the name of the template.</td>
113  * </tr>
114  * <tr>
115  * <td>i18nBasename</td>
116  * <td>&nbsp;</td>
117  * <td>Naming conventions should be followed using standard alphanumerical
118  * characters only.</td>
119  * <td>This property defines the message bundle to use for this template.</td>
120  * </tr>
121  * <tr>
122  * <td>title</td>
123  * <td>&nbsp;</td>
124  * <td>The title or a message bundle key to be used with the bundle defined by
125  * <code>i18nBasename</code>.</td>
126  * <td>This property designates the title of the template. The i18nBasename
127  * (designated message bundle) renders the title.</td>
128  * </tr>
129  * <tr>
130  * <td>description</td>
131  * <td>&nbsp;</td>
132  * <td>The description or a message bundle key to be used with the bundle
133  * defined by <code>i18nBasename</code>.</td>
134  * <td>This property contains the description of the template. Descriptions
135  * should be intuitive and provide a context for users and/or developers to
136  * understand how the overall template functions.</td>
137  * </tr>
138  * </tbody>
139  * </table>
140  *
141  * @author Sameer Charles
142  * @author Fabrizio Giustina
143  * @version $Revision: 36512 $ ($Author: fgrilli $)
144  */
145 public class Template extends AbstractRenderable {
146     private Content content;
147 
148     private boolean visible = true;
149 
150     private Map<String, Template> subTemplates = new HashMap<String, Template>();
151 
152     /**
153      * Used internally for SubTemplates.
154      */
155     public Template() {
156 
157     }
158 
159     /**
160      * Getter for <code>path</code>.
161      * @return Returns the path.
162      * @deprecated since 4.0. use getTemplatePath() instead
163      */
164     public String getPath() {
165         DeprecationUtil.isDeprecated("The 'path' property is deprecated: use the templatePath property instead. (current value: " + getTemplatePath() + ")");
166         return getTemplatePath();
167     }
168 
169 
170     public String getI18NTitle() {
171         Messages msgs = MessagesManager.getMessages(getI18nBasename());
172 
173         return msgs.getWithDefault(getTitle(), getTitle());
174     }
175 
176     public String getParameter(String key) {
177         return (String) getParameters().get(key);
178     }
179 
180     /**
181      * Getter for <code>visible</code>.
182      * @return Returns the visible.
183      */
184     public boolean isVisible() {
185         return this.visible;
186     }
187 
188     public Template getSubTemplate(String extension) {
189         return this.subTemplates.get(extension);
190     }
191 
192     public void addSubTemplate(String extension, Template subTemplate) {
193         this.subTemplates.put(extension, subTemplate);
194     }
195 
196     public Map<String, Template> getSubTemplates() {
197         return this.subTemplates;
198     }
199 
200     public void setSubTemplates(Map<String, Template> subTemplates) {
201         this.subTemplates = subTemplates;
202     }
203 
204     /**
205      * @deprecated since 4.0 use {@link #setTemplatePath(String)}
206      */
207     public void setPath(String path) {
208         // log message can only output the templatePath, as there is not guarantee the name or content name have been set already
209         DeprecationUtil.isDeprecated("The 'path' property is deprecated: use the templatePath property instead. (setting to value: " + path + ")");
210         setTemplatePath(path);
211     }
212 
213     public void setVisible(boolean visible) {
214         this.visible = visible;
215     }
216 
217     public boolean isAvailable(Content node) {
218         // TODO is called quite often and should be faster
219         AccessManager am = MgnlContext.getAccessManager(getContent().getHierarchyManager().getName());
220         return am.isGranted(getContent().getHandle(), Permission.READ);
221     }
222 
223     public Content getContent() {
224         return this.content;
225     }
226 
227     // this is set by content2bean
228     public void setContent(Content content) {
229         this.content = content;
230     }
231 
232 }