1 /**
2 * Copyright 2005-2012 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krad.uif.container;
17
18 import org.kuali.rice.krad.uif.component.Component;
19 import org.kuali.rice.krad.uif.element.Header;
20 import org.kuali.rice.krad.uif.element.Message;
21 import org.kuali.rice.krad.uif.element.ValidationMessages;
22 import org.kuali.rice.krad.uif.layout.LayoutManager;
23 import org.kuali.rice.krad.uif.widget.Helpable;
24
25 import java.util.List;
26 import java.util.Set;
27
28 /**
29 * Type of component that contains a collection of other components. All
30 * templates for {@code Container} components must use a
31 * {@code LayoutManager} to render the contained components.
32 *
33 * Each container has the following parts in addition to the contained components:
34 * <ul>
35 * <li>{@code HeaderField}</li>
36 * <li>Summary {@code Message}</li>
37 * <li>Help component</li>
38 * <li>Errors container</li>
39 * <li>Footer {@code Group}</li>
40 * </ul>
41 * Container implementations are free to add additional content as needed.
42 *
43 * @author Kuali Rice Team (rice.collab@kuali.org)
44 *
45 * @see org.kuali.rice.krad.uif.component.Component
46 */
47 public interface Container extends Component, Helpable {
48
49 /**
50 * {@code List} of {@code Component} instances that are held by
51 * the container
52 *
53 * <p>
54 * Contained components are rendered within the section template by calling
55 * the associated {@code LayoutManager}.
56 * </p>
57 *
58 * @return List component instances
59 */
60 List<? extends Component> getItems();
61
62 /**
63 * Setter for the containers list of components
64 *
65 * @param items list of components to set in container
66 */
67 void setItems(List<? extends Component> items);
68
69 /**
70 * {@code Set} of {@code Component} classes that may be placed
71 * into the container
72 *
73 * <p>
74 * If an empty or null list is returned, it is assumed the container
75 * supports all components. The returned set will be used by dictionary
76 * validators and allows renders to make assumptions about the contained
77 * components
78 * </p>
79 *
80 * @return Set component classes
81 */
82 Set<Class<? extends Component>> getSupportedComponents();
83
84 /**
85 * {@code LayoutManager} that should be used to layout the components
86 * in the container
87 *
88 * <p>
89 * The template associated with the layout manager will be invoked passing
90 * in the List of components from the container. This list is exported under
91 * the attribute name 'items'
92 * </p>
93 *
94 * @return LayoutManager instance
95 */
96 LayoutManager getLayoutManager();
97
98 /**
99 * Setter for the containers layout manager
100 *
101 * @param layoutManager
102 */
103 void setLayoutManager(LayoutManager layoutManager);
104
105 /**
106 * {@code HeaderField} associated with the container
107 *
108 * <p>
109 * Header fields are generally rendered at the beginning of the container to
110 * indicate a grouping, although this is determined by the template
111 * associated with the container. The actual rendering configuration (style
112 * and so on) is configured within the HeaderField instance
113 * </p>
114 * <p>
115 * Header is only rendered if {@code Container#isRenderHeader} is true
116 * and getHeader() is not null
117 * </p>
118 *
119 * @return HeaderField instance or Null
120 */
121 Header getHeader();
122
123 /**
124 * Setter for the containers header field
125 *
126 * @param header
127 */
128 void setHeader(Header header);
129
130 /**
131 * Footer {@code Group} associated with the container
132 *
133 * <p>
134 * The footer is usually rendered at the end of the container. Often this is
135 * a place to put actions (buttons) for the container.
136 * </p>
137 * <p>
138 * Footer is only rendered if {@code Container#isRenderFooter} is true
139 * and getFooter is not null
140 * </p>
141 *
142 * @return Group footer instance or Null
143 */
144 Group getFooter();
145
146 /**
147 * Setter for the containers footer
148 *
149 * @param footer
150 */
151 void setFooter(Group footer);
152
153 /**
154 * Text for the container that provides a summary description or
155 * instructions
156 *
157 * <p>
158 * Text is encapsulated in a {@code Message} that contains
159 * rendering configuration.
160 * </p>
161 * <p>
162 * Summary {@code Message} only rendered if this methods does not
163 * return null
164 * </p>
165 *
166 * @return Message instance or Null
167 */
168 Message getInstructionalMessage();
169
170 /**
171 * Setter for the containers summary message field
172 *
173 * @param instructionalMessage
174 */
175 void setInstructionalMessage(Message instructionalMessage);
176
177 /**
178 * Field that contains the error messages for the container
179 *
180 * <p>
181 * Containers can collect the errors for the contained component and display
182 * either all the messages or counts. This {@code Field} is used to
183 * render those messages. Styling and other configuration is done through
184 * the {@code ValidationMessages}
185 * </p>
186 *
187 * @return ValidationMessages holding the container errors
188 */
189 ValidationMessages getValidationMessages();
190
191 /**
192 * Setter for the containers errors field
193 *
194 * @param validationMessages
195 */
196 void setValidationMessages(ValidationMessages validationMessages);
197
198 }