001 /**
002 * Copyright 2005-2013 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 */
016 package org.kuali.rice.krad.uif.layout;
017
018 import org.kuali.rice.krad.uif.container.Container;
019 import org.kuali.rice.krad.uif.view.View;
020 import org.kuali.rice.krad.uif.component.Component;
021 import org.kuali.rice.krad.uif.component.Configurable;
022 import org.kuali.rice.krad.uif.component.PropertyReplacer;
023 import org.kuali.rice.krad.uif.service.ViewHelperService;
024
025 import java.io.Serializable;
026 import java.util.List;
027 import java.util.Map;
028 import 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 */
036 public 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 }