View Javadoc

1   /**
2    * This file Copyright (c) 2012 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 that is a nested class (public static class) within another controller that is
43   * either annotated with @Template or in the case of an area within an area annotated with @Area.
44   * <p/>
45   * An area has a unique name within its enclosing template or parent area. The title set using the <code>title</code>
46   * field is used both on the page as the displayed name of the area and as the title for the area's dialog.
47   * <p/>
48   * An area can have configurable content that is edited by its dialog. A controller that uses this annotation
49   * automatically becomes a factory for its own dialog. This dialog is automatically assigned an id and you do not need
50   * to add the {@link info.magnolia.module.blossom.annotation.DialogFactory} annotation. The functionality for creating
51   * the dialog is identical to the functionality of classes that use
52   * {@link info.magnolia.module.blossom.annotation.DialogFactory}. More specifically you can use {@link TabFactory},
53   * {@link TabValidator}, {@link DialogValidator} and {@link TabOrder}.
54   * <p/>
55   * If you prefer using a dialog created by a {@link DialogFactory} or one configured in Magnolia you can override this
56   * behaviour by setting the 'dialog' field.
57   * <p/>
58   * By using {@link AvailableComponents} and {@link AvailableComponentClasses} you can configure which components can be
59   * added to this area.
60   * <p/>
61   * The type of the area controls how the area can be used with regard to if and how many components can be placed in it.
62   * <p/>
63   * An area can be set to inherit components from areas with the same name in parent pages. This is done using
64   * {@link Inherits}. Inheritance is by default set to inherit all components with a property <code>inheritable</code>
65   * set to true (filtered mode). Inheritance can also be enabled for properties on the area making it possible for
66   * settings on the area itself to take effect on sub-pages.
67   * <p/>
68   * An optional area is an area that the page author can decide to use or not. The area won't be rendered unless the
69   * page author explicitly creates it on the page.
70   * <p/>
71   * You can use {@link info.magnolia.module.blossom.annotation.I18nBasename} to specify which resource bundle should be
72   * used for localization of the area's title and description.
73   *
74   * @see info.magnolia.module.blossom.annotation.AvailableComponents
75   * @see info.magnolia.module.blossom.annotation.AvailableComponentClasses
76   * @see info.magnolia.module.blossom.annotation.Inherits
77   * @see info.magnolia.module.blossom.annotation.TabOrder
78   * @see info.magnolia.module.blossom.annotation.TabFactory
79   * @see info.magnolia.module.blossom.annotation.TabValidator
80   * @see info.magnolia.module.blossom.annotation.DialogValidator
81   * @see info.magnolia.module.blossom.annotation.Available
82   * @see info.magnolia.module.blossom.annotation.I18nBasename
83   * @see info.magnolia.module.blossom.annotation.DialogFactory
84   * @since 2.0
85   */
86  @Retention(RetentionPolicy.RUNTIME)
87  @Target(ElementType.TYPE)
88  public @interface Area {
89  
90      /**
91       * Name of the area.
92       */
93      String value();
94  
95      String title() default "";
96  
97      /**
98       * Id of a dialog to be used for this area. By default the controller itself will be responsible for
99       * creating the dialog.
100      */
101     String dialog() default "";
102 
103     /**
104      * The type of area.
105      */
106     AreaType type() default AreaType.LIST;
107 
108     /**
109      * Whether this area is optional or not.
110      */
111     TernaryBoolean optional() default TernaryBoolean.UNSPECIFIED;
112 
113 }