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.service;
017
018 import org.kuali.rice.krad.uif.container.CollectionGroup;
019 import org.kuali.rice.krad.uif.view.ExpressionEvaluator;
020 import org.kuali.rice.krad.uif.view.View;
021 import org.kuali.rice.krad.uif.component.Component;
022 import org.kuali.rice.krad.uif.widget.Inquiry;
023
024 import java.util.Map;
025
026 /**
027 * Provides methods for implementing the various phases of a <code>View</code>
028 *
029 * <ul>
030 * <li>Initialize Phase: Invoked when the view is first requested to setup
031 * necessary state</li>
032 * </ul>
033 *
034 * @author Kuali Rice Team (rice.collab@kuali.org)
035 */
036 public interface ViewHelperService {
037
038 /**
039 * Populates the <code>View</code> properties from the given request
040 * parameters
041 *
042 * <p>
043 * The <code>View</code> instance is inspected for fields that have the
044 * <code>RequestParameter</code> annotation and if corresponding parameters
045 * are found in the request parameter map, the request value is used to set
046 * the view property. The Map of parameter name/values that match are placed
047 * in the view so they can be later retrieved to rebuild the view. Custom
048 * <code>ViewServiceHelper</code> implementations can add additional
049 * parameter key/value pairs to the returned map if necessary.
050 * </p>
051 *
052 * @see org.kuali.rice.krad.uif.component.RequestParameter
053 */
054 void populateViewFromRequestParameters(View view, Map<String, String> parameters);
055
056 /**
057 * Performs the Initialization phase for the <code>View</code>. During this
058 * phase each component of the tree is invoked to setup state based on the
059 * configuration and request options.
060 *
061 * <p>
062 * The initialize phase is only called once per <code>View</code> lifecycle
063 * </p>
064 *
065 * <p>
066 * Note the <code>View</code> instance also contains the context Map that
067 * was created based on the parameters sent to the view service
068 * </p>
069 *
070 * @param view View instance that should be initialized
071 * @param model object instance containing the view data
072 */
073 void performInitialization(View view, Object model);
074
075 /**
076 * Performs the Initialization phase for the given <code>Component</code>
077 *
078 * <p>
079 * Can be called for component instances constructed via code or prototypes
080 * to initialize the constructed component
081 * </p>
082 *
083 * @param view view instance the component belongs to
084 * @param model object instance containing the view data
085 * @param component component instance that should be initialized
086 */
087 void performComponentInitialization(View view, Object model, Component component);
088
089 /**
090 * Executes the ApplyModel phase. During this phase each component of the
091 * tree if invoked to setup any state based on the given model data
092 *
093 * <p>
094 * Part of the view lifecycle that applies the model data to the view.
095 * Should be called after the model has been populated before the view is
096 * rendered. The main things that occur during this phase are:
097 * <ul>
098 * <li>Generation of dynamic fields (such as collection rows)</li>
099 * <li>Execution of conditional logic (hidden, read-only, required settings
100 * based on model values)</li>
101 * </ul>
102 * </p>
103 *
104 * <p>
105 * The update phase can be called multiple times for the view's lifecycle
106 * (typically only once per request)
107 * </p>
108 *
109 * @param view View instance that the model should be applied to
110 * @param model Top level object containing the data (could be the form or a
111 * top level business object, dto)
112 */
113 void performApplyModel(View view, Object model);
114
115 /**
116 * Gets global objects for the context map and pushes them to the context
117 * for the component
118 *
119 * @param view view instance for component
120 * @param component component instance to push context to
121 */
122 Map<String, Object> getCommonContext(View view, Component component);
123
124 /**
125 * The last phase before the view is rendered. Here final preparations can
126 * be made based on the updated view state
127 *
128 * <p>
129 * The finalize phase runs after the apply model phase and can be called
130 * multiple times for the view's lifecylce (however typically only once per
131 * request)
132 * </p>
133 *
134 * @param view view instance that should be finalized for rendering
135 * @param model top level object containing the data
136 */
137 void performFinalize(View view, Object model);
138
139 /**
140 * Invoked after the view has been rendered to clear out objects that are not necessary to keep around for
141 * the post, this helps reduce the view size and overall cost to store the form in session
142 *
143 * @param view view instance to be cleaned
144 */
145 void cleanViewAfterRender(View view);
146
147 /**
148 * Performs the complete component lifecycle on the component passed in for use during a refresh process
149 *
150 * <p>
151 * Runs the three lifecycle phases on the component passed in. Some adjustments are made to account for the
152 * component being processed without its parent. The component within the view (contained on the form) is
153 * retrieved to obtain the context to use (such as parent). The created components id is then updated to match
154 * the current id within the view.
155 * </p>
156 *
157 * @param view view instance the component belongs to
158 * @param model object containing the full view data
159 * @param component component instance to perform lifecycle for
160 * @param origId id of the component within the view, used to pull the current component from the view
161 */
162 void performComponentLifecycle(View view, Object model, Component component, String origId);
163
164 /**
165 * Update the reference objects listed in referencesToRefresh of the model
166 * <p>
167 * The the individual references in the referencesToRefresh string are separated by
168 * KRADConstants.REFERENCES_TO_REFRESH_SEPARATOR).
169 * </p>
170 *
171 * @param model top level object containing the data
172 * @param referencesToRefresh list of references to refresh (
173 */
174 void refreshReferences(Object model, String referencesToRefresh);
175
176 /**
177 * Invoked when the add line action is chosen for a collection. The
178 * collection path gives the full path to the collection that action was
179 * selected for. Here validation can be performed on the line as well as
180 * further processing on the line such as defaults. If the action is valid
181 * the line should be added to the collection, otherwise errors should be
182 * added to the global <code>MessageMap</code>
183 *
184 * @param view view instance that is being presented (the action was taken on)
185 * @param model Top level object containing the view data including the
186 * collection and new line
187 * @param collectionPath full path to the collection on the model
188 */
189 void processCollectionAddLine(View view, Object model, String collectionPath);
190
191 /**
192 * Adds a blank line to the collection
193 *
194 * <p>
195 * Adds a new collection item to the collection and applies any default values.
196 * </p>
197 *
198 * @param view view instance that is being presented (the action was taken on)
199 * @param model Top level object containing the view data including the collection and new line
200 * @param collectionPath full path to the collection on the model
201 */
202 void processCollectionAddBlankLine(View view, Object model, String collectionPath);
203
204 /**
205 * Invoked when the save line action is chosen for a collection. This method only does server side validation by
206 * default but creates hook for client applications to add additional logic like persisting data.
207 *
208 * @param view view instance that is being presented (the action was taken on)
209 * @param model Top level object containing the view data including the collection and new line
210 * @param collectionPath full path to the collection on the model
211 */
212 void processCollectionSaveLine(View view, Object model, String collectionPath, int selectedLineIndex);
213
214 /**
215 * Invoked when the delete line action is chosen for a collection. The
216 * collection path gives the full path to the collection that action was
217 * selected for. Here validation can be performed to make sure the action is
218 * allowed. If the action is valid the line should be deleted from the
219 * collection, otherwise errors should be added to the global
220 * <code>MessageMap</code>
221 *
222 * @param view view instance that is being presented (the action was taken on)
223 * @param model Top level object containing the view data including the collection
224 * @param collectionPath full path to the collection on the model
225 * @param lineIndex index of the collection line that was selected for removal
226 */
227 void processCollectionDeleteLine(View view, Object model, String collectionPath, int lineIndex);
228
229 /**
230 * Process the results returned from a multi-value lookup populating the lines for the collection given
231 * by the path
232 *
233 * @param view view instance the collection belongs to
234 * @param model object containing the view data
235 * @param collectionPath binding path to the collection to populated
236 * @param lookupResultValues String containing the selected line values
237 */
238 void processMultipleValueLookupResults(View view, Object model, String collectionPath, String lookupResultValues);
239
240 /**
241 * Invoked by the <code>Inquiry</code> widget to build the inquiry link
242 *
243 * <p>
244 * Note this is used primarily for custom <code>Inquirable</code>
245 * implementations to customize the inquiry class or parameters for an
246 * inquiry. Instead of building the full inquiry link, implementations can
247 * make a callback to
248 * org.kuali.rice.krad.uif.widget.Inquiry.buildInquiryLink(Object, String,
249 * Class<?>, Map<String, String>) given an inquiry class and parameters to
250 * build the link field.
251 * </p>
252 *
253 * @param dataObject parent object for the inquiry property
254 * @param propertyName name of the property the inquiry is being built for
255 * @param inquiry instance of the inquiry widget being built for the property
256 */
257 void buildInquiryLink(Object dataObject, String propertyName, Inquiry inquiry);
258
259 /**
260 * Applies configured default values for the line fields to the line
261 * instance
262 *
263 * @param view view instance the collection line belongs to
264 * @param model object containing the full view data
265 * @param collectionGroup collection group component the line belongs to
266 * @param line line instance to apply default values to
267 */
268 void applyDefaultValuesForCollectionLine(View view, Object model, CollectionGroup collectionGroup, Object line);
269
270 /**
271 * Return an instance of {@link org.kuali.rice.krad.uif.view.ExpressionEvaluator} that can be used for evaluating
272 * expressions
273 * contained on the view
274 *
275 * <p>
276 * A ExpressionEvaluator must be initialized with a model for expression evaluation. One instance is
277 * constructed for the view lifecycle and made available to all components/helpers through this method
278 * </p>
279 *
280 * @return instance of ExpressionEvaluator
281 */
282 public ExpressionEvaluator getExpressionEvaluator();
283
284 /**
285 * Generates table formatted data based on data collected from the table model
286 *
287 * @param view view instance where the table is located
288 * @param model top level object containing the data
289 * @param tableId id of the table being generated
290 * @param formatType format which the table should be generated in
291 * @return
292 */
293 String buildExportTableData(View view, Object model, String tableId, String formatType);
294
295 }