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.layout;
17
18 import org.kuali.rice.krad.uif.container.Container;
19 import org.kuali.rice.krad.uif.view.View;
20 import org.kuali.rice.krad.uif.component.Component;
21 import org.kuali.rice.krad.uif.component.Configurable;
22 import org.kuali.rice.krad.uif.component.PropertyReplacer;
23 import org.kuali.rice.krad.uif.service.ViewHelperService;
24
25 import java.io.Serializable;
26 import java.util.List;
27 import java.util.Map;
28 import java.util.Set;
29
30 /**
31 * Manages the rendering of <code>Component</code> instances within a
32 * <code>Container</code>
33 *
34 * @author Kuali Rice Team (rice.collab@kuali.org)
35 */
36 public interface LayoutManager extends Configurable, Serializable {
37
38 /**
39 * The unique id (within a given tree) for the layout manager instance
40 *
41 * <p>
42 * The id is used to identify a <code>LayoutManager</code> instance within
43 * the tree and can be used by renderers
44 * </p>
45 *
46 * @return String id
47 */
48 public String getId();
49
50 /**
51 * Sets the unique id (within a given tree) for the layout manager
52 *
53 * @param id
54 * - string to set as the layout manager id
55 */
56 public void setId(String id);
57
58 /**
59 * The path to the JSP file that should be called to invoke the layout
60 * manager
61 *
62 * <p>
63 * The path should be relative to the web root. All layout manager templates
64 * receive the list of items of be placed, the configured layout manager,
65 * and the container to which the layout manager applies
66 * </p>
67 *
68 * <p>
69 * e.g. '/krad/WEB-INF/jsp/tiles/boxLayout.jsp'
70 * </p>
71 *
72 * @return String representing the template path
73 */
74 public String getTemplate();
75
76 /**
77 * Setter for the layout managers template
78 *
79 * @param template
80 */
81 public void setTemplate(String template);
82
83 /**
84 * Should be called to initialize the layout manager
85 *
86 * <p>
87 * This is where layout managers can set defaults and setup other necessary
88 * state. The initialize method should only be called once per layout
89 * manager lifecycle and is invoked within the initialize phase of the view
90 * lifecylce.
91 * </p>
92 *
93 * @param view
94 * - View instance the layout manager is a part of
95 * @param model - the object instance containing the view data
96 * @param container
97 * - Container the layout manager applies to
98 * @see ViewHelperService#performInitialization
99 */
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 }