1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.myfaces.trinidad.render;
20
21 import java.util.Map;
22
23 import javax.faces.component.UIComponent;
24 import javax.faces.component.UIViewRoot;
25 import javax.faces.context.FacesContext;
26
27 /**
28 * Interface to be implemented by RenderKits that support
29 * the launching of dialogs. The
30 * {@link org.apache.myfaces.trinidad.component.UIXCommand UIXCommand} components
31 * will not support launching dialogs unless the render kit provides an
32 * implementation of this API. Developers should always retrieve
33 * an instance using {@link org.apache.myfaces.trinidad.util.Service#getService},
34 * passing in the current RenderKit.
35 * </p>
36 * <pre>
37 * RenderKit rk = facesContext.getRenderKit();
38 * DialogService service = (DialogRenderKitService)
39 * Service.getService(rk, DialogRenderKitService.class);
40 * </pre>
41 *
42 */
43 public interface DialogRenderKitService
44 {
45 /**
46 * Launch a dialog, if possible given the current agent's capabilities.
47 * If the dialog cannot be launched, return false, indicating that
48 * the caller should fallback to launching a simple subprocess.
49 * The dialog may not be launched immediately; this method
50 * may result in simply queuing up behavior for the Render Response
51 * phase, when {@link ExtendedRenderKitService#encodeScripts} can output
52 * markup that will actually launch the dialog.
53 *
54 * @param context the current FacesContext
55 * @param source the source component
56 * @param targetRoot the UIViewRoot that should be displayed
57 * @param processParameters a set of parameters to populate the
58 * newly created pageFlowScope
59 * @param useWindow if true, try to show the dialog in a separate
60 * window. The meaning of this parameter can be interpreted
61 * by the RenderKit, and does not necessarily have to map
62 * to a full window.
63 * @param windowProperties a map of UI parameters used to
64 * modify the dialog. The list of property names that are
65 * supported will depend on the <code>RenderKit</code>, but
66 * common examples include "width" and "height".
67 * @return true if launching the dialog was handled by this service, false
68 * if it could not be, in which case ADF Faces will fall back on
69 * default dialog functionality.
70 */
71 public boolean launchDialog(
72 FacesContext context,
73 UIViewRoot targetRoot,
74 UIComponent source,
75 Map<String,Object> processParameters,
76 boolean useWindow,
77 Map<String,Object> windowProperties);
78
79 /**
80 * Called to return from a dialog.
81 * @param context the current FacesContext
82 * @param returnValue the value being returned from the dialog
83 */
84 public boolean returnFromDialog(
85 FacesContext context,
86 Object returnValue);
87
88 /**
89 * Returns true if the RenderKit is aware that a dialog has
90 * returned, and the given source component was responsible
91 * for launching that dialog.
92 *
93 * @param context the current FacesContext
94 * @param source the source component
95 */
96 public boolean isReturning(
97 FacesContext context,
98 UIComponent source);
99 }