001/**
002 * Copyright 2005-2016 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 */
016package org.kuali.rice.krad.uif.service;
017
018import org.kuali.rice.krad.uif.container.CollectionGroup;
019import org.kuali.rice.krad.uif.view.View;
020import org.kuali.rice.krad.uif.component.Component;
021import org.kuali.rice.krad.uif.widget.Inquiry;
022import org.kuali.rice.krad.web.form.UifFormBase;
023
024import 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 */
036public 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        public 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
071         *            - View instance that should be initialized
072     * @param model - object instance containing the view data
073         */
074        public void performInitialization(View view, Object model);
075
076        /**
077         * Performs the Initialization phase for the given <code>Component</code>
078         * 
079         * <p>
080         * Can be called for component instances constructed via code or prototypes
081         * to initialize the constructed component
082         * </p>
083         * 
084         * @param view
085         *            - view instance the component belongs to
086     * @param model - object instance containing the view data
087         * @param component
088         *            - component instance that should be initialized
089         */
090        public void performComponentInitialization(View view, Object model, Component component);
091
092        /**
093         * Executes the ApplyModel phase. During this phase each component of the
094         * tree if invoked to setup any state based on the given model data
095         * 
096         * <p>
097         * Part of the view lifecycle that applies the model data to the view.
098         * Should be called after the model has been populated before the view is
099         * 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}