SharePoint 2010 Dialog Framework

One of the really cool additions to SharePoint 2010 is a client side JavaScript framework for displaying popup windows. It is fairly simple to display a custom application page in a popup from some other page. A good out of the box example of this is the “Upload Document” popup available on document libraries:

You can use this same method in your own code. We’ll look at a simple example of a web part that calls into a popup to collect some information from the user. The popup content itself will actually be deployed as an application page.

Start with an Empty SharePoint Project (PopupDemo) in Visual Studio 2010 and add a new Application Page (MyPopup.aspx).

The Application Page will appear under the Layouts/PopupDemo mapped folder. Next add a Visual Web Part (PopupButton).

SharePoint will create a new User Control (PopupDemoUserControl) under the PopupButton web part. Open that file in the editor and add the following code:

<SharePoint:ScriptLink ID="showDailog" runat="server" Name="sp.js" Localizable="false" LoadAfterUI="true" />
<script type="text/javascript">
    function ShowPopup() {

        var options = {
            url: '/_layouts/PopupDemo/MyPopup.aspx’,
            tite: 'My Popup',
            allowMaximize: true,
            showClose: true,
            width: 300,
            height: 200,
            dialogReturnValueCallback: PopupCallback
        };

        SP.UI.ModalDialog.showModalDialog(options);
    }

    function PopupCallback(dialogResult, returnValue) {
        if (dialogResult == SP.UI.DialogResult.OK) {
            addNotification(‘Hello ‘ + returnValue);
            alert(‘Hello ‘ + returnValue);
        }
    }
    </script>
<button type="button" onclick="ShowPopup()" id="popupButton">Ask me</button>

The new code does three things. First it adds a script reference to sp.js which contains the necessary JavaScript for the dialog framework. Second it defines two new client side functions, ShowPopup and PopupCallback. ShowPopup runs when the button is clicked. Notice that we create an instance of Options, setting the URL (to the previously created Application page), title, size, and lastly, a callback function to be executed when the popup dialog is closed. PopupCallback is the callback function. The callback function displays the return value from the dialog using a JavaScript Alert. An alternative to using an alert is shown with the call to addNotification which utilizes the notification area on the page (it is at the bottom right hand corner of the ribbon). Visually, it is nicer than an alert window. Finally the code adds a button which, when clicked, will open the popup by calling ShowPopup.

Now that the web part is complete, some code needs to be added to the actual popup page. Open MyPopup.aspx in the designer and add the following code to the PageHead Content area:

<SharePoint:ScriptLink ID="showDailog" runat="server" Name="sp.js" Localizable="false" LoadAfterUI="true" />
<script type="text/javascript">
    function CancelDialog() {
        SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.cancel, 'Cancel Clicked');
    }

    function AcceptDialog() {
        SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, document.getElementById('<%= txtName.ClientID %>').value);
    }
    </script>

Once again the fist line is a reference to sp.js. The next two functions are responsible for closing the dialog, one with a dialog result of “cancel” and the other “OK”. The second argument passed to commonModelDialogClose is the actual return value being passed back from the dialog. This is optional but in this case, we want to pass a value back to the calling page. To accomplish this, in Accept Dialog, we will build a return value based on the data the user has entered into a text box on the page. The text box and the buttons need to be added to the Main content area on the page:

What is your name:<input type="text" id="txtName" runat="server" /><button type="button" onclick="CancelDialog()">Cancel</button><button type="button" onclick="AcceptDialog()">OK</button>

This is simply a text input and two buttons. The Cancel button calls the CancelDialog JavaScript function and the OK button calls AcceptDialog.

Compile and deploy the project into SharePoint and add the PopupButton web part to a page:

Clicking the button should load our dialog:

 

Enter something in the text box and click the “OK” button. You should then see the value correctly returned to the calling page. If you watch closely, you will also see the same message  appear in the notification area with a yellow background.

Through this simple example I’ve shown you how you can improve the user experience in SharePoint dramatically by using a popup dialog rather than forcing the user to navigate to a separate page. The possibilities go far beyond collecting simple input. We could uploaded a file, deleted a list, logged some information, or done just about anything else you can accomplish with the SharePoint object model.