Description
The dialog widget displays popup windows within the page, typically loading content from a remote source.
Usage
A dialog is defined simply by including the widget key as an attribute on a trigger element. It is recommended that the trigger element be a link or button, so that if the user has javascript disabled their browser can take them to a full-page version of the dialog contents.
<a href='...' data-ipsDialog data-ipsDialog-url='...'>Launch dialog</a>
Dialogs offer special functionality for forms contained with the dialog, enabling them to be automatically validated and submitted via AJAX when used with the form helper from the IPS4 PHP framework. See the remoteVerify and remoteSubmit options below.
Obtaining a dialog reference
If you need to control a dialog programmatically, you can do so by first obtaining the reference to the dialog. To do so, call the getObj method, passing in the element on which the dialog was created as the parameter:
// HTML
<div id='elementWithDialog' data-ipsDialog>
...
</div>
// Javascript
var dialog = ips.ui.dialog.getObj( $('#elementWithDialog') );
The returned reference to the dialog instance can be used to call the methods shown below.
Creating a dialog programmatically
Dialogs can be created programmatically by controllers instead of being created on particular elements. To achieve this, call the create method:
var dialog = ips.ui.dialog.create( object options );
The options parameter should be an object containing keys for the options below.
This method returns a reference to the dialog instance on which you can call methods to control the dialog, for example:
dialog.show(); dialog.hide();
Instance methods
show( boolean initOnly )
Initializes and shows the dialog. If initOnly is true, the dialog is initialized but not immediately shown.
hide()
Hides the dialog.
remove( boolean hideFirst )
Removes the dialog from the DOM. If hideFirst is true, the dialog will call hide() and remove itself after the animation is completed.
setLoading( boolean loading )
If loading is true, indicates to the user that something is being loaded (i.e. shows a spinner in the dialog). If loading is false, removes the loading state. Note: this method doesn't empty the dialog content first. Call instance.updateContent('') manually if desired.
updateContent( string newContent )
Updates the contents of the dialog with the provided newContent. New controllers/widgets are automatically initialized after updating.
Options
url
(String; optional)
If provided, the dialog contents will be loaded by calling this URL when the dialog is launched.
content
(Selector; optional)
If the dialog content already exists in the DOM, this option should be a selector that will locate the wrapper element for the content.
modal
(Boolean; optional; default true)
If true, the page background will fade, preventing the user from interacting with it until the dialog is dismissed.
title
(String; optional)
Sets the title shown in the dialog window. If not set, no title bar will display.
size
(String; optional)
If provided, will set a special class on the dialog designed to change its size. Currently, narrow, medium, wide and fullscreen are supported as values for this option. If not provided, the default dialog width will be used (defined in CSS).
close
(Boolean; optional; default true)
Determines whether the dialog should be built with a close button.
fixed
(Boolean; optional; default false)
Determines whether the dialog is fixed. A fixed dialog is anchored to the viewport, not the page. Its height will also be fixed, with the content scrolling inside if necessary. If this is false, the dialog will scroll with the page, and it will expand to fit all the content being shown, regardless of length.
remoteVerify
(Boolean; optional; default true)
When the dialog contains a form built using the IPS4 PHP framework form helper, this option instructs the dialog to automatically validate the form values and present any errors to the user.
remoteSubmit
(Boolean; optional; default false)
When the dialog contains a form built using the IPS4 PHP framework form helper, this option instructs the dialog to submit the form values via AJAX. If remoteVerify is also true, two separate AJAX requests are fired; first, the form is validated, and if successful the form is submitted with a second request.
If remoteSubmit is true, after a successful submit the dialog is closed automatically. If the flashMessage option is provided, it will be shown at this point.
By default, remoteSubmit is false, which means forms submit via a traditional page reload.
callback
(Function; optional)
Specifies a callback function that will be executed after the dialog has loaded remote content. Note: this option cannot be provided via the data API, and is therefore only available when interacting with ips.ui.dialog directly.
forceReload
(Boolean; optional; default false)
By default, once a dialog has loaded its content, it will not do so again even if the dialog is relaunched. By setting this option to true, the dialog will call the url every time it is opened. This option only takes effect when the url option is used.
Events emitted by ips.ui.dialog
openDialog
Triggered when the dialog is shown.
Event data:
-
elemID
ID of the element that triggered the dialog -
dialogID
ID of the dialog element -
dialog
Reference to the dialog element -
contentLoaded
Boolean indicating whether the dialog content has been loaded (may be false if remote content is used)
hideDialog
Triggered when the dialog is hidden.
Event data:
-
elemID
ID of the element that triggered the dialog -
dialogID
ID of the dialog element -
dialog
Reference to the dialog element
dialogContentLoaded
Triggered after remote content has been loaded and inserted into the dialog.
Event data:
-
elemID
ID of the element that triggered the dialog -
dialogID
ID of the dialog element -
dialog
Reference to the dialog element -
contentLoaded
Boolean indicating whether the dialog content has been loaded (always true here)
Events to which ips.ui.dialog responds
closeDialog
Instructs the dialog to close.
Event data:
-
dialogID (required)
The ID of the dialog to close (the event is ignored if the ID does not match the current dialog)
Report Guide