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.service;
17
18 import org.kuali.rice.krad.uif.container.CollectionGroup;
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.widget.Inquiry;
22 import org.kuali.rice.krad.web.form.UifFormBase;
23
24 import java.util.Map;
25
26 /**
27 * Provides methods for implementing the various phases of a <code>View</code>
28 *
29 * <ul>
30 * <li>Initialize Phase: Invoked when the view is first requested to setup
31 * necessary state</li>
32 * </ul>
33 *
34 * @author Kuali Rice Team (rice.collab@kuali.org)
35 */
36 public interface ViewHelperService {
37
38 /**
39 * Populates the <code>View</code> properties from the given request
40 * parameters
41 *
42 * <p>
43 * The <code>View</code> instance is inspected for fields that have the
44 * <code>RequestParameter</code> annotation and if corresponding parameters
45 * are found in the request parameter map, the request value is used to set
46 * the view property. The Map of parameter name/values that match are placed
47 * in the view so they can be later retrieved to rebuild the view. Custom
48 * <code>ViewServiceHelper</code> implementations can add additional
49 * parameter key/value pairs to the returned map if necessary.
50 * </p>
51 *
52 * @see org.kuali.rice.krad.uif.component.RequestParameter
53 */
54 public void populateViewFromRequestParameters(View view, Map<String, String> parameters);
55
56 /**
57 * Performs the Initialization phase for the <code>View</code>. During this
58 * phase each component of the tree is invoked to setup state based on the
59 * configuration and request options.
60 *
61 * <p>
62 * The initialize phase is only called once per <code>View</code> lifecycle
63 * </p>
64 *
65 * <p>
66 * Note the <code>View</code> instance also contains the context Map that
67 * was created based on the parameters sent to the view service
68 * </p>
69 *
70 * @param view
71 * - View instance that should be initialized
72 * @param model - object instance containing the view data
73 */
74 public void performInitialization(View view, Object model);
75
76 /**
77 * Performs the Initialization phase for the given <code>Component</code>
78 *
79 * <p>
80 * Can be called for component instances constructed via code or prototypes
81 * to initialize the constructed component
82 * </p>
83 *
84 * @param view
85 * - view instance the component belongs to
86 * @param model - object instance containing the view data
87 * @param component
88 * - component instance that should be initialized
89 */
90 public void performComponentInitialization(View view, Object model, Component component);
91
92 /**
93 * Executes the ApplyModel phase. During this phase each component of the
94 * tree if invoked to setup any state based on the given model data
95 *
96 * <p>
97 * Part of the view lifecycle that applies the model data to the view.
98 * Should be called after the model has been populated before the view is
99 * rendered. The main things that occur during this phase are:
100 * <ul>
101 * <li>Generation of dynamic fields (such as collection rows)</li>
102 * <li>Execution of conditional logic (hidden, read-only, required settings
103 * based on model values)</li>
104 * </ul>
105 * </p>
106 *
107 * <p>
108 * The update phase can be called multiple times for the view's lifecycle
109 * (typically only once per request)
110 * </p>
111 *
112 * @param view
113 * - View instance that the model should be applied to
114 * @param model
115 * - Top level object containing the data (could be the form or a
116 * top level business object, dto)
117 */
118 public void performApplyModel(View view, Object model);
119
120 /**
121 * The last phase before the view is rendered. Here final preparations can
122 * be made based on the updated view state
123 *
124 * <p>
125 * The finalize phase runs after the apply model phase and can be called
126 * multiple times for the view's lifecylce (however typically only once per
127 * request)
128 * </p>
129 *
130 *
131 * @param view
132 * - view instance that should be finalized for rendering
133 * @param model
134 * - top level object containing the data
135 */
136 public void performFinalize(View view, Object model);
137
138 /**
139 * Invoked after the view has been rendered to clear out objects that are not necessary to keep around for
140 * the post, this helps reduce the view size and overall cost to store the form in session
141 *
142 * @param view - view instance to be cleaned
143 */
144 public void cleanViewAfterRender(View view);
145
146 /**
147 * Performs the complete component lifecycle on the component passed in for use during a refresh process
148 *
149 * <p>
150 * Runs the three lifecycle phases on the component passed in. Some adjustments are made to account for the
151 * component being processed without its parent. The component within the view (contained on the form) is
152 * retrieved to obtain the context to use (such as parent). The created components id is then updated to match
153 * the current id within the view.
154 * </p>
155 *
156 * @param view - view instance the component belongs to
157 * @param model - object containing the full view data
158 * @param component - component instance to perform lifecycle for
159 * @param origId - id of the component within the view, used to pull the current component from the view
160 */
161 public void performComponentLifecycle(View view, Object model, Component component, String origId);
162
163 /**
164 * Invoked when the add line action is chosen for a collection. The
165 * collection path gives the full path to the collection that action was
166 * selected for. Here validation can be performed on the line as well as
167 * further processing on the line such as defaults. If the action is valid
168 * the line should be added to the collection, otherwise errors should be
169 * added to the global <code>MessageMap</code>
170 *
171 * @param view
172 * - view instance that is being presented (the action was taken
173 * on)
174 * @param model
175 * - Top level object containing the view data including the
176 * collection and new line
177 * @param collectionPath
178 * - full path to the collection on the model
179 */
180 public void processCollectionAddLine(View view, Object model, String collectionPath);
181
182 /**
183 * Invoked when the delete line action is chosen for a collection. The
184 * collection path gives the full path to the collection that action was
185 * selected for. Here validation can be performed to make sure the action is
186 * allowed. If the action is valid the line should be deleted from the
187 * collection, otherwise errors should be added to the global
188 * <code>MessageMap</code>
189 *
190 * @param view
191 * - view instance that is being presented (the action was taken
192 * on)
193 * @param model
194 * - Top level object containing the view data including the
195 * collection
196 * @param collectionPath
197 * - full path to the collection on the model
198 * @param lineIndex
199 * - index of the collection line that was selected for removal
200 */
201 public void processCollectionDeleteLine(View view, Object model, String collectionPath, int lineIndex);
202
203 /**
204 * Process the results returned from a multi-value lookup populating the lines for the collection given
205 * by the path
206 *
207 * @param view - view instance the collection belongs to
208 * @param model - object containing the view data
209 * @param collectionPath - binding path to the collection to populated
210 * @param lookupResultValues - String containing the selected line values
211 */
212 public void processMultipleValueLookupResults(View view, Object model, String collectionPath,
213 String lookupResultValues);
214
215 /**
216 * Invoked by the <code>Inquiry</code> widget to build the inquiry link
217 *
218 * <p>
219 * Note this is used primarily for custom <code>Inquirable</code>
220 * implementations to customize the inquiry class or parameters for an
221 * inquiry. Instead of building the full inquiry link, implementations can
222 * make a callback to
223 * org.kuali.rice.krad.uif.widget.Inquiry.buildInquiryLink(Object, String,
224 * Class<?>, Map<String, String>) given an inquiry class and parameters to
225 * build the link field.
226 * </p>
227 *
228 * @param dataObject
229 * - parent object for the inquiry property
230 * @param propertyName
231 * - name of the property the inquiry is being built for
232 * @param inquiry
233 * - instance of the inquiry widget being built for the property
234 */
235 public void buildInquiryLink(Object dataObject, String propertyName, Inquiry inquiry);
236
237 /**
238 * Applies configured default values for the line fields to the line
239 * instance
240 *
241 * @param view
242 * - view instance the collection line belongs to
243 * @param model
244 * - object containing the full view data
245 * @param collectionGroup
246 * - collection group component the line belongs to
247 * @param line
248 * - line instance to apply default values to
249 */
250 public void applyDefaultValuesForCollectionLine(View view, Object model, CollectionGroup collectionGroup,
251 Object line);
252
253 }