Customizing Open Modal Dialog Box

                                     How to: Display a Page as a Modal Dialog Box

Overview

The Microsoft® SharePoint® 2010 user interface makes extensive use of modal dialog boxes, which helps to improve the user experience by reducing the number of postbacks. You can use this functionality in your own applications through the use of the SharePoint client object model. This how-to topic describes how to use the SharePoint ECMAScript object model to launch a page as a modal dialog box.

For a practical example of the deployment and use of pages for modal dialog boxes, including how to pass information to the modal dialog box, see the Full-Trust Proxy Reference Implementation. For more information about using the SharePoint client object model in JavaScript, see ECMAScript Object Model Reference on MSDN.

Note:
These steps are designed for sandboxed solution deployment. However, you can use the same approach to deploy JavaScript functions within farm solutions.

Summary of Steps

This how-to topic includes the following steps:

• Step 1: Create and Configure a Module. In this step, you create a feature manifest file that contains a Module element. This specifies which files to deploy and where to deploy them.
• Step 2: Create the JavaScript Function. In this step, you create a JavaScript file and add it to the module. The file contains a function that accepts a page URL and displays the page as a modal dialog box.
• Step 3: Add the Module to a Feature. In this step, you create a feature and add the feature manifest file to the feature. This enables you to deploy your JavaScript function to the SharePoint environment.
• Step 4: Invoke the JavaScript Function. In this step, you use the JavaScript function to launch the site calendar as a modal dialog box.

Note:
This how-to topic assumes that you have used the Microsoft Visual Studio® 2010 development system and one of the SharePoint 2010 templates to create a project.

Step 1: Create and Configure a Module

This procedure creates a feature manifest that contains a Module element. You will use the module to deploy the JavaScript file. The module is configured to add files to the content database, which enables you to deploy it within a sandboxed solution.

To create a Module element

1. In Solution Explorer, right-click the project node, point to Add, and then click New Item.
2. In the Add New Item dialog box, expand SharePoint in the Installed Templates pane, and then click 2010.
3. Click Module, type a name for the module in the Name text box, and then click Add. This example uses the name Scripts for the module.
   
   In Solution Explorer, notice that Visual Studio has added a Scripts node to represent your module.
   
4. In Solution Explorer, right-click the Scripts node, point to Add, and then click New Item.
5. In the Add New Item dialog box, click Web in the Installed Templates pane, and then click the Jscript File template.
6. In the Name text box, type jsFunctions.js, and then click Add.
7. Open the Elements.xml file in the Script module. Notice that Visual Studio has added a File element for the jsFunctions.js file.
   XML

   <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
     <Module Name="Scripts">
       <File Path="Scripts\Sample.txt" Url="Scripts/Sample.txt" />
       <File Path="Scripts\jsFunctions.js" Url="Scripts/jsFunctions.js" />
     </Module>
   </Elements>
   
   

8. In the Module element, add a Url ="_catalogs/masterpage" attribute value. This tells the feature to deploy the JavaScript file to the site's master page gallery.

   Note:
   In a sandboxed solution, you are not permitted to deploy any files to the server-side file system. Instead, you can deploy the JavaScript file to the site's master page gallery. This ensures that it is available to all users who can view the site.
9. In the Module element, add a List="116" attribute value. This indicates that the destination is a library of type master page gallery.
10. Delete the File element for the Sample.txt file. You can also delete the Sample.txt file from Solution Explorer.
11. Make the following changes to the File element for the jsFunctions.js file:
    1. Leave the Path attribute value as Scripts\jsFunctions.js. This tells the feature where to find the file in your Visual Studio project.
    2. Change the Url attribute value to jsFunctions.js. This specifies the virtual path to the file in the virtual directory specified by the Module element.
    3. Add a Type="GhostableInLibrary" attribute value. This indicates that the file will be stored as a document library item in the content database.

    Note:
    Visual Studio 2010 does not always automatically pick up the feature manifest schema. If you see schema errors or you lack IntelliSense support when you edit a feature manifest, check the properties of the XML document in the Properties window. The Schemas property should be set to 14\TEMPLATE\XML\wss.xsd.
12. The feature manifest should resemble the following code example.
    C#

    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
      <Module Name="Scripts" List="116" Url="_catalogs/masterpage">
        <File Path="Scripts\jsFunctions.js" Url="jsFunctions.js"   
              Type="GhostableInLibrary"/>
      </Module>
    </Elements>
    
    

    Note:
    For sandboxed deployments, you can use Type attribute values of Ghostable or GhostableInLibrary. Use GhostableInLibrary if your deployment target is a document library and you want SharePoint to create a parent list item for your file.

Step 2: Create the JavaScript Function

This procedure creates a JavaScript function. The function accepts a single argument that represents the URL of a Web page. The function then uses the SharePoint ECMAScript object model to launch the specified page as a modal dialog box.

To create a JavaScript function that launches a modal dialog box

1. In Solution Explorer, double-click jsFunctions.js to open the file.
2. Add a function named ShowDialog that takes a single argument named url.
   JavaScript

   function ShowDialog(url) { }
   
   

3. Add the following code to the ShowDialog function.
   JavaScript

   var options = SP.UI.$create_DialogOptions();
   options.url = url;
   options.height = 300;
   SP.UI.ModalDialog.showModalDialog(options);
   
   

4. When invoked, this JavaScript function launches the specified page as a modal dialog box with a height of 300 pixels.

Step 3: Add the Module to a Feature

This procedure adds the module to a feature, which provides the mechanism to deploy your JavaScript file to the SharePoint environment.

To add a module to a feature

1. In Solution Explorer, right-click the Features node, and then click Add Feature.

   Note:
   Visual Studio 2010 may have already added an empty feature when you added the module. In this case, you can either rename the empty feature or delete it and create a new one.
2. In Solution Explorer, right-click the new feature node, and then click Rename. Type a name for the feature. This example uses the name ScriptsFeature.
3. Double-click the ScriptsFeature node to open the Feature Designer.
4. In the Feature Designer, set the feature scope to Site.
5. In the Items in the Solution pane, click the Scripts module.
6. Click the right arrow button to add the module to the feature. This moves the feature to the Items in the Feature pane.
   

Step 4: Invoke the JavaScript Function

You can use your JavaScript function in several different ways. This procedure provides a simple demonstration that uses the JavaScript function to display the site calendar as a modal dialog box page.

To invoke the JavaScript function

1. In Solution Explorer, right-click the project node, point to Add, and then click New Item.
2. In the Add New Item dialog box, expand SharePoint in the Installed Templates pane, and then click 2010.
3. Click Web Part, type a name for the module in the Name text box, and then click Add. This example uses the name DialogDemo for the Web Part.
   
4. Add the following using statement to the DialogDemo class.
   C#

   using System.Web.UI.HtmlControls;
   
   

5. Add the following constant string to the DialogDemo class. This indicates the site-relative location of the JavaScript file.
   C#

   const string jsScriptURL = "/_catalogs/masterpage/jsFunctions.js";
   
   

6. Add the following code to the CreateChildControls method. This renders an HTML script element that loads the JavaScript file.
   C#

   HtmlGenericControl scriptInclude = new HtmlGenericControl("script");
   scriptInclude.Attributes.Add("src", 
                          SPContext.Current.Site.RootWeb.Url + jsScriptURL);
   Controls.Add(scriptInclude);
   
   

7. Add the following code to the CreateChildControls method. This renders a hyperlink that calls the ShowDialog function, passing in the relative URL of the site calendar.
   C#

   HyperLink link = new HyperLink();
   link.Text = "View Calendar";
   link.NavigateUrl = string.Concat("javascript: ShowDialog('",
                                     SPContext.Current.Site.RootWeb.Url,
                                    "/Lists/Calendar/calendar.aspx')");
   this.Controls.Add(link);
   
   

8. In Solution Explorer, double-click the ScriptsFeature node to open the Feature Designer. Make sure that the DialogDemo Web Part is added to the feature.
9. In Solution Explorer, right-click the project node, and then click Deploy.
10. Browse to your test site, add the DialogDemo Web Part to a page, and then click the View Calendar link.

    Note:
    By default, the DialogDemo Web Part is added to the Custom Categories Web Part group.
    
11. The site calendar is displayed in a modal dialog box.