001/**
002 * Copyright 2005-2018 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.element.Header;
020import org.kuali.rice.krad.uif.element.Message;
021import org.kuali.rice.krad.uif.element.ValidationMessages;
022import org.kuali.rice.krad.uif.layout.LayoutManager;
023import org.kuali.rice.krad.uif.widget.Helpable;
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} components must use a
031 * {@code LayoutManager} 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}</li>
036 * <li>Summary {@code Message}</li>
037 * <li>Help component</li>
038 * <li>Errors container</li>
039 * <li>Footer {@code Group}</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 * @see org.kuali.rice.krad.uif.component.Component
045 */
046public interface Container extends Component, Helpable {
047
048    /**
049     * {@code List} of {@code Component} instances that are held by
050     * the container
051     *
052     * <p>
053     * Contained components are rendered within the section template by calling
054     * the associated {@code LayoutManager}.
055     * </p>
056     *
057     * @return List component instances
058     */
059    List<? extends Component> getItems();
060
061    /**
062     * Setter for the containers list of components
063     *
064     * @param items list of components to set in container
065     */
066    void setItems(List<? extends Component> items);
067
068    /**
069     * {@code Set} of {@code Component} classes that may be placed
070     * into the container
071     *
072     * <p>
073     * If an empty or null list is returned, it is assumed the container
074     * supports all components. The returned set will be used by dictionary
075     * validators and allows renders to make assumptions about the contained
076     * components
077     * </p>
078     *
079     * @return Set component classes
080     */
081    Set<Class<? extends Component>> getSupportedComponents();
082
083    /**
084     * {@code LayoutManager} that should be used to layout the components
085     * in the container
086     *
087     * <p>
088     * The template associated with the layout manager will be invoked passing
089     * in the List of components from the container. This list is exported under
090     * the attribute name 'items'
091     * </p>
092     *
093     * @return LayoutManager instance
094     */
095    LayoutManager getLayoutManager();
096
097    /**
098     * @see #getLayoutManager()
099     */
100    void setLayoutManager(LayoutManager layoutManager);
101
102    /**
103     * {@code HeaderField} associated with the container
104     *
105     * <p>
106     * Header fields are generally rendered at the beginning of the container to
107     * indicate a grouping, although this is determined by the template
108     * associated with the container. The actual rendering configuration (style
109     * and so on) is configured within the HeaderField instance
110     * </p>
111     * <p>
112     * Header is only rendered if {@code Container#isRenderHeader} is true
113     * and getHeader() is not null
114     * </p>
115     *
116     * @return HeaderField instance or Null
117     */
118    Header getHeader();
119
120    /**
121     * @see #getHeader()
122     */
123    void setHeader(Header header);
124
125    /**
126     * Footer {@code Group} associated with the container
127     *
128     * <p>
129     * The footer is usually rendered at the end of the container. Often this is
130     * a place to put actions (buttons) for the container.
131     * </p>
132     * <p>
133     * Footer is only rendered if {@code Container#isRenderFooter} is true
134     * and getFooter is not null
135     * </p>
136     *
137     * @return Group footer instance or Null
138     */
139    Group getFooter();
140
141    /**
142     * @see #getFooter()
143     */
144    void setFooter(Group footer);
145
146    /**
147     * Text for the container that provides a summary description or
148     * instructions
149     *
150     * <p>
151     * Text is encapsulated in a {@code Message} that contains
152     * rendering configuration.
153     * </p>
154     * <p>
155     * Summary {@code Message} only rendered if this methods does not
156     * return null
157     * </p>
158     *
159     * @return Message instance or Null
160     */
161    Message getInstructionalMessage();
162
163    /**
164     * @see #getInstructionalMessage()
165     */
166    void setInstructionalMessage(Message instructionalMessage);
167
168    /**
169     * Field that contains the error messages for the container
170     *
171     * <p>
172     * Containers can collect the errors for the contained component and display
173     * either all the messages or counts. This {@code Field} is used to
174     * render those messages. Styling and other configuration is done through
175     * the {@code ValidationMessages}
176     * </p>
177     *
178     * @return ValidationMessages holding the container errors
179     */
180    ValidationMessages getValidationMessages();
181
182    /**
183     * @see #getValidationMessages()
184     */
185    void setValidationMessages(ValidationMessages validationMessages);
186
187    /**
188     * Performs sorting of the container items based on the order property.
189     *
190     * <p>
191     * Note that the items may be modified by this method to assign order priority where it has not
192     * been previously assigned.
193     * </p>
194     */
195    void sortItems();
196
197    /**
198     * Determine if remote field holders should be processed for this container.
199     *
200     * @return True if remote field holders should be processed for this container.
201     */
202    boolean isProcessRemoteFieldHolders();
203
204    /**
205     * Get the key of the action item to invoke upon pressing the enter key.
206     *
207     * @return String enterKeyAction
208     */
209    public String getEnterKeyAction();
210
211    /**
212     * @see #getEnterKeyAction()
213     */
214    public void setEnterKeyAction(String enterKeyAction);
215
216}