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  
20  package org.apache.myfaces.custom.dialog;
21  
22  import javax.faces.component.UIPanel;
23  
24  import org.apache.myfaces.custom.dojo.DojoWidget;
25  
26  /**
27   * Embeds into the current page a javascript object with methods which can be called to
28   * display (and hide) a modal popup window. 
29   * <p>
30   * When the popup window is displayed, the current window contents become "greyed out" and
31   * the new window appears on top of the original. The original window does not respond to 
32   * keys or clicks; only the new window can be accessed by the user. When the popup window
33   * is closed then the original window is again accessable.
34   * </p>
35   * <p>
36   * When this component has a child facet named "titleBar" then the contents of that facet
37   * are rendered at the top of the popup window. This facet is intended to allow users to
38   * define their own custom window "decoration".
39   * </p>
40   * <p>
41   * When this component has no "titleBar" facet, but does have a "dialogTitle" property,
42   * then a default window decoration is generated. It consists of a table row with two
43   * cells. The left cell contains the dialogTitle text. If property renderCloseButton is
44   * true, then the right cell holds a "close" icon. Styles are defined for the row and
45   * cells so that the look-and-feel can be customised.
46   * </p>
47   * <p>
48   * The new window can optionally load a page from the server when it is displayed. If
49   * one of viewId or contentURL is defined, then an internal frame is inserted after the
50   * titleBar, and the specified contents is immediately loaded into the popup window when
51   * it is displayed.
52   * </p>
53   * <p>
54   * The rest of the child components (ie other than titleBar) are displayed after the
55   * titlebar (and after the contents of viewId or contentURL if it is defined).
56   * </p>
57   * <p>
58   * This component internally uses the Dojo modal window widget.
59   * </p>
60   * 
61   * @JSFComponent
62   *   name = "s:modalDialog"
63   *   class = "org.apache.myfaces.custom.dialog.ModalDialog"
64   *   tagClass = "org.apache.myfaces.custom.dialog.ModalDialogTag"
65   *   
66   */
67  public abstract class AbstractModalDialog extends UIPanel implements DojoWidget {
68  
69      public static final String COMPONENT_TYPE = "org.apache.myfaces.ModalDialog";
70  
71      public static final String DEFAULT_RENDERER_TYPE = "org.apache.myfaces.ModalDialog";
72      
73      /**
74       * A space separated list with attribute='value' pairs, which control the behaviour of the dojo dialog.
75       * 
76       * @JSFProperty
77       */
78      public abstract String getDialogAttr();
79  
80      /**
81       * An optional raw id to assign to the html div that encloses the modal dialog.
82       * <p>
83       * This id can be useful for controlling the dialog with javascript. However in most
84       * cases it is not necessary.
85       * </p>
86       * <p>
87       * If this is property is not defined then an id will be automatically generated.
88       * </p>
89       * 
90       * @JSFProperty
91       */
92      public abstract String getDialogId();
93  
94      /**
95       * Specifies the name of the javascript variable which provides access to the
96       * dialog functionality.
97       * <p>
98       * For example, if this is "myDialog" then a javascript object with name
99       * "myDialog" will be defined. This exposes the following methods:
100      * </p>
101      * <ul>
102      * <li>myDialog.show() will display the modal dialog window</li>
103      * <li>myDialog.hide() will hide it (though this is not normally needed).</li> 
104      * </ul>
105      * 
106      * @JSFProperty
107      */
108     public abstract String getDialogVar();
109     
110     public abstract void setDialogVar(String dialogVar);
111 
112     /**
113      * A list of ids of components which, when activated, should cause the popup
114      * dialog to be hidden.
115      * <p>
116      * If the standard title-bar is displayed (ie no custom titleBar facet exists,
117      * and property dialogTitle is defined) then the standard close-button in that
118      * bar is automatically included.
119      * </p>
120      * <p>
121      * If the child components of this component (which will appear in the popup)
122      * include other items that should cause the window to close (ie a button) then
123      * their ids should be defined via this property. This component will then
124      * automatically wire them up to the necessary functions to cause the popup
125      * to be closed when they are activated.
126      * </p>
127      * 
128      * @JSFProperty
129      */
130     public abstract String getHiderIds();
131 
132     /**
133      * The URL of the view to show within the content area of the dialog.
134      * <p>
135      * Optional; when not defined (or defined as an EL expression, but that expression returns null)
136      * then the popup dialog will be opened with no content. Presumably custom javascript in the
137      * calling page will arrange to populate the window content appropriately.
138      * </p>
139      * <p>
140      * The modalDialog component treats this as a <i>url</i> relative to the webapp base. The value
141      * should not start with a slash.
142      * </p>
143      * <p> 
144      * Note that technically this value is not a viewId. A viewId is the internal path to the
145      * page definition (eg "foo.jsp" or "foo.xhtml"). What the browser accesses is a URL (which
146      * contains the path that triggers the facelets servlet, eg "foo.faces" or "foo.jsf" or
147      * "/faces/foo".
148      * </p>
149      * The valueIt should not start with a slash.
150      * 
151      * @JSFProperty
152      */
153     public abstract String getViewId();
154 
155     /**
156      * The URL to show within the content area of the dialog.
157      * <p>
158      * This may be:
159      * </p>
160      * <ul>
161      * <li>an absolute url ("http://..")</li>
162      * <li>a url relative to the current webapp</li>
163      * <li>a url relative to the current page</li>
164      * </ul>
165      * 
166      * @JSFProperty
167      */
168     public abstract String getContentURL();
169 
170     //@Override
171     public boolean getRendersChildren() {
172         return true;
173     }
174 
175     /**
176      * HTML: CSS styling instructions.
177      * 
178      * @JSFProperty
179      */
180     public abstract String getStyle();
181 
182     /**
183      * The CSS class for this element. Corresponds to the HTML 'class' attribute.
184      * <p>
185      * This value is also used as a base for defining style classes for parts of the
186      * standard window "title bar" decoration.
187      * </p>
188      * 
189      * @JSFProperty
190      */
191     public abstract String getStyleClass();
192 
193     /**
194      * Optional enforced dojo widgetId
195      *  
196      * @JSFProperty
197      */
198     public abstract String getWidgetId();
199 
200     /**
201      * The title text to show in the title area of the popup window 
202      * (ie the "window decoration").
203      * <p>
204      * Ignored if there is a "titleBar" facet as a child.
205      * </p>
206      * 
207      * @JSFProperty
208      */
209     public abstract String getDialogTitle();
210 
211     /**
212      * Specifies whether there should be a "close" icon to the right of the
213      * popup window title.
214      * <p>
215      * Ignored if there is a "titleBar" facet as a child, or dialogTitle is
216      * not defined. 
217      * </p>
218      * <p>
219      * Defaults to true.
220      * </p>
221      * 
222      * @JSFProperty
223      */
224     public abstract Boolean getCloseButton();
225 
226     /**
227      * An alias for the "dialogVar" property.
228      *
229      * @deprecated use getDialogVar instead.
230      * 
231      * @JSFProperty
232      */
233     public String getWidgetVar() {
234         return getDialogVar();
235     }
236 
237     public void setWidgetVar(String widgetVar) {
238        setDialogVar(widgetVar);
239     }
240 }