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.layout;
017
018import org.kuali.rice.krad.uif.container.Container;
019import org.kuali.rice.krad.uif.view.View;
020import org.kuali.rice.krad.uif.component.Component;
021import org.kuali.rice.krad.uif.component.Configurable;
022import org.kuali.rice.krad.uif.component.PropertyReplacer;
023import org.kuali.rice.krad.uif.service.ViewHelperService;
024
025import java.io.Serializable;
026import java.util.List;
027import java.util.Map;
028import java.util.Set;
029
030/**
031 * Manages the rendering of <code>Component</code> instances within a
032 * <code>Container</code>
033 * 
034 * @author Kuali Rice Team (rice.collab@kuali.org)
035 */
036public interface LayoutManager extends Configurable, Serializable {
037
038        /**
039         * The unique id (within a given tree) for the layout manager instance
040         * 
041         * <p>
042         * The id is used to identify a <code>LayoutManager</code> instance within
043         * the tree and can be used by renderers
044         * </p>
045         * 
046         * @return String id
047         */
048        public String getId();
049
050        /**
051         * Sets the unique id (within a given tree) for the layout manager
052         * 
053         * @param id
054         *            - string to set as the layout manager id
055         */
056        public void setId(String id);
057
058        /**
059         * The path to the JSP file that should be called to invoke the layout
060         * manager
061         * 
062         * <p>
063         * The path should be relative to the web root. All layout manager templates
064         * receive the list of items of be placed, the configured layout manager,
065         * and the container to which the layout manager applies
066         * </p>
067         * 
068         * <p>
069         * e.g. '/krad/WEB-INF/jsp/tiles/boxLayout.jsp'
070         * </p>
071         * 
072         * @return String representing the template path
073         */
074        public String getTemplate();
075
076        /**
077         * Setter for the layout managers template
078         * 
079         * @param template
080         */
081        public void setTemplate(String template);
082
083        /**
084         * Should be called to initialize the layout manager
085     *
086         * <p>
087         * This is where layout managers can set defaults and setup other necessary
088         * state. The initialize method should only be called once per layout
089         * manager lifecycle and is invoked within the initialize phase of the view
090         * lifecylce.
091         * </p>
092         * 
093         * @param view
094         *            - View instance the layout manager is a part of
095     * @param model - the object instance containing the view data
096         * @param container
097         *            - Container the layout manager applies to
098         * @see ViewHelperService#performInitialization
099         */
100        public void performInitialization(View view, Object model, Container container);
101
102        /**
103         * Called after the initialize phase to perform conditional logic based on
104         * the model data
105         * 
106         * @param view
107         *            - view instance to which the layout manager belongs
108         * @param model
109         *            - Top level object containing the data (could be the form or a
110         *            top level business object, dto)
111         * @param container
112         *            - Container the layout manager applies to
113         */
114        public void performApplyModel(View view, Object model, Container container);
115
116        /**
117         * The last phase before the view is rendered. Here final preparations can
118         * be made based on the updated view state
119         * 
120         * 
121         * @param view
122         *            - view instance that should be finalized for rendering
123         * @param model
124         *            - top level object containing the data
125         * @param container
126         *            - Container the layout manager applies to
127         */
128        public void performFinalize(View view, Object model, Container container);
129
130        /**
131         * Determines what <code>Container</code> classes are supported by the
132         * <code>LayoutManager</code>
133         * 
134         * @return Class<? extends Container> container class supported
135         */
136        public Class<? extends Container> getSupportedContainer();
137
138        /**
139         * List of components that are contained within the layout manager that should be sent through the lifecycle
140     *
141         * <p>
142         * Used by <code>ViewHelperService</code> for the various lifecycle
143         * callbacks
144     * </p>
145         * 
146         * @return List<Component> child components
147         */
148        public List<Component> getComponentsForLifecycle();
149
150    /**
151     * List of components that are maintained by the layout manager as prototypes for creating other component
152     * instances
153     *
154     * <p>
155     * Prototypes are held for configuring how a component should be created during the lifecycle. An example of this
156     * are the fields in a collection group that are created for each collection record. They only participate in the
157     * initialize phase.
158     * </p>
159     *
160     * @return List<Component> child component prototypes
161     */
162    public List<Component> getComponentPrototypes();
163
164        /**
165         * Used by the copy process to determine for which properties only the value
166         * reference should be copied (not a new copy instance). Subclasses can
167         * define the properties for which only the reference should be copied
168         * 
169         * @return Set<String> property names for which only the value reference
170         *         should be copied
171         * @see org.kuali.rice.krad.uif.util.ComponentUtils.copy(T)
172         */
173        public Set<String> getPropertiesForReferenceCopy();
174
175        /**
176         * CSS style string to be applied to the area (div) the layout manager
177         * generates for the items
178         * 
179         * <p>
180         * Note the styleClass/style configured on the <code>Container</code>
181         * applies to all the container content (header, body, footer), while the
182         * styleClass/style configured on the <code>LayoutManager</code> only
183         * applies to the div surrounding the items placed by the manager (the
184         * container's body)
185         * </p>
186         * 
187         * <p>
188         * Any style override or additions can be specified with this attribute.
189         * This is used by the renderer to set the style attribute on the
190         * corresponding element.
191         * </p>
192         * 
193         * <p>
194         * e.g. 'color: #000000;text-decoration: underline;'
195         * </p>
196         * 
197         * @return String css style string
198         */
199        public String getStyle();
200
201        /**
202         * Setter for the layout manager div style
203         * 
204         * @param style
205         */
206        public void setStyle(String style);
207
208        /**
209         * CSS style class(s) to be applied to the area (div) the layout manager
210         * generates for the items
211         * 
212         * <p>
213         * Note the styleClass/style configured on the <code>Container</code>
214         * applies to all the container content (header, body, footer), while the
215         * styleClass/style configured on the <code>LayoutManager</code> only
216         * applies to the div surrounding the items placed by the manager (the
217         * container's body)
218         * </p>
219         * 
220         * <p>
221         * Declares additional style classes for the div. Multiple classes are
222         * specified with a space delimiter. This is used by the renderer to set the
223         * class attribute on the corresponding element. The class(s) declared must
224         * be available in the common style sheets or the style sheets specified for
225         * the view
226         * </p>
227         * 
228         * <p>
229         * e.g. 'header left'
230         * </p>
231         * 
232         * @return List<String> css style classes to apply
233         */
234        public List<String> getStyleClasses();
235
236        /**
237         * Setter for the layout manager div style class
238         * 
239         * @param styleClass
240         */
241        public void setStyleClasses(List<String> styleClasses);
242
243        /**
244         * This method adds a single style class to the list of css style classes on this component
245         * 
246         * @param style
247         */
248        public void addStyleClass(String styleClass);
249
250        /**
251         * Context map for the layout manager
252         * 
253         * @return Map<String, Object> context
254         * @see org.kuali.rice.krad.uif.Component.getContext()
255         */
256        public Map<String, Object> getContext();
257
258        /**
259         * Setter for the context Map
260         * 
261         * @param context
262         * @see org.kuali.rice.krad.uif.Component.setElContext(Map<String, Object>)
263         */
264        public void setContext(Map<String, Object> context);
265
266        /**
267         * Places the given object into the context Map for the layout manager
268         * with the given name
269         * 
270         * @see org.kuali.rice.krad.uif.Component.pushObjectToContext(String,
271         *      Object)
272         */
273        public void pushObjectToContext(String objectName, Object object);
274        
275        /**
276         * List of <code>PropertyReplacer</code> instances that will be
277         * evaluated during the view lifecycle to conditional set properties on the
278         * <code>LayoutManager</code> based on expression evaluations
279         * 
280         * @return List<PropertyReplacer> replacers to evaluate
281         */
282        public List<PropertyReplacer> getPropertyReplacers();
283
284        /**
285         * Setter for the layout managers property substitutions
286         * 
287         * @param propertyReplacers
288         */
289        public void setPropertyReplacers(List<PropertyReplacer> propertyReplacers);
290
291}