Window.openDialog

  • Revision slug: DOM/window.openDialog
  • Revision title: window.openDialog
  • Revision id: 114265
  • Created:
  • Creator: Sonnyp
  • Is current revision? No
  • Comment 8 words added

Revision Content

{{ DomRef() }}

Summary

window.openDialog is an extension to window.open. It behaves the same, except that it can optionally take one or more parameters past windowFeatures, and windowFeatures itself is treated a little differently.

The optional parameters, if present, will be bundled up in a JavaScript Array object and added to the newly created window as a property named window.arguments. They may be referenced in the JavaScript of the window at any time, including during the execution of a load handler. These parameters may be used, then, to pass arguments to and from the dialog window.

Note that the call to openDialog() returns immediately. If you want the call to block until the user has closed the dialog, supply modal as a windowFeatures parameter. Note that this also means the user won't be able to interact with the opener window until he closes the modal dialog.

Syntax

newWindow = openDialog(url, name, features, arg1, arg2, ...) 
newWindow 
The opened window
url 
The URL to be loaded in the newly opened window.
name 
The window name (optional). See window.open description for detailed information.
features 
See window.open description for description.
arg1, arg2, ... 
The arguments to be passed to the new window (optional).

Example

var win = openDialog("http://example.tld/zzz.xul", "dlg", "", "pizza", 6.98);

Notes

New Features

all - Initially activates (or deactivates ("all=no")) all chrome (except the behaviour flags chrome, dialog and modal). These can be overridden (so "menubar=no,all" turns on all chrome except the menubar.) This feature is explicitly ignored by window.open. window.openDialog finds it useful because of its different default assumptions.

Default behaviour

The chrome and dialog features are always assumed on, unless explicitly turned off ("chrome=no"). openDialog treats the absence of the features parameter as does window.open, (that is, an empty string sets all features to off) except chrome and dialog, which default to on. If the features parameter is a zero-length string, or contains only one or more of the behaviour features (chrome, dependent, dialog and modal) the chrome features are assumed "OS' choice." That is, window creation code is not given specific instructions, but is instead allowed to select the chrome that best fits a dialog on that operating system.

Passing extra parameters to the dialog

To pass extra parameters into the dialog, you can simply supply them after the windowFeatures parameter:

openDialog("http://example.tld/zzz.xul", "dlg", "", "pizza", 6.98);

The extra parameters will then get packed into a property named arguments of type Array, and this property gets added to the newly opened dialog window.

To access these extra parameters from within dialog code, use the following scheme:

var food  = window.arguments[0];
var price = window.arguments[1];

Note that you can access this property from within anywhere in the dialog code. (Another example).

Returning values from the dialog

Since window.close() erases all properties associated with the dialog window (i.e. the variables specified in the JavaScript code which gets loaded from the dialog), it is not possible to pass return values back past the close operation using globals (or any other constructs).

To be able to pass values back to the caller, you have to supply some object via the extra parameters. You can then access this object from within the dialog code and set properties on it, containing the values you want to return or preserve past the window.close() operation.

var retVals = { address: null, delivery: null };
openDialog("http://example.tld/zzz.xul", "dlg", "modal", "pizza", 6.98, retVals);

If you set the properties of the retVals object in the dialog code as described below, you can now access them via the retVals array after the openDialog() call returns.

Inside the dialog code, you can set the properties as follows:

var retVals = window.arguments[2];
retVals.address  = enteredAddress;
retVals.delivery = "immediate";

See also . (Another example).
see also window.importDialog (mobile).

Specification

{{ DOM0() }}

{{ languages( { "pl": "pl/DOM/window.openDialog" } ) }}

Revision Source

<p>{{ DomRef() }}</p>
<h3 name="Summary">Summary</h3>
<p><code>window.openDialog</code> is an extension to <a href="/en/DOM/window.open" title="en/DOM/window.open">window.open</a>. It behaves the same, except that it can optionally take one or more parameters past <code>windowFeatures</code>, and <code>windowFeatures</code> itself is treated a little differently.</p>
<p>The optional parameters, if present, will be bundled up in a JavaScript Array object and added to the newly created window as a property named <a href="/en/DOM/window.arguments" title="en/DOM/window.arguments">window.arguments</a>. They may be referenced in the JavaScript of the window at any time, including during the execution of a <code>load</code> handler. These parameters may be used, then, to pass arguments to and from the dialog window.</p>
<p>Note that the call to <code>openDialog()</code> returns immediately. If you want the call to block until the user has closed the dialog, supply <code>modal</code> as a <code>windowFeatures</code> parameter. Note that this also means the user won't be able to interact with the opener window until he closes the modal dialog.</p>
<h3 name="Syntax">Syntax</h3>
<pre class="eval"><em>newWindow</em> = openDialog(<em>url</em>, <em>name</em>, <em>features</em>, <em>arg1</em>, <em>arg2</em>, ...) 
</pre>
<dl> <dt>newWindow </dt> <dd>The opened window</dd> <dt>url </dt> <dd>The URL to be loaded in the newly opened window.</dd> <dt>name </dt> <dd>The window name (optional). See <a href="/en/DOM/window.open" title="en/DOM/window.open">window.open</a> description for detailed information.</dd> <dt>features </dt> <dd>See <a href="/en/DOM/window.open" title="en/DOM/window.open">window.open</a> description for description.</dd> <dt>arg1, arg2, ... </dt> <dd>The arguments to be passed to the new window (optional).</dd>
</dl>
<h3 name="Example">Example</h3>
<pre class="eval">var win = openDialog("<span class="nowiki">http://example.tld/zzz.xul</span>", "dlg", "", "pizza", 6.98);
</pre>
<h3 name="Notes">Notes</h3>
<h4 name="New_Features">New Features</h4>
<p><code>all</code> - Initially activates (or deactivates <code>("all=no")</code>) all chrome (except the behaviour flags <code>chrome</code>, <code>dialog</code> and <code>modal</code>). These can be overridden (so <code>"menubar=no,all"</code> turns on all chrome except the menubar.) This feature is explicitly ignored by <a href="/en/DOM/window.open" title="en/DOM/window.open">window.open</a>. <code>window.openDialog</code> finds it useful because of its different default assumptions.</p>
<h4 name="Default_behaviour">Default behaviour</h4>
<p>The <code>chrome</code> and <code>dialog</code> features are always assumed on, unless explicitly turned off ("<code>chrome=no</code>"). <code>openDialog</code> treats the absence of the features parameter as does <a href="/en/DOM/window.open" title="en/DOM/window.open">window.open</a>, (that is, an empty string sets all features to off) except <code>chrome</code> and <code>dialog</code>, which default to on. If the <code>features</code> parameter is a zero-length string, or contains only one or more of the behaviour features (<code>chrome</code>, <code>dependent</code>, <code>dialog</code> and <code>modal</code>) the chrome features are assumed "OS' choice." That is, window creation code is not given specific instructions, but is instead allowed to select the chrome that best fits a dialog on that operating system.</p>
<h4 name="Passing_extra_parameters_to_the_dialog">Passing extra parameters to the dialog</h4>
<p>To pass extra parameters into the dialog, you can simply supply them after the <code>windowFeatures</code> parameter:</p>
<pre class="eval">openDialog("<span class="nowiki">http://example.tld/zzz.xul</span>", "dlg", "", "pizza", 6.98);
</pre>
<p>The extra parameters will then get packed into a property named <code>arguments</code> of type <a href="/en/Core_JavaScript_1.5_Reference/Global_Objects/Array" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a>, and this property gets added to the newly opened dialog window.</p>
<p>To access these extra parameters from within dialog code, use the following scheme:</p>
<pre class="eval">var food  = window.arguments[0];
var price = window.arguments[1];
</pre>
<p>Note that you can access this property from within anywhere in the dialog code. (<a href="/en/Code_snippets/Dialogs_and_Prompts#Passing_arguments_and_displaying_a_dialog" title="en/Code_snippets/Dialogs_and_Prompts#Passing_arguments_and_displaying_a_dialog">Another example</a>).</p>
<h4 name="Returning_values_from_the_dialog">Returning values from the dialog</h4>
<p>Since <code>window.close()</code> erases all properties associated with the dialog window (i.e. the variables specified in the JavaScript code which gets loaded from the dialog), it is not possible to pass return values back past the close operation using globals (or any other constructs).</p>
<p>To be able to pass values back to the caller, you have to supply some object via the extra parameters. You can then access this object from within the dialog code and set properties on it, containing the values you want to return or preserve past the <code>window.close()</code> operation.</p>
<pre class="eval">var retVals = { address: null, delivery: null };
openDialog("<span class="nowiki">http://example.tld/zzz.xul</span>", "dlg", "modal", "pizza", 6.98, retVals);
</pre>
<p>If you set the properties of the <code>retVals</code> object in the dialog code as described below, you can now access them via the <code>retVals</code> array after the <code>openDialog()</code> call returns.</p>
<p>Inside the dialog code, you can set the properties as follows:</p>
<pre class="eval">var retVals = window.arguments[2];
retVals.address  = enteredAddress;
retVals.delivery = "immediate";
</pre>
<p>See also <a class="external" href="http://groups.google.com/group/netscape.public.dev.xul/msg/02075a1736406b40"></a>. (<a href="/en/Code_snippets/Dialogs_and_Prompts#Passing_arguments_and_displaying_a_dialog" title="en/Code_snippets/Dialogs_and_Prompts#Passing_arguments_and_displaying_a_dialog">Another example</a>).<br>
see also window.importDialog (mobile).</p>
<h3 name="Specification">Specification</h3>
<p>{{ DOM0() }}</p>
<p>{{ languages( { "pl": "pl/DOM/window.openDialog" } ) }}</p>
Revert to this revision