1 /**
2 * Copyright 2005-2013 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 /**
222 * CSS style class(s) to be applied to the area (div) the layout manager
223 * generates for the items
224 *
225 * <p>
226 * Note the styleClass/style configured on the <code>Container</code>
227 * applies to all the container content (header, body, footer), while the
228 * styleClass/style configured on the <code>LayoutManager</code> only
229 * applies to the div surrounding the items placed by the manager (the
230 * container's body)
231 * </p>
232 *
233 * <p>
234 * Declares additional style classes for the div. Multiple classes are
235 * specified with a space delimiter. This is used by the renderer to set the
236 * class attribute on the corresponding element. The class(s) declared must
237 * be available in the common style sheets or the style sheets specified for
238 * the view
239 * </p>
240 *
241 * <p>
242 * e.g. 'header left'
243 * </p>
244 *
245 * @return List<String> css style classes to apply
246 */
247 public List<String> getCssClasses();
248
249 /**
250 * Setter for the layout manager div style class
251 *
252 * @param styleClasses
253 */
254 public void setCssClasses(List<String> styleClasses);
255
256 /**
257 * This method adds a single style class to the list of css style classes on this component
258 *
259 * @param styleClass
260 */
261 public void addStyleClass(String styleClass);
262
263 /**
264 * Context map for the layout manager
265 *
266 * @return Map<String, Object> context
267 * @see org.kuali.rice.krad.uif.component.Component#getContext()
268 */
269 public Map<String, Object> getContext();
270
271 /**
272 * Appends to the inline style set on this layoutManager
273 *
274 * @param styleRules
275 */
276 public void appendToStyle(String styleRules);
277
278 /**
279 * Setter for the context Map
280 *
281 * @param context
282 */
283 public void setContext(Map<String, Object> context);
284
285 /**
286 * Places the given object into the context Map for the layout manager
287 * with the given name
288 *
289 * @see org.kuali.rice.krad.uif.component.Component#pushObjectToContext(String,
290 * Object)
291 */
292 public void pushObjectToContext(String objectName, Object object);
293
294 /**
295 * List of <code>PropertyReplacer</code> instances that will be
296 * evaluated during the view lifecycle to conditional set properties on the
297 * <code>LayoutManager</code> based on expression evaluations
298 *
299 * @return List<PropertyReplacer> replacers to evaluate
300 */
301 public List<PropertyReplacer> getPropertyReplacers();
302
303 /**
304 * Setter for the layout managers property substitutions
305 *
306 * @param propertyReplacers
307 */
308 public void setPropertyReplacers(List<PropertyReplacer> propertyReplacers);
309
310 /**
311 * Copy the object
312 *
313 * @return the copied object
314 */
315 public <T extends LayoutManager> T copy();
316
317 }