Home Library Learn Downloads Support Community
Sign in | United States - English | |
1 out of 2 rated this helpful - Rate this topic

SP.UI.ModalDialog.showModalDialog(options) Method

SharePoint 2010

Displays a modal dialog with specified dialog options.

Copy 
var value = SP.UI.ModalDialog.showModalDialog(options);

options

Type: Object

The options to create the modal dialog.

Type: SP.UI.ModalDialog

A modal dialog with the specified options.

The following table lists the available dialog options. To set an option, set the indicated property of the options parameter. All of these options are optional. However, either the url or html option is required.

options Property

Description

title

A string that contains the title of the dialog.

url

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.

html

A string that contains the HTML of the page that appears in the dialog. If both html and url are specified, url takes precedence. Either url or html must be specified.

x

An integer value that specifies the x-offset of the dialog. This value works like the CSS left value.

y

An integer value that specifies the y-offset of the dialog. This value works like the CSS top value.

width

An integer value that specifies the width of the dialog. If width is not specified, the width of the dialog is autosized by default. If autosize is false, the width of the dialog is set to 768 pixels.

height

An integer value that specifies the height of the dialog. If height is not specified, the height of the dialog is autosized by default. If autosize is false, the dialog height is set to 576 pixels.

allowMaximize

A Boolean value that specifies whether the dialog can be maximized. true if the Maximize button is shown; otherwise, false.

showMaximized

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.

showClose

A Boolean value that specifies whether the Close button appears on the dialog.

autoSize

A Boolean value that specifies whether the dialog platform handles dialog sizing.

dialogReturnValueCallback

A function pointer that specifies the return callback function. The function takes two parameters, a dialogResult of type SP.UI.DialogResult Enumeration and a returnValue of type object that contains any data returned by the dialog.

args

An object that contains data that are passed to the dialog.
Copy 
//Using the DialogOptions class.
var options = SP.UI.$create_DialogOptions();

options.title = "My Dialog Title";
options.width = 400;
options.height = 600;
options.url = "/_layouts/DialogPage.aspx";

SP.UI.ModalDialog.showModalDialog(options);

//Using a generic object.
var options = {
    title: "My Dialog Title",
    width: 400,
    height: 600,
    url: "/_layouts/DialogPage.aspx" };

SP.UI.ModalDialog.showModalDialog(options);
Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Example to show HTML in Modal Dialog
I think an example of showing simple HTML text in modal dialog would be helpful.
History
.HTML options Property
As mentioned in prior posts, the 'html' entry uses a DOM element as its input.  When the dialog is closed, the DOM element that was provided will be destroyed.  If a user accesses the Modal Dialog through a link which provides an existing DOM element as input, that element will be destroyed when the dialog is closed.  If the user clicks the same link again, the DOM element will not exist and an error will occur.  To avoid this error, call .cloneNode(true) on the element and pass the copy in the options property.
History
McAfee Anti-Virus
Note that McAfee Anti-Virus incorrectly identifies any call to javascript functions named "showModalDialog" as malicious.

A work-around is to call "SP.UI.ModalDialog.commonModalDialogOpen" instead. http://msdn.microsoft.com/en-us/library/ff409609.aspx
History
Position of dialog window
The dialog is opened in the middle of the viewing area, ONLY if the current viewing area is the top of the page.
If you have a page that is more than one page long, scroll down to the bottom of the page, and spawn a modal dialog, it may be positioned partly or even entirely outside of the visible area of the screen, forcing the user to scroll to see the dialog at all.

Manually calculating and setting an x and y position which compensates for scroll position does not help, because when opening the dialog, this check is done (pseudo code):
If (x + width) > (width of visible area, regardless of scroll position) --> x = 0
If (y + height) > (height of visible area, regardless of scroll position) --> y = 0
(margins etc are concidered but left out for abbrevity).

There is a common fix for this which is basically adding this CSS:

.ms-dlgContent
{
position:fixed! important;
}

However, in IE (at least IE8) this will cause a white square showing behind the dialog. How bad it looks depends on scroll position, window size, dialog size, etc.
History
SP.UI.Dialog options Properties
http://msdn.microsoft.com/en-us/library/ff411351.aspx
History
Rendering html in a SharePoint Dialog requires a DOM element and not a String
.html option takes a DOM element rather than a string $0$0 $0 $0 $0function ShowDialog()$0 $0{$0 $0var htmlElement = document.createElement('p');$0 $0$0 $0 $0var helloWorldNode = document.createTextNode('Hello world!');$0 $0var htmlElement.appendChild(helloWorldNode);$0 $0$0 $0 $0var options = {$0 $0html: htmlElement,$0 $0autoSize:true,$0 $0allowMaximize:true,$0 $0title: 'Test dialog',$0 $0showClose: true,$0 $0};$0 $0$0 $0 $0var dialog = SP.UI.ModalDialog.showModalDialog(options);$0 $0}$0 $0 $0$0 $0 $0See the original post on my blog: http://www.neilrichards.net/blog/?p=124$0
History
Options available in SP.UI.ModalDialog
From: http://www.chaholl.com/archive/2010/11/17/using-the-dialog-framework-in-sharepoint-2010.aspx


allowMaximize
boolean (true/false)
true
Determines whether the maximise button is present on the rendered dialog.

args
object

We’ll examine this property in more detail later. The args property allows us to pass arbitrary properties into our dialog.

autoSize
boolean (true/false)
true
Determines whether the dialog should be automatically sized to fit within the parent browser window. Where a value has been set for width or height, this value is deemed to be false regardless of the actual setting.

dialogReturnValueCallback
function

We’ll examine this property in more detail. By passing a function, we can specify a section of script to be executed when the dialog is closed.

height
numeric

The height of the dialog to be displayed. If this value is not set the dialog is automatically sized to fit the window.

html
string

Where a Url is passed, an IFRAME tag is rendered pointing to the appropriate Url. AS an alternative to this, it is possible to pass arbitrary HTML instead, in which case, rather than an IFRAME tag, the arbitrary HTML is rendered instead.

showClose
boolean (true/false)
true
Determines whether the close button is visible in the titlebar of the dialog.

showMaximized
boolean
(true/false)
false
Dictates whether the rendered dialog should fill the available space in the parent window.

title
string

Specifies the title of the dialog. Where no title is specified, the title of the document referred to by the Url property is used instead.

url
string
null
The url of the page to be shown in the dialog. Where a url is set and IFRAME tag will be rendered by the Dialog framework and the src of the IFRAME will be set to this url.

width
numeric

The width of the dialog to be displayed. If this value is not set the dialog is automatically sized to fit the window.

x
numeric

Specifies the starting position of the rendered dialog. If this value is not set the dialog is shown in the middle of the viewing area. This value represents the offset from the left edge of the parent browser window.

y
numeric

Specifies the starting position of the rendered dialog. If this value is not set the dialog is shown in the middle of the viewing area. This value represents the offset from the bottom of the parent browser window.
History