Sharepoint Modal Dialog Configuration And Callback Functions

ByThe SharePoint FAQs Team

Opening SharePoint Modal Dialogs

SharePoint provides the ability to open modal dialog popups to display forms, messages, or allow user input. The main method used to open a modal dialog in SharePoint is SP.UI.ModalDialog.showModalDialog(). This method opens a modal dialog popup using the provided URL and options. Some key things to note when opening SharePoint modal dialogs:

  • The dialog URL can point to a SharePoint form, ASPX page, or external page
  • Dialog parameters can be passed in to customize the displayed content
  • Callback functions can be specified to handle dialog data when closed
  • Various dialog options are available like width, height, add scrollbar, etc

Using SP.UI.ModalDialog.showModalDialog() Method

The SP.UI.ModalDialog.showModalDialog() method is used to open a modal dialog in SharePoint. This method accepts a dialog URL, any parameters to pass, and a dialog options object. Here is an example usage:

SP.UI.ModalDialog.showModalDialog({
  url: "/sites/site/form.aspx",
  parameters: {param1: "value1"},
  options: {width: 600, height: 400}
});

This opens a modal dialog popup pointing to the form.aspx page, passes in a custom parameter, and sets the width and height options. The dialog will be displayed modally, blocking interaction with the underlying page until the user closes it.

Passing Parameters to the Dialog

Custom parameters can be passed to the modal dialog by specifying them in the parameters property. This allows dynamic content to be displayed based on the calling page. For example:

var itemId = 1234;

SP.UI.ModalDialog.showModalDialog({
  url: "/sites/site/details.aspx",
  parameters: {itemId: itemId}  
});

Here the itemId parameter is passed to details.aspx, which can use it to look up and display the details for that specific item.

Parameters can be used within the dialog page by accessing the query string. In ASPX, the Request.QueryString collection contains all passed parameters.

Configuring Modal Dialog Behavior

SharePoint provides several options to control the look, feel, and functionality of modal dialogs. By customizing these options, dialogs can be sized appropriately, scrolled if needed, and customized for the specific scenario.

Setting Dialog Options

Modal dialogs support various options that specify properties like size, title, behavior, and appearance. This options object can be passed to the SP.UI.ModalDialog.showModalDialog() method. Some commonly used options include:

  • width – Sets dialog width in pixels
  • height – Sets dialog height in pixels
  • title – Custom text for the dialog title
  • allowMaximize – Allow user to maximize dialog
  • showClose – Show or hide close button

For example, to show a large 800×600 dialog with scrolling and a custom title:

SP.UI.ModalDialog.showModalDialog({
  url: "/form.aspx",
  options: {
    width: 800,
    height: 600,
    title: "Custom Form",
    scroll: true 
  }
})

Enabling Scrollbars and Resizing

If a modal dialog has significant content, scrollbars can be enabled using the dialogReturnValueCallback option. Setting this to true will add scrollbar when content overflows.

User resizable dialogs can also be enabled with the allowMaximize option. This shows a maximize icon that allows the user to resize larger or smaller.

Retrieving Data from Modal Dialogs

Often modal dialogs are used to gather input or display information to the user. Any data needs to be returned back to the original calling page when the dialog closes. SharePoint provides callback functions and return values to achieve this communication between the parent and dialog.

Accessing Dialog Return Value in Callback

The primary way to retrieve data from a modal dialog is via a return value that gets passed to a callback function. This callback is called when the dialog closes. For example:

SP.UI.ModalDialog.showModalDialog({
  url: "/form.aspx",
  options: {
    title: "Edit Item",
    dialogReturnValueCallback: function(dialogResult) {
      // Access dialog return value  
    }
  }  
});

The function passed to dialogReturnValueCallback gets called when the dialog closes. The dialogResult parameter contains any value returned from the dialog page.

Getting Updated Field Values

To actually return data, the dialog page needs to call SP.UI.ModalDialog.commonModalDialogClose() while passing a return value. This value then gets passed back to the callback function. For example in the dialog ASPX page:

var updatedValue = // Logic to get updated value   

SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, updatedValue);

This would return the updatedValue object back to the callback function for processing.

Processing Returned Data

After a modal dialog has been closed and return value received, the callback function needs to process it appropriately. Common actions include updating SharePoint list items, refreshing the parent page, or rerendering UI elements with new data.

Updating SharePoint List Items

If a modal dialog gathers input that updates SharePoint list items, the callback function can call the Lists web service to update. For example:

SP.UI.ModalDialog.showModalDialog({
  // Open dialog options...
  
  options: {
   dialogReturnValueCallback: function(dialogResult) {
     var item = dialogResult.updatedItem;
     
     $().SPServices({
       operation: "UpdateListItems",  
       listName: "Tasks",
       ID: item.ID,
       valuepairs: [[
           "Title", item.Title
       ], 
       [
          "PercentComplete", item.PercentComplete
       ]]
      });
   }
  }
});

This processes the returned updatedItem object and updates the corresponding SharePoint list item using the SPServices library.

Refreshing Parent Page After Dialog Close

Sometimes modal dialogs update other parts of the page that need to be refreshed once it closes. Call the page reload function in the callback to do this.

SP.UI.ModalDialog.showModalDialog({
  // Open dialog
  
  options: {
    dialogReturnValueCallback: function() {
      SP.UI.Notify.addNotification("Item updated");
      
      // Refresh page to show updates  
      window.location.reload();   
    }
  }
});

Modal Dialog Code Examples

Here are some common code examples for configuring and working with SharePoint modal dialogs:

Minimal Configuration Modal Dialog

Opens a basic modal dialog with default options:

  
SP.UI.ModalDialog.showModalDialog("/sites/site/form.aspx");

Modal Dialog with Scrollbars and Callback Function

Opens a modal with scrollbars and return value callback:

SP.UI.ModalDialog.showModalDialog({

  url: "/sites/site/details.aspx",
  
  options: {
    title: "Item Details",
    autoSize: true,
    scroll: true,
    
    dialogReturnValueCallback: function(result) {
      // Return value handling
    } 
  }
});

Updating List After Dialog Form Submit

Dialog updates list items after user input:

 
SP.UI.ModalDialog.showModalDialog({

  url: "/sites/site/editForm.aspx",
   
  options: {  
    dialogReturnValueCallback: function(result) {
    
      // Update item in Tasks list
      $().SPServices({
        operation: "UpdateListItems",
        listName: "Tasks", 
        ID: result.ID,
        valuepairs: [[
           "PercentComplete", result.percentComplete
        ]]
      });
    }
  }  
});

Troubleshooting Common Modal Dialog Issues

Some common issues faced when working with SharePoint modal dialogs include:

Debugging Empty Dialog Return Values

If callback function shows undefined or empty return value from dialog, ensure SP.UI.ModalDialog.commonModalDialogClose() is called properly to return a value back.

Fixing Popup Blockers

Popup blockers can prevent modal dialogs from opening. Users should whitelist SharePoint site to allow popups to show.

Handling Dialog Errors Gracefully

Use try/catch statements around modal calls to catch errors opening dialogs. Display user-friendly messages if issues occur.

Leave a Reply

Your email address will not be published. Required fields are marked *