1 /**
2 * Copyright 2005-2014 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.datadictionary.uif.UifDictionaryBean;
19 import org.kuali.rice.krad.uif.container.Container;
20 import org.kuali.rice.krad.uif.view.View;
21 import org.kuali.rice.krad.uif.component.Component;
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 UifDictionaryBean, 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 * The name for which the template can be invoked by
85 *
86 * <p>
87 * Whether the template name is needed depends on the underlying rendering engine being used. In the example of
88 * Freemarker, the template points to the actual source file, which then loads a macro. From then on the macro is
89 * simply invoked to execute the template
90 * </p>
91 *
92 * <p>
93 * e.g. 'uif_grid'
94 * </p>
95 *
96 * @return
97 */
98 public String getTemplateName();
99
100 /**
101 * Setter for the name of the template (a name which can be used to invoke)
102 *
103 * @param templateName
104 */
105 public void setTemplateName(String templateName);
106
107 /**
108 * Should be called to initialize the layout manager
109 *
110 * <p>
111 * This is where layout managers can set defaults and setup other necessary
112 * state. The initialize method should only be called once per layout
113 * manager lifecycle and is invoked within the initialize phase of the view
114 * lifecylce.
115 * </p>
116 *
117 * @param view
118 * - View instance the layout manager is a part of
119 * @param model - the object instance containing the view data
120 * @param container
121 * - Container the layout manager applies to
122 * @see ViewHelperService#performInitialization
123 */
124 public void performInitialization(View view, Object model, Container container);
125
126 /**
127 * Called after the initialize phase to perform conditional logic based on
128 * the model data
129 *
130 * @param view
131 * - view instance to which the layout manager belongs
132 * @param model
133 * - Top level object containing the data (could be the form or a
134 * top level business object, dto)
135 * @param container
136 * - Container the layout manager applies to
137 */
138 public void performApplyModel(View view, Object model, Container container);
139
140 /**
141 * The last phase before the view is rendered. Here final preparations can
142 * be made based on the updated view state
143 *
144 *
145 * @param view
146 * - view instance that should be finalized for rendering
147 * @param model
148 * - top level object containing the data
149 * @param container
150 * - Container the layout manager applies to
151 */
152 public void performFinalize(View view, Object model, Container container);
153
154 /**
155 * Determines what <code>Container</code> classes are supported by the
156 * <code>LayoutManager</code>
157 *
158 * @return Class<? extends Container> container class supported
159 */
160 public Class<? extends Container> getSupportedContainer();
161
162 /**
163 * List of components that are contained within the layout manager that should be sent through the lifecycle
164 *
165 * <p>
166 * Used by <code>ViewHelperService</code> for the various lifecycle
167 * callbacks
168 * </p>
169 *
170 * @return List<Component> child components
171 */
172 public List<Component> getComponentsForLifecycle();
173
174 /**
175 * List of components that are maintained by the layout manager as prototypes for creating other component
176 * instances
177 *
178 * <p>
179 * Prototypes are held for configuring how a component should be created during the lifecycle. An example of this
180 * are the fields in a collection group that are created for each collection record. They only participate in the
181 * initialize phase.
182 * </p>
183 *
184 * @return List<Component> child component prototypes
185 */
186 public List<Component> getComponentPrototypes();
187
188 /**
189 * CSS style string to be applied to the area (div) the layout manager
190 * generates for the items
191 *
192 * <p>
193 * Note the styleClass/style configured on the <code>Container</code>
194 * applies to all the container content (header, body, footer), while the
195 * styleClass/style configured on the <code>LayoutManager</code> only
196 * applies to the div surrounding the items placed by the manager (the
197 * container's body)
198 * </p>
199 *
200 * <p>
201 * Any style override or additions can be specified with this attribute.
202 * This is used by the renderer to set the style attribute on the
203 * corresponding element.
204 * </p>
205 *
206 * <p>
207 * e.g. 'color: #000000;text-decoration: underline;'
208 * </p>
209 *
210 * @return String css style string
211 */
212 public String getStyle();
213
214 /**
215 * Setter for the layout manager div style
216 *
217 * @param style
218 */
219 public void setStyle(String style);
220
221 public List<String> getLibraryCssClasses();
222
223 public void setLibraryCssClasses(List<String> libraryClasses);
224
225 /**
226 * CSS style class(s) to be applied to the area (div) the layout manager
227 * generates for the items
228 *
229 * <p>
230 * Note the styleClass/style configured on the <code>Container</code>
231 * applies to all the container content (header, body, footer), while the
232 * styleClass/style configured on the <code>LayoutManager</code> only
233 * applies to the div surrounding the items placed by the manager (the
234 * container's body)
235 * </p>
236 *
237 * <p>
238 * Declares additional style classes for the div. Multiple classes are
239 * specified with a space delimiter. This is used by the renderer to set the
240 * class attribute on the corresponding element. The class(s) declared must
241 * be available in the common style sheets or the style sheets specified for
242 * the view
243 * </p>
244 *
245 * <p>
246 * e.g. 'header left'
247 * </p>
248 *
249 * @return List<String> css style classes to apply
250 */
251 public List<String> getCssClasses();
252
253 /**
254 * Setter for the layout manager div style class
255 *
256 * @param styleClasses
257 */
258 public void setCssClasses(List<String> styleClasses);
259
260 public List<String> getAdditionalCssClasses();
261
262 public void setAdditionalCssClasses(List<String> libraryClasses);
263
264 /**
265 * This method adds a single style class to the list of css style classes on this component
266 *
267 * @param styleClass
268 */
269 public void addStyleClass(String styleClass);
270
271 /**
272 * Context map for the layout manager
273 *
274 * @return Map<String, Object> context
275 * @see org.kuali.rice.krad.uif.component.Component#getContext()
276 */
277 public Map<String, Object> getContext();
278
279 /**
280 * Appends to the inline style set on this layoutManager
281 *
282 * @param styleRules
283 */
284 public void appendToStyle(String styleRules);
285
286 /**
287 * Setter for the context Map
288 *
289 * @param context
290 */
291 public void setContext(Map<String, Object> context);
292
293 /**
294 * Places the given object into the context Map for the layout manager
295 * with the given name
296 *
297 * @see org.kuali.rice.krad.uif.component.Component#pushObjectToContext(String,
298 * Object)
299 */
300 public void pushObjectToContext(String objectName, Object object);
301
302 /**
303 * Places all entries from a map into the context Map for the layout manager.
304 *
305 * @param sourceContext The map to push entries from.
306 * @see org.kuali.rice.krad.uif.component.Component#pushToContext(Map,
307 * Object)
308 */
309 public void pushAllToContext(Map<String, Object> sourceContext);
310
311 /**
312 * List of <code>PropertyReplacer</code> instances that will be
313 * evaluated during the view lifecycle to conditional set properties on the
314 * <code>LayoutManager</code> based on expression evaluations
315 *
316 * @return List<PropertyReplacer> replacers to evaluate
317 */
318 public List<PropertyReplacer> getPropertyReplacers();
319
320 /**
321 * Setter for the layout managers property substitutions
322 *
323 * @param propertyReplacers
324 */
325 public void setPropertyReplacers(List<PropertyReplacer> propertyReplacers);
326
327 /**
328 * Copy the object
329 *
330 * @return the copied object
331 */
332 public <T> T copy();
333
334 }