001/**
002 * Copyright 2005-2014 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.web.service;
017
018import org.kuali.rice.krad.web.form.UifFormBase;
019import org.springframework.web.servlet.ModelAndView;
020
021import javax.servlet.http.HttpServletRequest;
022import java.util.Map;
023import java.util.Properties;
024
025/**
026 * Service that provides helper methods for building {@link org.springframework.web.servlet.ModelAndView} instances
027 * and also other controller helper methods such as showing a dialog, a message view, or redirecting.
028 *
029 * @author Kuali Rice Team (rice.collab@kuali.org)
030 */
031public interface ModelAndViewService {
032
033    /**
034     * Handles the check form action to validate the given form data.
035     *
036     * @param form instance containing the model data
037     * @return ModelAndView instance for rendering the view
038     */
039    ModelAndView checkForm(UifFormBase form);
040
041    /**
042     * Invoked by controller methods to show a dialog to the user.
043     *
044     * <p>This will return back to the view and display the dialog to the user. When the users chooses a response,
045     * the initial action that triggered the controller method (which called showDialog) will be triggered again. The
046     * response will be captured in the form property
047     * {@link org.kuali.rice.krad.web.form.UifFormBase#getDialogResponses()}. In the case of a confirmation, if 'false'
048     * (typically labeled cancel) is choosen the initial action will simply not be triggered again.</p>
049     *
050     * @param dialogId id for the dialog group to show
051     * @param confirmation whether the dialog should be shown as a confirmation, in this case it is expected the
052     * options are true (continue) or false (stop). In addition, if the user selects the false option, the dialog
053     * answer will not be resubmitted to the server, instead the user will remain on the view
054     * @param form instance containing the model data
055     * @return ModelAndView instance for rendering the view
056     */
057    ModelAndView showDialog(String dialogId, boolean confirmation, UifFormBase form);
058
059    /**
060     * Builds an URL from the given base URL and parameters, then builds a model and view instance
061     * configured to redirect to the built URL.
062     *
063     * @param form form instance containing the model data
064     * @param baseUrl base URL to redirect to
065     * @param urlParameters parameters to add to the base URL
066     * @return ModelAndView instance configured to redirect to the built URL
067     */
068    ModelAndView performRedirect(UifFormBase form, String baseUrl, Properties urlParameters);
069
070    /**
071     * Builds a model and view instance configured to redirect to the given URL.
072     *
073     * @param form instance containing the model data
074     * @param redirectUrl URL to redirect to
075     * @return ModelAndView instance configured to redirect to the given URL
076     */
077    ModelAndView performRedirect(UifFormBase form, String redirectUrl);
078
079    /**
080     * Builds a message view from the given header and message text then forwards the UIF model and view.
081     *
082     * <p>If an error or other type of interruption occurs during the request processing the controller can
083     * invoke this message to display the message to the user. This will abandon the view that was requested
084     * and display a view with just the message</p>
085     *
086     * @param form instance containing the model data
087     * @param headerText header text for the message view (can be blank)
088     * @param messageText text for the message to display
089     * @return instance for rendering the view
090     */
091    ModelAndView getMessageView(UifFormBase form, String headerText, String messageText);
092
093    /**
094     * Configures the Spring model and view instance containing the form data and pointing to the
095     * generic Uif view.
096     *
097     * <p>The view and page to render is assumed to be set in the given form object.</p>
098     *
099     * @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}