A dive into the SharePoint 2010 SP.UI.ModalDialog ECMAScript Class Library

I’m pretty interested in the ECMAScript class library of the SharePoint 2010, since, the documentation isn’t available on MSDN yet. I’ll try and explain the SP.UI.ModalDialog  methods.

Method Description Return Value
showModalDialog (options). The method will basically open a dialog with the a specified URL. The parameter SP.UI.DialogOptions though is very handy. It has some useful parameters. The URL of the page to be displayed in the dialog, the dialog title, the width and the height of the dialog. Also you can choose whether you want to show or hide the close and maximize buttons.
You can use the return object value to get the current URL,title, and the HTML of the dialog, Also you can check if the dialog was closed, and get the return value.
object of type SP.UI.ModalDialog
commonModal DialogClose (dialogResult, returnVal) The method is used within the dialog to close it. The method calls the DialogCallback method specified while opening the dialog and passes the 2 parameters to the callback method. The dialogResult which is an enumeration of type SP.UI.DialogResult with 3 values OK,Cancel, and Invalid. The other parameter is a return value of type object. void
OpenPopUpPage (URL, callback, width, height) Opens a dialog with the specified values but the difference is that you have less control over the dialog. void
ShowPopupDialog (url) Opens a dialog with the specified URL. It does the auto sizing for you. But you have no other control on the dialog. void
commonModal DialogOpen (url, options, callback, args) Opens the dialog with the URL and options passed parameters. Note that the values specified in the method call will override the values specified within the options void
showWaitScreenSize (title, message, callbackFunc, height, width) Opens a dialog and displays the default progress image of the SharePoint. When closed, the callback method is called. object of type SP.UI.ModalDialog
showWaitScreen WithNoClose (title, message, height, width) Opens a dialog and displays the default progress image of the SharePoint. The close button is hidden. object of type SP.UI.ModalDialog
RefreshPage (dialogResult) Refresh the page after closing the dialog. void

Example of using the SP.UI.DialogOptions:

var options = {
url: "AddCarPage.aspx",
title: "Custom Add Page",
showClose: false,
allowMaximize: false,
autoSize: true,
// width: 800,
// height: 600,
dialogReturnValueCallback: DialogCallback
dlg = SP.UI.ModalDialog.showModalDialog(options);

Using the Sharepoint 2010 Dialog

The new dialog framework is introduced in the SharePoint new Client OM. You can check the Client OM at http://msdn.microsoft.com/en-us/library/ee535231.aspx. For now, we’re interested in the method SP.UI.ModalDialog.showModalDialog.

How it works?

When the showModalDialog method is invoked the SharePoint adds a div element named “ms-dlgContent”. The dialog contents are rendered from the passed URL. The passed URL can be a link to the web or a custom page. Also, the dialog can open a List Form dialog (Add/Edit). Another div element named “ms-dlgOverlay” disables the user from clicking on the original page and thus, provides the user with a modal dialog.

The showModalDialog method takes 1 parameter; an object of the Class SP.UI.DialogOptions. The option object contains the width and height of the dialog, the URL of the page and the dialog CallBack method name.


The Preparation

1. Create a new Layouts page.

2. Add 3 input buttons to the PlaceHolderMain of the ASPX page. The buttons should look something like this

<input type="button" value="Open Google in Popup" id="btnGoogle"  onclick="OpenWebPage();"/>
<input type="button" value="Open My Custom Page" id="btnMyPage"  onclick="OpenMyWebPage();"/>
<input type="button" id="btnAddItem" value="Add Item" onclick="NewItemDialog();" />

3. Add a CallBack method that will be called when the dialog closes, in order to notify the user with the result of the dialog. You can find more info about the SP.UI.Notify.addNotification here

function DialogCallback(dialogResult, returnValue) {
meesageId = SP.UI.Notify.addNotification(returnValue, false);

1. Open a link to the web

Set the URL of the options object to the web URL.

function OpenWebPage() {
var options= {
width: 800,
height: 600,
dialogReturnValueCallback: DialogCallback

2. Open a Custom page

We’ll Use the AddCarPage that was created in the previous post. We’ll need to modify the 2 Callback methods of success and failure to the following

function Succeeded() {
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK,'Item Created');
function Failed(sender,args) {
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.cancel, 'Item Creation Failed');

Set the URL of the options object to the AddCarPage.aspx

function OpenMyWebPage() {
var options = {
url: "AddCarPage.aspx",
width: 800,
height: 600,
dialogReturnValueCallback: DialogCallback

3. Open a New Item From

Set the URL of the options object to the NewForm.aspx of the list. Note that you can also use any of the form dialogs.

function NewItemDialog() {
var options = {
url: "http://shaalan:4040/sites/UserExperience/Lists/Cars/NewForm.aspx?RootFolder=",
width: 800,
height: 600,
dialogReturnValueCallback: DialogCallback

Adding an Item to a SharePoint List using JavaScript

I found out that adding an item to a list using the Sharepoint client OM  in SharePoint 2010 is not as simple as it seems to be. There are plenty of examples on demos using the Sharepoint client OM in the code behind. But I couldn’t get my hands on how to do this using JavaScript. And the documentation on SP.js isn’t available yet. So how did i do it?

The Preparation

1. Create a custom list named Cars.

2. Create a new Empty SharePoint project.

3. Add a mapped Layouts folder

4. Add a page called AddCarPage.aspx

5. Create JavaScript method called AddCar.

6. Add an input of type button and set it’s onclick to AddCar(). another input of type text and name it as txtCar.

The PlaceHolderMain of the ASPX page should now look something like this :

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
<input type="text" id="txtCar" />
<input type="button" id="btnAddCar" onclick="AddCar();" value="Add Car" />
<label id ="lbl" runat="server"/>

The SharePoint

We need to include the SharePoint ECMAScript library in the aspx page.The main file is SP.js . Information about all the ECMAScript Library can be found here. Including the SP.js can be done using the SharePoint:ScriptLink tag.

<Sharepoint:ScriptLink name="SP.js" runat="server" OnDemand="true" localizable="false" />

We will write our code in the AddCar JavaScript method.

function AddCar() {
//Retrieve the txtCar and check if it has some text.
var txtCar = document.getElementById("txtCar");
if (txtCar.value == "") {
alert("please enter a car");
//Retrieve the clientContext
var clientContext = SP.ClientContext.get_current();
//Retrieve the current website
var webSite = clientContext.get_web();
//Retrieve the lists
var lists = webSite.get_lists();
//Get the Cars List
var carsList = lists.getByTitle("Cars");
//Create new IteamCreationInformation
var itemCreationInfo = new SP.ListItemCreationInformation();
//the addItem takes the itemCreationInformation object
//and returns the listItem
var listItem = carsList.addItem(itemCreationInfo);
//Set the title of the list Item
//to the value in the txtCar
listItem.set_item("Title", txtCar.value);
//Call Update the listItem
//Finally execute the operation
//pass to it a 2 callBack methods OnSucceed and OnFailure

Finally add the 2 CallBack method

function Succeeded() {
function Failed(sender,args) {