1 /**
2 * Copyright 2005-2016 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.web.service;
17
18 import org.kuali.rice.krad.web.form.UifFormBase;
19 import org.springframework.web.servlet.ModelAndView;
20
21 import javax.servlet.http.HttpServletRequest;
22 import java.util.Map;
23 import java.util.Properties;
24
25 /**
26 * Service that provides helper methods for building {@link org.springframework.web.servlet.ModelAndView} instances
27 * and also other controller helper methods such as showing a dialog, a message view, or redirecting.
28 *
29 * @author Kuali Rice Team (rice.collab@kuali.org)
30 */
31 public interface ModelAndViewService {
32
33 /**
34 * Handles the check form action to validate the given form data.
35 *
36 * @param form instance containing the model data
37 * @return ModelAndView instance for rendering the view
38 */
39 ModelAndView checkForm(UifFormBase form);
40
41 /**
42 * Invoked by controller methods to show a dialog to the user.
43 *
44 * <p>This will return back to the view and display the dialog to the user. When the users chooses a response,
45 * the initial action that triggered the controller method (which called showDialog) will be triggered again. The
46 * response will be captured in the form property
47 * {@link org.kuali.rice.krad.web.form.UifFormBase#getDialogResponses()}. In the case of a confirmation, if 'false'
48 * (typically labeled cancel) is choosen the initial action will simply not be triggered again.</p>
49 *
50 * @param dialogId id for the dialog group to show
51 * @param confirmation whether the dialog should be shown as a confirmation, in this case it is expected the
52 * options are true (continue) or false (stop). In addition, if the user selects the false option, the dialog
53 * answer will not be resubmitted to the server, instead the user will remain on the view
54 * @param form instance containing the model data
55 * @return ModelAndView instance for rendering the view
56 */
57 ModelAndView showDialog(String dialogId, boolean confirmation, UifFormBase form);
58
59 /**
60 * Builds an URL from the given base URL and parameters, then builds a model and view instance
61 * configured to redirect to the built URL.
62 *
63 * @param form form instance containing the model data
64 * @param baseUrl base URL to redirect to
65 * @param urlParameters parameters to add to the base URL
66 * @return ModelAndView instance configured to redirect to the built URL
67 */
68 ModelAndView performRedirect(UifFormBase form, String baseUrl, Properties urlParameters);
69
70 /**
71 * Builds a model and view instance configured to redirect to the given URL.
72 *
73 * @param form instance containing the model data
74 * @param redirectUrl URL to redirect to
75 * @return ModelAndView instance configured to redirect to the given URL
76 */
77 ModelAndView performRedirect(UifFormBase form, String redirectUrl);
78
79 /**
80 * Builds a message view from the given header and message text then forwards the UIF model and view.
81 *
82 * <p>If an error or other type of interruption occurs during the request processing the controller can
83 * invoke this message to display the message to the user. This will abandon the view that was requested
84 * and display a view with just the message</p>
85 *
86 * @param form instance containing the model data
87 * @param headerText header text for the message view (can be blank)
88 * @param messageText text for the message to display
89 * @return instance for rendering the view
90 */
91 ModelAndView getMessageView(UifFormBase form, String headerText, String messageText);
92
93 /**
94 * Configures the Spring model and view instance containing the form data and pointing to the
95 * generic Uif view.
96 *
97 * <p>The view and page to render is assumed to be set in the given form object.</p>
98 *
99 * @param form form instance containing the model data
100 * @return ModelAndView instance for rendering the view
101 */
102 ModelAndView getModelAndView(UifFormBase form);
103
104 /**
105 * Configures the Spring model and view instance containing the form data and pointing to the
106 * generic Uif view, and also changes the current page to the given page id.
107 *
108 * <p>The view to render is assumed to be set in the given form object.</p>
109 *
110 * @param form form instance containing the model data
111 * @param pageId page id within the view to render
112 * @return ModelAndView instance for rendering the view
113 */
114 ModelAndView getModelAndView(UifFormBase form, String pageId);
115
116 /**
117 * Configures the Spring model and view instance containing the form data and pointing to the
118 * generic Uif view, and also adds the given attributes (which can be referenced in the view templates).
119 *
120 * <p>The view and page to render is assumed to be set in the given form object.</p>
121 *
122 * @param form form instance containing the model data
123 * @param additionalViewAttributes additional attributes to add to the returned model and view
124 * @return ModelAndView instance for rendering the view
125 */
126 ModelAndView getModelAndView(UifFormBase form, Map<String, Object> additionalViewAttributes);
127
128 /**
129 * Initialize a new view instance for the given view id, then configures the Spring model and view
130 * instance containing the form data and pointing to the generic Uif view.
131 *
132 * <p>This can be used by controllers to render a different view from the one initially requested (if any)</p>
133 *
134 * @param form form instance containing the model data
135 * @param viewId id for the view to initialize
136 * @return ModelAndView instance for rendering the view
137 */
138 ModelAndView getModelAndViewWithInit(UifFormBase form, String viewId);
139
140 /**
141 * Initialize a new view instance for the given view id, then configures the Spring model and view
142 * instance containing the form data and pointing to the generic Uif view.
143 *
144 * <p>This can be used by controllers to render a different view from the one initially requested (if any)</p>
145 *
146 * @param form form instance containing the model data
147 * @param viewId id for the view to initialize
148 * @param pageId page id within the view to render
149 * @return ModelAndView instance for rendering the view
150 */
151 ModelAndView getModelAndViewWithInit(UifFormBase form, String viewId, String pageId);
152
153 /**
154 * After the controller logic is executed, the form is placed into session and the corresponding view
155 * is prepared for rendering.
156 *
157 * @param request servlet request
158 * @param modelAndView model and view
159 */
160 void prepareView(HttpServletRequest request, ModelAndView modelAndView);
161 }