6.4 User prompts

6.4.1 Simple dialogs

window . alert(message)

Displays a modal alert with the given message, and waits for the user to dismiss it.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

result = window . confirm(message)

Displays a modal OK/Cancel prompt with the given message, waits for the user to dismiss it, and returns true if the user clicks OK and false if the user clicks Cancel.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

result = window . prompt(message [, default] )

Displays a modal text field prompt with the given message, waits for the user to dismiss it, and returns the value that the user entered. If the user cancels the prompt, then returns null instead. If the second argument is present, then the given value is used as a default.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

The alert(message) method, when invoked, must run the following steps:

  1. If the event loop's termination nesting level is non-zero, optionally abort these steps.

  2. Release the storage mutex.

  3. Optionally, abort these steps. (For example, the user agent might give the user the option to ignore all alerts, and would thus abort at this step whenever the method was invoked.)

  4. Show the given message to the user.

  5. Optionally, pause while waiting for for the user to acknowledge the message.

The confirm(message) method, when invoked, must run the following steps:

  1. If the event loop's termination nesting level is non-zero, optionally abort these steps, returning false.

  2. Release the storage mutex.

  3. Optionally, return false and abort these steps. (For example, the user agent might give the user the option to ignore all prompts, and would thus abort at this step whenever the method was invoked.)

  4. Show the given message to the user, and ask the user to respond with a positive or negative response.

  5. Pause until the user responds either positively or negatively.

  6. If the user responded positively, return true; otherwise, the user responded negatively: return false.

The prompt(message, default) method, when invoked, must run the following steps:

  1. If the event loop's termination nesting level is non-zero, optionally abort these steps, returning null.

  2. Release the storage mutex.

  3. Optionally, return null and abort these steps. (For example, the user agent might give the user the option to ignore all prompts, and would thus abort at this step whenever the method was invoked.)

  4. Show the given message to the user, and ask the user to either respond with a string value or abort. The second argument is optional. If the second argument (default) is present, then the response must be defaulted to the value given by default.

  5. Pause while waiting for the user's response.

  6. If the user aborts, then return null; otherwise, return the string that the user responded with.

6.4.2 Printing

window . print()

Prompts the user to print the page.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

When the print() method is invoked, if the Document is ready for post-load tasks, then the user agent must synchronously run the printing steps. Otherwise, the user agent must only set the print when loaded flag on the Document.

User agents should also run the printing steps whenever the user asks for the opportunity to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.

The printing steps are as follows:

  1. The user agent may display a message to the user and/or may abort these steps.

    For instance, a kiosk browser could silently ignore any invocations of the print() method.

    For instance, a browser on a mobile device could detect that there are no printers in the vicinity and display a message saying so before continuing to offer a "save to PDF" option.

  2. The user agent must fire a simple event named beforeprint at the Window object of the Document that is being printed, as well as any nested browsing contexts in it.

    The beforeprint event can be used to annotate the printed copy, for instance adding the time at which the document was printed.

  3. The user agent must release the storage mutex.

  4. The user agent should offer the user the opportunity to obtain a physical form (or the representation of a physical form) of the document. The user agent may wait for the user to either accept or decline before returning; if so, the user agent must pause while the method is waiting. Even if the user agent doesn't wait at this point, the user agent must use the state of the relevant documents as they are at this point in the algorithm if and when it eventually creates the alternate form.

  5. The user agent must fire a simple event named afterprint at the Window object of the Document that is being printed, as well as any nested browsing contexts in it.

    The afterprint event can be used to revert annotations added in the earlier event, as well as showing post-printing UI. For instance, if a page is walking the user through the steps of applying for a home loan, the script could automatically advance to the next step after having printed a form or other.

6.4.3 Dialogs implemented using separate documents

result = window . showModalDialog(url [, argument] )

Prompts the user with the given page, waits for that page to close, and returns the return value.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

The showModalDialog(url, argument) method, when invoked, must cause the user agent to run the following steps:

  1. Resolve url relative to the entry script's base URL.

    If this fails, then throw a SyntaxError exception and abort these steps.

  2. If the event loop's termination nesting level is non-zero, optionally abort these steps, returning the empty string.

  3. Release the storage mutex.

  4. If the user agent is configured such that this invocation of showModalDialog() is somehow disabled, then return the empty string and abort these steps.

    User agents are expected to disable this method in certain cases to avoid user annoyance (e.g. as part of their popup blocker feature). For instance, a user agent could require that a site be white-listed before enabling this method, or the user agent could be configured to only allow one modal dialog at a time.

  5. If the active sandboxing flag set of the active document of the browsing context of the script that invoked the method has its sandboxed auxiliary navigation browsing context flag set, then return the empty string and abort these steps.

  6. Let the list of background browsing contexts be a list of all the browsing contexts that:

    ...as well as any browsing contexts that are nested inside any of the browsing contexts matching those conditions.

  7. Disable the user interface for all the browsing contexts in the list of background browsing contexts. This should prevent the user from navigating those browsing contexts, causing events to be sent to those browsing context, or editing any content in those browsing contexts. However, it does not prevent those browsing contexts from receiving events from sources other than the user, from running scripts, from running animations, and so forth.

  8. Create a new auxiliary browsing context, with the opener browsing context being the browsing context of the Window object on which the showModalDialog() method was called. The new auxiliary browsing context has no name.

    This browsing context's Documents' Window objects all implement the WindowModal interface.

  9. Set all the flags in the new browsing context's popup sandboxing flag set that are set in the active sandboxing flag set of the active document of the browsing context of the script that invoked the method. The browsing context of the script that invoked the method must be set as the new browsing context's one permitted sandboxed navigator.

  10. Let the dialog arguments of the new browsing context be set to the value of argument, or the 'undefined' value if the argument was omitted.

  11. Let the dialog arguments' origin be the origin of the script that called the showModalDialog() method.

  12. Navigate the new browsing context to the absolute URL that resulted from resolving url earlier, with replacement enabled, and with the browsing context of the script that invoked the method as the source browsing context.

  13. Spin the event loop until the new browsing context is closed. (The user agent must allow the user to indicate that the browsing context is to be closed.)

  14. Reenable the user interface for all the browsing contexts in the list of background browsing contexts.

  15. Return the auxiliary browsing context's return value.

The Window objects of Documents hosted by browsing contexts created by the above algorithm must also implement the WindowModal interface.

When this happens, the members of the WindowModal interface, in JavaScript environments, appear to actually be part of the Window interface (e.g. they are on the same prototype chain as the window.alert() method).

[NoInterfaceObject] interface WindowModal {
  readonly attribute any dialogArguments;
           attribute DOMString returnValue;
};
window . dialogArguments

Returns the argument argument that was passed to the showModalDialog() method.

window . returnValue [ = value ]

Returns the current return value for the window.

Can be set, to change the value that will be returned by the showModalDialog() method.

Such browsing contexts have associated dialog arguments, which are stored along with the dialog arguments' origin. These values are set by the showModalDialog() method in the algorithm above, when the browsing context is created, based on the arguments provided to the method.

The dialogArguments IDL attribute, on getting, must check whether its browsing context's active document's origin is the same as the dialog arguments' origin. If it is, then the browsing context's dialog arguments must be returned unchanged. Otherwise, if the dialog arguments are an object, then the empty string must be returned, and if the dialog arguments are not an object, then the stringification of the dialog arguments must be returned.

These browsing contexts also have an associated return value. The return value of a browsing context must be initialized to the empty string when the browsing context is created.

The returnValue IDL attribute, on getting, must return the return value of its browsing context, and on setting, must set the return value to the given new value.

The window.close() method can be used to close the browsing context.