001/**
002 * Copyright 2005-2016 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.krad.uif.container;
017
018import org.kuali.rice.krad.uif.component.Component;
019import org.kuali.rice.krad.uif.field.ErrorsField;
020import org.kuali.rice.krad.uif.field.HeaderField;
021import org.kuali.rice.krad.uif.field.MessageField;
022import org.kuali.rice.krad.uif.layout.LayoutManager;
023import org.kuali.rice.krad.uif.widget.Help;
024
025import java.util.List;
026import java.util.Set;
027
028/**
029 * Type of component that contains a collection of other components. All
030 * templates for <code> Container</code> components must use a
031 * <code>LayoutManager</code> to render the contained components.
032 *
033 * Each container has the following parts in addition to the contained components:
034 * <ul>
035 * <li><code>HeaderField</code></li>
036 * <li>Summary <code>MessageField</code></li>
037 * <li>Help component</li>
038 * <li>Errors container</li>
039 * <li>Footer <code>Group</code></li>
040 * </ul>
041 * Container implementations are free to add additional content as needed.
042 * 
043 * @author Kuali Rice Team (rice.collab@kuali.org)
044 * 
045 * @see org.kuali.rice.krad.uif.component.Component
046 */
047public interface Container extends Component {
048
049        /**
050         * <code>List</code> of <code>Component</code> instances that are held by
051         * the container
052         * 
053         * <p>
054         * Contained components are rendered within the section template by calling
055         * the associated <code>LayoutManager</code>
056         * </p>
057         * 
058         * @return List component instances
059         */
060        public List<? extends Component> getItems();
061
062    /**
063     * Setter for the containers list of components
064     *
065     * @param items - list of components to set in container
066     */
067    public void setItems(List<? extends Component> items);
068
069        /**
070         * <code>Set</code> of <code>Component</code> classes that may be placed
071         * into the container
072         * 
073         * <p>
074         * If an empty or null list is returned, it is assumed the container
075         * supports all components. The returned set will be used by dictionary
076         * validators and allows renders to make assumptions about the contained
077         * components
078         * </p>
079         * 
080         * @return Set component classes
081         */
082        public Set<Class<? extends Component>> getSupportedComponents();
083
084        /**
085         * <code>LayoutManager</code> that should be used to layout the components
086         * in the container
087         * 
088         * <p>
089         * The template associated with the layout manager will be invoked passing
090         * in the List of components from the container. This list is exported under
091         * the attribute name 'items'
092         * </p>
093         * 
094         * @return LayoutManager instance
095         */
096        public LayoutManager getLayoutManager();
097
098        /**
099         * Setter for the containers layout manager
100         * 
101         * @param layoutManager
102         */
103        public void setLayoutManager(LayoutManager layoutManager);
104
105        /**
106         * <code>HeaderField</code> 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</code> is true
116         * and getHeader() is not null
117         * </p>
118         * 
119         * @return HeaderField instance or Null
120         */
121        public HeaderField getHeader();
122
123        /**
124         * Setter for the containers header field
125         * 
126         * @param header
127         */
128        public void setHeader(HeaderField header);
129
130        /**
131         * Footer <code>Group</code> 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</code> is true
139         * and getFooter is not null
140         * </p>
141         * 
142         * @return Group footer instance or Null
143         */
144        public Group getFooter();
145
146        /**
147         * Setter for the containers footer
148         * 
149         * @param footer
150         */
151        public 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>MessageField</code> that contains
159         * rendering configuration.
160         * </p>
161         * <p>
162         * Summary <code>MessageField</code> only rendered if this methods does not
163         * return null
164         * </p>
165         * 
166         * @return MessageField instance or Null
167         */
168        public MessageField getInstructionalMessageField();
169
170        /**
171         * Setter for the containers summary message field
172         * 
173         * @param summaryMessageField
174         */
175        public void setInstructionalMessageField(MessageField summaryMessageField);
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</code> is used to
183         * render those messages. Styling and other configuration is done through
184         * the <code>ErrorsField</code>
185         * </p>
186         * 
187         * @return ErrorsField holding the container errors
188         */
189        public ErrorsField getErrorsField();
190
191        /**
192         * Setter for the containers errors field
193         * 
194         * @param errorsField
195         */
196        public void setErrorsField(ErrorsField errorsField);
197
198        /**
199         * Help configuration object for the container
200         * 
201         * <p>
202         * External help information can be configured for the container. The
203         * <code>Help</code> object can the configuration for rendering a link to
204         * that help information.
205         * </p>
206         * 
207         * @return Help for container
208         */
209        public Help getHelp();
210
211        /**
212         * Setter for the containers help content
213         * 
214         * @param help
215         */
216        public void setHelp(Help help);
217
218        /**
219         * This property is true if the container is used to display a group of fields that is visually a single
220         * field - this has an effect on where errors will show up for these fields.
221         * @return the fieldContainer
222         */
223        public boolean isFieldContainer();
224
225        /**
226         * @param fieldContainer the fieldContainer to set
227         */
228        public void setFieldContainer(boolean fieldContainer);
229
230}