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 }