1 /**
2 * Copyright 2005-2011 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 * Performs the complete component lifecycle on the component passed in for use during a refresh process
140 *
141 * <p>
142 * Runs the three lifecycle phases on the component passed in. Some adjustments are made to account for the
143 * component being processed without its parent. The component within the view (contained on the form) is
144 * retrieved to obtain the context to use (such as parent). The created components id is then updated to match
145 * the current id within the view.
146 * </p>
147 *
148 * @param view - view instance the component belongs to
149 * @param model - object containing the full view data
150 * @param component - component instance to perform lifecycle for
151 * @param origId - id of the component within the view, used to pull the current component from the view
152 */
153 public void performComponentLifecycle(View view, Object model, Component component, String origId);
154
155 /**
156 * Invoked when the add line action is chosen for a collection. The
157 * collection path gives the full path to the collection that action was
158 * selected for. Here validation can be performed on the line as well as
159 * further processing on the line such as defaults. If the action is valid
160 * the line should be added to the collection, otherwise errors should be
161 * added to the global <code>MessageMap</code>
162 *
163 * @param view
164 * - view instance that is being presented (the action was taken
165 * on)
166 * @param model
167 * - Top level object containing the view data including the
168 * collection and new line
169 * @param collectionPath
170 * - full path to the collection on the model
171 */
172 public void processCollectionAddLine(View view, Object model, String collectionPath);
173
174 /**
175 * Invoked when the delete line action is chosen for a collection. The
176 * collection path gives the full path to the collection that action was
177 * selected for. Here validation can be performed to make sure the action is
178 * allowed. If the action is valid the line should be deleted from the
179 * collection, otherwise errors should be added to the global
180 * <code>MessageMap</code>
181 *
182 * @param view
183 * - view instance that is being presented (the action was taken
184 * on)
185 * @param model
186 * - Top level object containing the view data including the
187 * collection
188 * @param collectionPath
189 * - full path to the collection on the model
190 * @param lineIndex
191 * - index of the collection line that was selected for removal
192 */
193 public void processCollectionDeleteLine(View view, Object model, String collectionPath, int lineIndex);
194
195 /**
196 * Process the results returned from a multi-value lookup populating the lines for the collection given
197 * by the path
198 *
199 * @param view - view instance the collection belongs to
200 * @param model - object containing the view data
201 * @param collectionPath - binding path to the collection to populated
202 * @param lookupResultValues - String containing the selected line values
203 */
204 public void processMultipleValueLookupResults(View view, Object model, String collectionPath,
205 String lookupResultValues);
206
207 /**
208 * Invoked by the <code>Inquiry</code> widget to build the inquiry link
209 *
210 * <p>
211 * Note this is used primarily for custom <code>Inquirable</code>
212 * implementations to customize the inquiry class or parameters for an
213 * inquiry. Instead of building the full inquiry link, implementations can
214 * make a callback to
215 * org.kuali.rice.krad.uif.widget.Inquiry.buildInquiryLink(Object, String,
216 * Class<?>, Map<String, String>) given an inquiry class and parameters to
217 * build the link field.
218 * </p>
219 *
220 * @param dataObject
221 * - parent object for the inquiry property
222 * @param propertyName
223 * - name of the property the inquiry is being built for
224 * @param inquiry
225 * - instance of the inquiry widget being built for the property
226 */
227 public void buildInquiryLink(Object dataObject, String propertyName, Inquiry inquiry);
228
229 /**
230 * Applies configured default values for the line fields to the line
231 * instance
232 *
233 * @param view
234 * - view instance the collection line belongs to
235 * @param model
236 * - object containing the full view data
237 * @param collectionGroup
238 * - collection group component the line belongs to
239 * @param line
240 * - line instance to apply default values to
241 */
242 public void applyDefaultValuesForCollectionLine(View view, Object model, CollectionGroup collectionGroup,
243 Object line);
244
245 }