View Javadoc

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  }