Modifying the User Interface for Web Parts and Web Parts Pages

 

Nilly Banerjee
Microsoft Corporation

May 2003

Applies to:
    Microsoft® Windows® SharePoint™ Services
    Microsoft Office SharePoint Portal Server 2003
    Microsoft Visual Studio®.NET
    Web Part infrastructure

Summary: Learn how to customize the user interface (UI) for Web Parts and Web Parts Pages. This paper reviews the different methods by which you can modify the UI for Microsoft Windows SharePoint Services and related products. (13 printed pages)

Note   The information in this article also applies to Microsoft Office SharePoint Portal Server 2003, which is built on the Windows SharePoint Services platform.

Contents

Introduction
Customizing by Using the UI
Customizing by Embedding Code
Using Themes to Customize a Site
Customizing the Task Pane
Overriding and Customizing the Web Part Menu
Customizing Task Pane Views
Conclusion

Introduction

When you create Web Parts Pages or develop Web Parts for Microsoft Windows SharePoint Services or Microsoft Office SharePoint Portal Server 2003, you may want to customize the user interface (UI). Windows SharePoint Services makes this task simpler for authors and developers in several ways. You can easily customize the Web Parts Page title bar, use a full object model to manipulate Web Part menus, and use style classes to create UI elements that match the color scheme of any given theme. Additionally, developers and authors can write code to select and control the views displayed in the task pane.

Customizing by Using the UI

This section reviews ways in which you can easily customize a site by using the UI provided by default on a Web Part Page. For example, if you are a page author or contributor with your own page, you may want to customize your title bar Web Part to fit the purpose of your page.

Tip   The home page of any SharePoint site is a customized Web Part Page with a modified header Web Part, title, and image property. To customize those portions of the home page, you can use a compatible Web page editor such as Microsoft Office FrontPage® 2003.

To change the title bar

  1. Click Modify Shared Page in the title bar of the Web Parts page, point to Modify Shared Web Parts, and then click Web Parts Page Title Bar.
  2. In the appropriate boxes, type the title, caption, description, and image link that you want to use, and then click Apply or OK.

To change the default logo image

  1. Delete or rename the WPIcon.gif file located in the following folder:

    local_drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\Template\Images

    **Note   **The HTTP path to this folder is http://server_name/layouts/images/

  2. Copy the new Graphics Interchange Format (GIF) file that you want to use into this folder, and then rename the new GIF file to WPIcon.gif.

Customizing by Embedding Code

Another method that you can use to customize a Web Part Page is to embed code to add additional ASP .NET server controls to the page. The following procedures are examples of the types of controls you can add to a Web Part Page.

To add a page-level menu (for example, the Modify Shared Page menu) to your Web Parts Page, embed the following control into your page.

<WebPartPages:SettingsLink />

Alternatively, you can create a Web Part to execute either of the following lines of code, and then render the myLink control.

myLink = new Microsoft.SharePoint.WebPartPages.SettingsLink("Link Text");

- or -

myLink = new Microsoft.SharePoint.WebPartPages.SettingsLink();

When you execute the constructor on the server, you can insert your own text into the page menu.

**Note   **No HTML is created in addition to the link when you embed a SettingsLink control or execute server-side code. You must manually add any formatting tags that you want to use in your custom text.

To render a Sign In button

To add a Sign In button to your page, embed the following control into your Web Parts Page:

<WebPartPages:AuthenticationButton />

Alternatively, you can create a Web Part to execute the following lines of code, and then render the myButton control:

myButton = new Microsoft.SharePoint.WebPartPages.AuthenticationButton();

Using Themes to Customize a Site

When you customize a Web Parts Page, you may want to ensure that the UI created by your Web Part supports themes, so it can adopt the color-scheme of any theme that is applied to your site. A user interface that does not support themes may become unreadable when a theme is applied to your site. The following images show a Web Part rendered with different themes.

Figure 1. Sample Web Part rendered with the default theme

Because this sample Web Part uses the correct style classes, it also renders the HTML correctly in the Ripple theme and in the Iris theme, as shown in the following examples.

Figure 2. Sample Web Part rendered with the Ripple theme

Figure 3. Sample Web Part rendered with the Iris theme

To render a tool bar at the top of a Web Part

Use the following HTML code:

<table class="ms-toolbar" border="0" cellspacing="0" cellpadding="2">
   <tr>
      <td class="ms-toolbar">
      </td>
      <td class="ms-toolbar">
         <table cellpadding="1" cellspacing="0" border="0">
            <tr>
               <td class="ms-toolbar" nowrap="true">
                  <a tabindex="0" style="cursor:hand;">Command 1</a>
               </td>
            </tr>
         </table>
      </td>
      <td class="ms-separator">|</td>
      <td class="ms-toolbar">
         <table cellpadding="1" cellspacing="0" border="0">
            <tr>
               <td class="ms-toolbar" nowrap="true">
                  <a tabindex="0" style="cursor:hand;">Command 2</a>
               </td>
            </tr>
         </table>
      </td>
      <td class="ms-separator">|</td>
      <td class="ms-toolbar">
         <table cellpadding="1" cellspacing="0" border="0" ID="Table4">
            <tr>
               <td class="ms-toolbar" nowrap="true">
                  <a tabindex="0" style="cursor:hand;">Command 3</a>
               </td>
            </tr>
         </table>
      </td>
      <td width="100%" class="ms-toolbar" nowrap="true"></td>
      <td align="right" nowrap="true" valign="center" style="Display:inline;">
         <label>DropDown:</label>
      </td>
      <td nowrap="true" valign="center" style="Display:inline;">
         <select>
            <option selected >First Option</option>
            <option>Second Option</option>
            <option>Third Option</option>
         </select>
      </td>
      <td width="99%" class="ms-toolbar" nowrap="true">
      </td>
   </tr>
</table>

The Web Part uses the ms-toolbar class to render the correct gradient image and the correct font for a given theme.

To render the music chart section of the Web Part

Use the following HTML code:

<table cellSpacing=0 width="100%" class="UserGeneric">
<tr>
   <td class="ms-smallsectionline, ms-smallheader">
            Artist</td>
        <td class="ms-smallsectionline, ms-smallheader">
            Album</td>
        <td class="ms-smallsectionline, ms-smallheader">
            Genre</td>
        <td class="ms-smallsectionline, ms-smallheader">
            Year</td>
</tr>
<tr onmouseover="this.className = 'ms-HoverCellActive';" 
   onmousedown="this.className = 'ms-HoverCellActiveDark';" 
   onmouseout="this.className = 'ms-HoverCellInActive';"    
        cellpadding=0   
   class="ms-HoverCellInActive" 
   style="cursor: hand">
   <td class="ms-smallsectionline">
            U2</td>
        <td class="ms-smallsectionline">
            The Joshua Tree</td>
        <td class="ms-smallsectionline">
            Rock</td>
        <td class="ms-smallsectionline">
            1987</td>
</tr>
<tr onmouseover="this.className = 'ms-HoverCellActive';" 
   onmousedown="this.className = 'ms-HoverCellActiveDark';" 
   onmouseout="this.className = 'ms-HoverCellInActive';"    
   class="ms-HoverCellInActive" 
   style="cursor: hand">
   <td class="ms-smallsectionline">
            Cult</td>
        <td class="ms-smallsectionline">
            Love</td>
        <td class="ms-smallsectionline">
            Hard Rock</td>
        <td class="ms-smallsectionline">
            1986</td>
</tr>
<tr 
   class="ms-selectednav" 
   style="cursor: hand">
   <td>Cult</td><td>Love</td><td>Hard Rock</td><td>1986</td>
</tr>
</table>

The Web Part uses the ms-smallsectionline class to draw the gridlines, the ms-smallheader class for the header treatment, and the UserGeneric class to render padding. Additionally, the Web Part uses the ms-HoverCellInactive, ms-HoverCellActive, and ms-HoverCellActiveDark classes to render the hovering behavior and the ms-selectednav class to show the current selection.

To render the tabs and text area at the bottom of the Web Part

Use the following HTML code:

<table border="0" cellpadding="0" cellspacing="0" width="100%" class="UserSectionTitle"> 
   <tr>
      <td valign="top">
         <div width="100%" class="ms-WPBody"  >
            <span class="ms-tabselected" style="width:5px;height:5px;">
               <nobr>Active Tab</nobr>
            </span>
            <span style="width:3px;height:5px;"> </span>
            <span style="width:5px;height:25px;padding-top:2px;">
               <span class="ms-tabinactive" style="width:5px;height:5px;">
                  <nobr>Inactive Tab</nobr>
               </span>
            </span>
         </div>
      </td>
   </tr>
</table>
<div class="UserBackground UserGeneric">
   A basic panel with padding.
</div>
<div class="UserSectionFooter">
   Footer with top border.
</div>

The Web Part uses the ms-WPBody class to render basic text, the UserSectionTitle class to render a header with a bottom border, the UserSectionFooter class to render a footer with a top border, and the UserBackground class and the UserGeneric class to provide generic backgrounds and spacing. Additionally, the Web Part uses the ms-tabselected class and the ms-tabinactive class to render the tab treatment on the sample pages.

Customizing the Task Pane

You can also modify the default task pane to display additional links, images, or other tasks. The following example shows how to display icons next to the Web Parts in the Add Web Parts task pane as shown in the following image:

Figure 4. Web Part icons displayed in the Add Web Parts task pane

To display icons next to the Web Parts in the Add Web Parts task pane

Use code similar to the following to set the PartImageLarge property to point at the image file that you want to use:

this.PartImageLarge = "_WPR_/image.gif";

Alternatively, you can add a line similar to the following to specify the PartImageLarge property in the .dwp file for the Web Part:

<PartImageLarge>_WPR_/image.gif</PartImageLarge>

In this example, the Image.gif file is located in the class resources directory for the Web Part. For more information about Web Part class resources or about how to deploy Web Parts, see the Microsoft SharePoint Products and Technologies Software Development Kit (SDK) or Packaging and Deploying Web Parts for Microsoft Windows SharePoint Services.

Overriding and Customizing the Web Part Menu

If you are a Web Part author, you may need to override or customize the default Web Parts menu. This document briefly summarizes this process by using a hypothetical scenario based on C# that involves several property checks. For more information about the object model for the Web Part menu, see the Microsoft SharePoint Products and Technologies Software Development Kit (SDK).

To override the Web Parts menu

The following sample code overrides the CreateWebPartMenu() function to customize the menu.

public override void CreateWebPartMenu()
{
MenuItem ParentItem, Item1, Item2;

//first we create three menu items
//one as a parent item, and two submenu items

//create the parent item
ParentItem = new MenuItem("ParentItem", "", "ParentItemID");

//create a submenu item with a server event on click
Item1 = new MenuItem("Item1", "Item1ID", new EventHandler(EventHandlerForItem1));

//create a submenu item with a client event on click 
Item2 = new MenuItem("Item2", "javascript:alert('Item2 was clicked');", "Item2ID");

// We then add the submenu items to the parent item.

ParentItem.MenuItems.Add(Item1);
ParentItem.MenuItems.Add(Item2);

// We then decide that we'd like to add the parent item after the 
// "Edit Web Part Properties" item in the menu. 

// First we find the index of the "Edit" item
int EditIndex = 
   this.WebPartMenu.MenuItems.IndexOf(this.WebPartMenu.MenuItems.ItemFromID("MSOMenu_Edit"));

// Then we insert the parent item after the "Edit" item
this.WebPartMenu.MenuItems.Insert(EditIndex + 1, ParentItem); 

// Make sure the parent item has a separator above it
ParentItem.BeginSection = true;

// Check a custom property to decide whether to display the parent menu
if (this.CustomProperty1 == true)
{
ParentItem.Visible = true;
}
else
{
ParentItem.Visible = false;
}

// Check another custom property to decide which menu item to enable 
// within the parent item
if (this.CustomProperty2 == true)
{
Item1.Enabled=true;
Item2.Enabled=false;
}
else
{
Item1.Enabled=false;
Item2.Enabled=true;
}
}

Customizing Task Pane Views

There are several views in which a Web Part developer or Web Parts Page author can open the task pane. These views can modify Web Part properties, add Web Parts to the page, and open extensible views, among other things. To use these views, call the MSOTlPn_ShowToolPane(ViewID, WebPartID**)** function in JScript.

The MSOTlPn_ShowToolPane() function has one required parameter, and one optional parameter. The required parameter is ViewID, which is an integer. The following table shows the ViewID value for each view of the task pane.

Table 1. ViewID value for each view of the task pane

ViewID View of task pane to be displayed
-1 Extensible View
0 Close task pane
1 Web Part Properties and Custom ToolParts
2 Add Web Parts – Browse
3 Add Web Parts – Search
4 Navigation (Downlevel only)
5 Add Web Parts – Import
6 Web Part Menu (Downlevel only)
7 Error

For example, the following sample JScript call opens the Add Web Parts task pane in Import mode:

MSOTlPn_ShowToolPane(5);

The optional parameter is WebPartID, which is a globally unique identifier (GUID) for a Web Part on the page. You can use this parameter when the ViewID parameter is set to -1, 1, or 6. For example, the following sample JScript call opens the property sheet task pane for a Web Part:

MSOTlPn_ShowToolPane(1, <GUID>);

In addition to passing basic parameters into the MSOTlPn_ShowToolPane() function, you can use the MSOGallery_SelectedLibrary form field to make the Add Web Parts – Browse task pane point at a specific Web Part gallery. When you set this field to an integer value from 1 to 4, the corresponding gallery is selected when the task pane opens. The following table shows the corresponding gallery for each of the MSOGallery_SelectedLibrary field values.

Table 2. MSOGallery_SelectedLibrary field values

MSOGallery_SelectedLibrary Selected Web Part Gallery
1 Site_name Gallery
2 Online Gallery
3 Web Parts Page Gallery
4 Virtual Server Gallery

For example, to open the Online Gallery, use the following lines of code:

MSOGallery_SelectedLibrary=2;
MSOTlPn_ShowToolPane(2);

To further specify the Web Parts that are displayed in the Add Web Parts – Browse task pane, use the filter string. When you set the MSOGallery_FilterString field to a specific string, the task pane uses that string to filter the Group field in the Team Web Site Gallery. For example, to display only the "Finance Web Parts" group in the Team Web Site Gallery, use the following lines of code:

MSOGallery_SelectedLibrary=1;
MSOGallery_FilterString="Finance Web Parts";
MSOTlPn_ShowToolPane(2); 

Note   This functionality only works with the Site_name Gallery.

Conclusion

Web Part Page authors and Web Part developers have many different options for customizing the user interface in Windows SharePoint Services. While many of these options are available through the browser, you must have access to the server to perform some customization tasks, and many more customization tasks require executing code on the server. With the various UI customizations in Windows SharePoint Services, Web Part developers and solution developers can effectively and easily brand their sites and achieve their desired look.