1 /**
2 * This file Copyright (c) 2003-2011 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.blossom.annotation;
35
36 import java.lang.annotation.ElementType;
37 import java.lang.annotation.Retention;
38 import java.lang.annotation.RetentionPolicy;
39 import java.lang.annotation.Target;
40
41 /**
42 * Used on a Spring Web MVC controller to expose it as a template. A template is either used to render a page or a
43 * component.
44 * <p/>
45 * The title of the template is set with this annotation while the description is set using
46 * {@link info.magnolia.module.blossom.annotation.TemplateDescription}.
47 * <p/>
48 * A component is added to a page using a dialog. A controller that uses this annotation automatically becomes a factory
49 * for its dialog. This dialog is automatically assigned an id and you do not need to add the
50 * {@link info.magnolia.module.blossom.annotation.DialogFactory} annotation. The functionality for creating the dialog
51 * is identical to the functionality of classes that use {@link info.magnolia.module.blossom.annotation.DialogFactory}.
52 * More specifically you can use {@link TabFactory}, {@link TabValidator}, {@link DialogValidator} and {@link TabOrder}.
53 * <p/>
54 * If you prefer using a dialog created by a {@link DialogFactory} or one configured in Magnolia you can override this
55 * behaviour by setting the 'dialog' field.
56 * <p/>
57 * The class will also be scanned for methods annotated with {@link DialogFactory}. This makes it possible to declare
58 * dialogs in the same template that they're used for.
59 * <p/>
60 * It is possible to restrict on which pages a template can be used by using the
61 * {@link info.magnolia.module.blossom.annotation.Available} annotation.
62 * <p/>
63 * You can use {@link info.magnolia.module.blossom.annotation.I18nBasename} to specify which resource bundle should be
64 * used for localization of the template's title and description.
65 * <p/>
66 * For example this template will be exposed with the id "mainTemplate":
67 * <pre>
68 * @Controller
69 * @Template(title = "Main", id = "moduleName:pages/main")
70 * public class MainTemplate {
71 * @RequestMapping("/mainTemplate")
72 * public String render() {
73 * return "mainTemplate.jsp";
74 * }
75 * @TabFactory("Content")
76 * public void contentTab(TabBuilder tab) {
77 * tab.addFckEditor("body", "Text", "Text");
78 * tab.addFile("image", "Image", "Image");
79 * }
80 * }
81 * </pre>
82 *
83 * @see info.magnolia.module.blossom.annotation.TemplateDescription
84 * @see info.magnolia.module.blossom.annotation.Area
85 * @see info.magnolia.module.blossom.annotation.TabOrder
86 * @see info.magnolia.module.blossom.annotation.TabFactory
87 * @see info.magnolia.module.blossom.annotation.TabValidator
88 * @see info.magnolia.module.blossom.annotation.DialogValidator
89 * @see info.magnolia.module.blossom.annotation.Available
90 * @see info.magnolia.module.blossom.annotation.I18nBasename
91 * @see info.magnolia.module.blossom.annotation.DialogFactory
92 * @since 1.0
93 */
94 @Retention(RetentionPolicy.RUNTIME)
95 @Target(ElementType.TYPE)
96 public @interface Template {
97
98 /**
99 * Id of the template. Templates intended to be used for pages must have an id in the format
100 * <code><moduleName>:pages/*</code> or if it's intended to be a component
101 * <code><moduleName>:components/*</code>. For example: <code>myModule:pages/mainTemplate</code> and
102 * <code>myModule:components/textAndImage</code>.
103 */
104 String id();
105
106 /**
107 * Title of the template.
108 */
109 String title();
110
111 /**
112 * Id of a dialog to be used for this template. By default the controller itself will be responsible for
113 * creating the dialog.
114 */
115 String dialog() default "";
116
117 /**
118 * Defines the visibility of the template. When set to false the template is never presented in the user interface.
119 * This is useful for templates that are only used for pages that are created by scheduled jobs rather than by
120 * editors.
121 */
122 boolean visible() default true;
123 }