Methods

closeModalDialog

(source code)
closeModalDialog(dialogResult, returnValue)
Close the last modal dialog

Parameters:

Object
dialogResult Optional
One of the enumeration values specifying the result of the modal dialog (SP.UI.DialogResult|), or the modal object returned by $SP().getModalDialog()
Object
returnValue Optional
The return value of the modal dialog

Example:

// if the user use the cross to close the modal, then `dialogResult` equals to 0 in the callback
// but you can trigger the close of the modal and pass anything you want
$SP().showModalDialog({
  id:"demo",
  title:"Hello World",
  html:'<p>This is an example. Click one of the buttons.</p><p class="ms-alignCenter"><button onclick="$SP().closeModalDialog(\'Continue has been clicked\')">Continue</button></p>',
  callback:function(res) {
    alert(res)
  }
})

// or
var modal = $SP().getModalDialog('demo');
if (modal) $SP().closeModalDialog(modal);

getModalDialog

(source code)
getModalDialog(id)
Retrieve the modal object for a special modalDialog

Parameters:

String
id
The ID of the modal

Returns:

Object
The modal object or NULL if the modal doesnt exist

Example:

var modal = $SP().getModalDialog("MyModal");
$SP().closeModalDialog(modal);

notify

(source code)
notify(message, options)
Permits to notify the user using the SP.UI.Notify.addNotification system

Parameters:

String
message
Message to show
Object
options Optional
Integer
options.timeout Optional, Default: 5
The number of seconds that the notification is shown
Boolean
options.override Optional, Default: false
This option to TRUE permits to remove the previous/current notification that is showing (even if the timeout is not over and even if it's a sticky) and replace it with the new one
Boolean
options.overrideAll Optional, Default: false
Same as previously except that it will remove *all* the previous notifications that are currently showing
Boolean
options.overrideSticky Optional, Default: true
When "overrideAll:true" then even the sticky notifications are removed, but you can block this behavior with "overrideSticky:false"
Boolean
options.sticky Optional, Default: false
Keep the notification on the screen until it's manually removed (or automatically removed with "overrideAll:true" and "overrideSticky:true")
String
options.name Optional, Default: random()
You can give a name to the notification (to use it with $SP().removeNotify('name'))
Function
options.after Optional, Default: function(name,afterDelay){}
You can call this function when the notification is removed -- the argument "name" is the name of the notification (see previous option), the argument "afterDelay" is TRUE when the notification has been removed by the system after it's normal timeout

Example:

$SP().notify('Processing the data...', {sticky:true}); // the notification will stay on the screen until we remove it
$SP().notify('All done!', {overrideAll:true}); // the "Processing the data..." is removed from the screen and a 5 seconds message says "All done!"

$SP().notify('Please wait 10 seconds...', {
  name:"My 10 seconds notification",
  timeout:10,
  after:function(name,afterDelay) {
    if (afterDelay) alert("OK, you waited during 10 seconds!")
    else alert("Something just removed this notification called '"+name+"'' before the timeout :-(")
  }
})

removeNotify

(source code)
removeNotify(name, options)
Permits to remove a notification that is shown on the screen

Parameters:

String
name Optional
Name of the notification
Object
options Optional
If you pass the options, then the 'name' is ignored
Boolean
options.all Optional, Default: false
To TRUE to remove ALL notifications
Boolean
options.includeSticky Optional, Default: true
To FALSE if you don't want to remove the sticky notifications (only works with the "all:true" option)

Example:

$SP().notify('Processing the data...', {sticky:true,name:"Processing data"}); // the notification will stay on the screen until we remove it
$SP().removeNotify("Processing data"); // the notification is removed

$SP().notify('Doing some stuff...');
$SP().notify('Doing some other stuff...');
$SP().removeNotify({all:true}); // all the notifications are removed

$SP().notify('Doing some stuff...');
$SP().notify('Doing some other stuff...');
$SP().notify('This is a sticky message', {sticky:true});
$SP().removeNotify({all:true, includeSticky:false}); // all the notifications are removed except the sticky one

resizeModalDialog

(source code)
resizeModalDialog(options, width, height, id)
Resize a ModalDialog and recenter it

Parameters:

Object
options
Number
width
Number
height
String
id Optional
The id of the modal to resize, or the last opened dialog will be used

Returns:

Boolean
FALSE if something went wrong

Example:

// to have a form opened faster we define a minimal width and height, and then once it's loaded we want to have the correct size
$SP().showModalDialog({
  id:"inmodal",
  url:url,
  width:200,
  height:100,
  allowMaximize:true,
  onurlload:function() {
    // resize the frame by checking the size of the loaded page
    var iframe=window.top.document.getElementById('sp_frame_inmodal').nextSibling.querySelector('iframe');
    // define the max size based on the page size
    var size = $SP().getPageSize();
    var maxWidth = 2*size.vw.width/3; // 2/3 of the viewport width
    var maxHeight = 90*size.vw.height/100 // 90% of the viewport height
    // find the size we want based on the modal
    var e=$(iframe.contentDocument.getElementById('onetIDListForm')); // this element gives the size of our form from the modal
    var width=e.outerWidth(true)+100;
    var height=e.outerHeight(true)+iframe.contentDocument.getElementById('ms-designer-ribbon').offsetHeight+100;
    if (width>maxWidth) width=maxWidth;
    if (height>maxHeight) height=maxHeight;
    $SP().resizeModalDialog({id:"inmodal",width:width,height:height});
    // bind the iframe resize, to make sure an external event won't resize it to 200x100
    $(iframe.contentWindow).on('resize', function() {
var $this=$(this);
if ($this.width() === 200 && $this.height() === 100) { // if it gets the original size, then resize to the new ones
  $SP().resizeModalDialog({id:"inmodal",width:width,height:height});
}
    })
  }
});

showModalDialog

(source code)
showModalDialog(options)
Show a modal dialog (based on SP.UI.ModalDialog.showModalDialog) but provides some advanced functions and better management of the modals (for example when you launch several modals)

Parameters:

Object
options Optional
Regular options from http://msdn.microsoft.com/en-us/library/office/ff410058%28v=office.14%29.aspx with some additional ones or some changes
String
options.html Optional
We can directly provide the HTML code as a string
String
options.width Optional
If equals to "calculated", then we use the 2/3 of the viewport width; if equals to "full" then we use the full viewport width; otherwise see the original documentation (https://msdn.microsoft.com/en-us/library/office/ff410058(v=office.14).aspx)
String
options.height Optional
If equals to "calculated", then we use 90% of the viewport height; if equals to "full" then we use the full viewport height; otherwise see the original documentation (https://msdn.microsoft.com/en-us/library/office/ff410058(v=office.14).aspx)
Boolean
options.closePrevious Optional, Default: false
It permits to close a previous modal dialog before opening this one
Boolean
options.wait Optional, Default: false
If we want to show a Wait Screen (alias for $SP().waitModalDialog())
String
options.id Optional, Default: random()
An unique ID to identify the modal dialog (don't use space or special characters)
Function
options.callback Optional
A shortcut to `dialogReturnValueCallback` with dialogResult and returnValue
Function
options.onload Optional
The modal might be delayed as we need to load some Sharepoint JS files; the `onload` function is called once the modal is shown
Function
options.onurlload Optional
When we use the "url" parameter, this is triggered when the DOMContent of the iframe is loaded (if it's the same origin)
String
options.title Optional
The title to give to the modal (if you use `wait:true` then it will be the main text that will appear on 2013, and the modal title for 2010)
String
options.message Optional
This parameter is only use if there is `wait:true` and permits to define the subtitle message for 2013, or the main message for 2010
String
options.url Optional
A string that contains the URL of the page that appears in the dialog. If both url and html are specified, url takes precedence. Either url or html must be specified.
Number
options.x Optional
An integer value that specifies the x-offset of the dialog. This value works like the CSS left value.
Number
options.y Optional
An integer value that specifies the y-offset of the dialog. This value works like the CSS top value.
Boolean
options.allowMaximize Optional
A Boolean value that specifies whether the dialog can be maximized. true if the Maximize button is shown; otherwise, false.
Boolean
options.showMaximized Optional
A Boolean value that specifies whether the dialog opens in a maximized state. true the dialog opens maximized. Otherwise, the dialog is opened at the requested sized if specified; otherwise, the default size, if specified; otherwise, the autosized size.
Boolean
options.showClose Optional, Default: true
A Boolean value that specifies whether the Close button appears on the dialog.
Boolean
options.autoSize Optional
A Boolean value that specifies whether the dialog platform handles dialog sizing.

Returns:

Promise
If will return an object with two parameters: dialogResult, returnValue

Example:

// using a callback
$SP().showModalDialog({
  title:"Dialog",
  html:'<h1>Hello World</h1><p><button type="button" onclick="$SP().closeModalDialog(\'here\')">Close</button></p>',
  callback:function(dialogResult, returnValue) {
    alert("Result="+dialogResult); // -> "here"
  }
})

// using as a Promise
$SP().showModalDialog({
  title:"Dialog",
  html:'<h1>Hello World</h1><p><button type="button" onclick="$SP().closeModalDialog(\'here\')">Close</button></p>'
})
.then(function(res) {
  alert("Result="+res.dialogResult); // -> "here"
})

// show a waiting message
$SP().waitModalDialog("Working...");
// --- do some stuff ---
// close the waiting message and open a new modal dialog
$SP().showModalDialog({
  closePrevious:true,
  title:"Success",
  html:'<h1>Done!</h1>'
})
// and use $SP().closeModalDialog() to close it

waitModalDialog

(source code)
waitModalDialog(title, subtitle, height, width)
Shortcut for SP.UI.ModalDialog.showWaitScreenWithNoClose()

Parameters:

String
title Optional, Default: "Working on it..."
The main message with the loading spin for SP2013, or the modal window title for SP2010
String
subtitle Optional, Default: ""
The subtitle for SP2013, or the main message with the loading spin for SP2010
Number
height Optional
The modal height
Number
width Optional
The modal width