Customizing Page Editing Toolbar Components in SharePoint Server 2007

  • Article

Summary: Learn how to customize the Page Editing menu and the Quick Access buttons of the Page Editing toolbar in Microsoft Office SharePoint Server 2007.

Office Visual How To

Applies to: 2007 Microsoft Office System, Microsoft Office SharePoint Server 2007, Microsoft SharePoint Designer 2007

Joel Krist, Akona Systems

February 2008

Overview

The Page Editing toolbar is a panel of user interface (UI) elements that provide page information and ways to interact with pages. The Page Editing toolbar plays an important role in the publishing cycle of site pages, offering content authors status information about the current page, menus for interacting with the page, and quick access buttons for the most popular actions given the page status and context. As with most of the Web content management–related features of Microsoft Office SharePoint Server 2007, the Page Editing toolbar can be extended and customized. This Office Visual How To shows how you can customizeing the Page Editing menu and the Quick Access buttons of the Page Editing toolbar in Microsoft Office SharePoint Server 2007.

 See It Customizing Page Editing Toolbar Components

Watch the Video

Length: 11:13 | Size: 14.6 MB | Type: WMV file

Code It | Read It | Explore It

Code It

Download the Code Sample

Both the Page Editing menu and the Quick Access buttons implementations are based on the idea of separating the UI portion of the component from its data source. This allows the component to be customized by modifying the data source and the UI control independently. To illustrate both approaches this Office Visual How To uses the following two scenarios:

  1. Adding a custom Page Editing menu to the Page Editing toolbar by using Microsoft Office SharePoint Designer 2007 to modify the XML data source of the Page Editing menu.

  2. Adding a button to the Page Editing toolbar Quick Access buttons by using Microsoft Visual Studio 2005 to create an assembly that contains the implementation of a class derived from the SharePoint ConsoleAction class.

Adding a Custom Page Editing Menu to the Page Editing Toolbar

The Page Editing menu on the Page Editing toolbar configures itself based on the contents of two XML files: EditingMenu.xml and CustomEditingMenu.xml. EditingMenu.xml contains the default configuration of the Page Editing menu and is located in the following folder:

%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\EditingMenu

CustomEditingMenu.xml is the Page Editing menu configuration file that is provided to customize the default Page Editing menu configuration. CustomEditingMenu.xml is located in the Editing Menu folder under the Master Page Gallery. The Page Editing menu first reads the default EditingMenu.xml file and then reads the custom CustomEditingMenu.xml file to apply incremental customizations.

Note

Do not modify the default EditingMenu.xml file. Doing so will break compatibility with future releases of Office SharePoint Server. Edit the contents of CustomEditingMenu.xml.

To add a custom menu to the Page Editing menu of the Page Editing toolbar

  1. Start Office SharePoint Designer 2007.

  2. On the File menu, click Open Site.

  3. In the Open Site dialog box, enter the URL of the SharePoint site, and then click Open. SharePoint Designer displays the contents of the site.

  4. Locate the CustomEditingMenu.xml file in the SharePoint Designer Folder List. The CustomEditingMenu.xml file is located in the Editing Menu folder under the Master Page Gallery folder in the Folder List.

    Figure 1. Locating CustomEditingMenu.xml

    Locating CustomEditingMenu.xml

  5. Edit the contents of the CustomEditingMenu.xml file: Double-click the file in the SharePoint Designer Folder List. SharePoint Designer prompts that the file is under source control and asks for confirmation before checking it out. Click Yes to check out the file. SharePoint Designer checks out the file and opens it for editing.

  6. Replace the contents of CustomEditingMenu.xml with the following markup:

    <?xml version="1.0" encoding="utf-8" ?>
<Console>
  <references>
    <reference TagPrefix="cms"
    assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0,
    Culture=neutral, PublicKeyToken=71e9bce111e9429c"
    namespace=
    "Microsoft.SharePoint.Publishing.WebControls.EditingMenuActions" />
  </references>
  <structure>
    <ConsoleNode ConfigMenu="Add" Sequence="600"
      href="javascript:" AccessKey="L" DisplayText="Links" 
      UserRights="EmptyMask" UseResourceFile="false" 
      RequiredStates="InSharedView" ID="LinksMenu" >
      <ConsoleNode 
        DisplayText="View Pages Library"
        UseResourceFile="false"
        ImageUrl="/_layouts/images/ActionsSettings.gif"
        UserRights="BrowseDirectories|ManageLists"  
        RequiredRightsMode="Any"
        PermissionContext="CurrentSite"
        IsSiteRelative="true"  
        href="Pages/forms/allitems.aspx"  
        ChangedNodeID="ViewPagesList">             
      </ConsoleNode>
      <ConsoleNode IsSeparatorImage="True" UserRights="EmptyMask" />
      <ConsoleNode 
        DisplayText="View Master Page Gallery" 
        UseResourceFile="false" 
        ImageUrl="/_layouts/images/ActionsSettings.gif"
        UserRights="BrowseDirectories|ManageLists"  
        RequiredRightsMode="Any"
        PermissionContext="CurrentSite"
        IsSiteRelative="false"  
        href="/_catalogs/masterpage/Forms/AllItems.aspx" 
        ChangedNodeID="ViewPagesLibSettings">
      </ConsoleNode>
    </ConsoleNode>
  </structure>       
</Console>

  7. Save the changes to the CustomEditingMenu.xml file.

The markup shown above adds a menu item named Links to the Page Editing menu. The Links menu item contains two menu items, View Pages Library and View Master Page Gallery. You can click on the menu items to navigate to the Pages library and the Master Page Gallery.

Figure 2. Custom Page Editing menu

Custom Page Editing menu

Adding a Quick Access Button to the Page Editing Toolbar

The following sections show how to add a Quick Access button to the Page Editing toolbar that can be used to cancel another user's Checked Out status on a specified page. The process includes five steps:

  1. Creating a Class Library project in Visual Studio 2005.

  2. Adding references to the required assemblies to the Visual Studio project.

  3. Signing the class library assembly with a strong name.

  4. Implementing the Quick Access toolbar button.

  5. Deploying the Quick Access toolbar button.

Creating a Class Library Project in Visual Studio 2005

The first step is to create a Class Library project.

To create a Class Library project in Visual Studio 2005

  1. Start Visual Studio.

  2. On the File menu, click New, and then click Project.

  3. In the New Project dialog box, on the Project Types pane, select Visual C# or Visual Basic, and then select the Windows category.

  4. In the Templates pane, select Class Library.

  5. Type PageEditingToolbarControls for the Name of the project.

  6. Specify a Location for the project, and then click OK. Visual Studio generates a Class Library project with a single source file in it called Class1.cs or Class1.vb, depending on the language selected in Step 3 above.

  7. Rename the Class1.cs or Class1.vb source file to DiscardOtherUserCheckoutAction.cs or DiscardOtherUserCheckoutAction.vb, depending on the language being used, by right-clicking the file in the Visual Studio Solution Explorer and choosing Rename.

Adding References to the Required Assemblies

The class that implements the Quick Access button is derived from the Microsoft.SharePoint.Publishing.WebControls.EditingMenuActions.ConsoleAction class and also uses other SharePoint objects. To use these objects, you must add references to the necessary SharePoint assemblies.

To add the necessary SharePoint references on a computer running Office SharePoint Server 2007

  1. In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Add Reference.

  2. In the Add Reference dialog box, on the .NET tab, click Microsoft.SharePoint.Publishing.dll.

  3. Select Microsoft.SharePoint.dll and Microsoft.SharePoint.Publishing.dll. To select more than one file at a time, hold down the Ctrl key while selecting the files with the mouse.

  4. Click OK.

If Visual Studio is running on a computer that does not have Office SharePoint Server 2007 installed, the required SharePoint assemblies are not available from the .NET tab of the Visual Studio Add Reference dialog box. In this case, you can copy the assemblies from a computer that has Office SharePoint Server 2007 installed on it to a local project folder on the development computer. The assembly files needed to create the Quick Access toolbar button shown below are Microsoft.SharePoint.dll and Microsoft.SharePoint.Publishing.dll. By default, these assemblies are located in the following folder on a computer that has Office SharePoint Server 2007 installed:

%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\ISAPI

After you make local copies of the assemblies, you can add references to them by browsing for the local files.

To add references to local copies of the assemblies

  1. In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Add Reference.

  2. In the Add Reference dialog box, on the Browse tab, navigate to the local folder containing the copies of the SharePoint assemblies.

  3. Select the Microsoft.SharePoint.dll and Microsoft.SharePoint.Publishing.dll files. To select more than one file at a time, hold down the Ctrl key while selecting the files with the mouse.

  4. Click OK.

To use the code in the Implementing the Quick Access Toolbar Button section, add a reference to the System.Web assembly to the project.

To add a reference to System.Web

  1. In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Add Reference.

  2. In the Add Reference dialog box, on the .NET tab, select System.Web.dll.

  3. Click OK.

Signing the Class Library Assembly with a Strong Name

To install the class library assembly into the Global Assembly Cache on the server running Office SharePoint server, it must be signed with a strong name. A strong name consists of the assembly's identity—the simple text name of the assembly, the version number, and culture information (if provided)—plus a public key and a digital signature.

To assign a strong name to the class library assembly in Visual Studio

  1. In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Properties.

  2. On the project properties page, on the Signing tab, select the Sign the Assembly check box.

  3. In the Choose a Strong Name Key file list, click New.

  4. In the Create Strong Name Key dialog box, enter a key file name, and then clear the Protect my key file with a password check box.

  5. Close the project properties page.

Implementing the Quick Access Toolbar Button

After adding the references to the required assemblies and signing the class library assembly, the next step is to create the class that provides the implementation of the Quick Access toolbar button.

To implement the Quick Access toolbar button

  1. Add the following Imports or using statements to the top of the DiscardOtherUserCheckoutAction.cs or DiscardOtherUserCheckoutAction.vb source file, replacing any Imports or using statements generated by Visual Studio when the project was created.

    Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Text
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports Microsoft.SharePoint.Publishing
Imports Microsoft.SharePoint.Publishing.WebControls.EditingMenuActions
Imports Microsoft.SharePoint.Publishing.WebControls
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Utilities

    using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Text;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using Microsoft.SharePoint.Publishing;
using Microsoft.SharePoint.Publishing.WebControls.EditingMenuActions;
using Microsoft.SharePoint.Publishing.WebControls;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;

    The Imports and using statements make it possible to use the classes and types defined in the referenced namespaces without using fully qualified namespace paths.

  2. Replace DiscardOtherUserCheckoutAction class definition generated by Visual Studio with the following:

    Public NotInheritable Class DiscardOtherUserCheckoutAction
    Inherits ConsoleAction

    ''' <summary>
    ''' Returns the permissions required to use this Action.
    ''' </summary>
    ''' <value></value>
    Public Overrides ReadOnly Property UserRights() As _
        Microsoft.SharePoint.SPBasePermissions
        Get
            Return SPBasePermissions.CancelCheckout
        End Get
    End Property

    ''' <summary>
    ''' Returns the AuthoringStates required for the button to
    ''' be enabled.
    ''' </summary>
    ''' <value></value>
    Public Overrides ReadOnly Property RequiredStates() As _
        AuthoringStates
        Get
            Return AuthoringStates.CheckedOutVersionExistsTrue Or _
                AuthoringStates.IsCheckedOutToCurrentUserFalse Or _
                AuthoringStates.IsDocLibListItemTrue
        End Get
    End Property

    ''' <summary>
    ''' Defines the PostBack behavior when the button is clicked.
    ''' </summary>
    ''' <param name="eventArgument"></param>
    Public Overrides Sub RaisePostBackEvent( _
        ByVal eventArgument As String)
        If eventArgument = _
DiscardOtherUserCheckoutAction.DiscardCheckOutPostBackEventArgument _
        Then
            Try
                Dim myFile As SPFile = SPContext.Current.File
                myFile.UndoCheckOut()
            Catch e As SPException
                Dim actionsNode As ConsoleNode = New ConsoleNode()
                Dim exitNoSaveNode As ConsoleNode = _
                    New ConsoleNode(actionsNode)

                exitNoSaveNode.Action = New ExitWithoutSavingAction()
                exitNoSaveNode.Action.ID = _
                    "checkOutDiscardErrorActionExitNoSave"
                actionsNode.ChildConsoleNodes.Add(exitNoSaveNode)
                Me.ShowError(e, New ConsoleError(e.Message, _
                    actionsNode))
            Finally
                SPUtility.Redirect( _
                    SPContext.Current.ListItemServerRelativeUrl, _
                    SPRedirectFlags.Default, Context)
            End Try
        End If
    End Sub

    ''' <summary>
    ''' Returns the URL for this Action.
    ''' </summary>
    ''' <value></value>
    Public Overrides Property href() As String
        Get
            Return "javascript:" + _
                Page.ClientScript.GetPostBackEventReference(Me, _
DiscardOtherUserCheckoutAction.DiscardCheckOutPostBackEventArgument)
        End Get
        Set(ByVal value As String)
            MyBase.href = value
        End Set
    End Property

    Private Const DiscardCheckOutPostBackEventArgument As String = _
        "discardUserCheckout"

End Class

    public sealed class DiscardOtherUserCheckoutAction : ConsoleAction
{
    /// <summary>
    /// The constructor for this ConsoleAction.
    /// </summary>
    public DiscardOtherUserCheckoutAction() : base()
    {
        this.DisplayText = "Discard Other User's Checkout";
    }
    /// <summary>
    /// Returns the permissions required to use this Action.
    /// </summary>
    /// <value></value>
    public override SPBasePermissions UserRights
    {
        get { return SPBasePermissions.CancelCheckout; }
    }
    /// <summary>
    /// Returns the AuthoringStates required for the button to be
    /// enabled.
    /// </summary>
    /// <value></value>
    public override AuthoringStates RequiredStates
    {
        get
        {
            return AuthoringStates.CheckedOutVersionExistsTrue |
                AuthoringStates.IsCheckedOutToCurrentUserFalse | 
                AuthoringStates.IsDocLibListItemTrue;
        }
    }
    /// <summary>
    /// Defines the PostBack behavior when the button is clicked.
    /// </summary>
    /// <param name="eventArgument"></param>
    public override void RaisePostBackEvent(string eventArgument)
    {
        if (eventArgument == 
DiscardOtherUserCheckoutAction.DiscardCheckOutPostBackEventArgument)
        {
            try
            {
                SPFile myFile = SPContext.Current.File;
                myFile.UndoCheckOut();
            }
            catch (SPException e)
            {
                ConsoleNode actionsNode = new ConsoleNode();
                ConsoleNode exitNoSaveNode =
                    new ConsoleNode(actionsNode);
                exitNoSaveNode.Action = new ExitWithoutSavingAction();
                exitNoSaveNode.Action.ID = 
                    "checkOutDiscardErrorActionExitNoSave";
                actionsNode.ChildConsoleNodes.Add(exitNoSaveNode);
                this.ShowError(
                    e, new ConsoleError(e.Message, actionsNode));
            }
            finally
            {
                SPUtility.Redirect(
                    SPContext.Current.ListItemServerRelativeUrl,
                    SPRedirectFlags.Default, Context);
            }
        }
    }
    /// <summary>
    /// Returns the URL for this Action.
    /// </summary>
    /// <value></value>
    public override string href
    {
        get
        {
            return "javascript:" + 
                Page.ClientScript.GetPostBackEventReference(this,
DiscardOtherUserCheckoutAction.DiscardCheckOutPostBackEventArgument);
        }
        set
        {
            base.href = value;
        }
    }

    private const string DiscardCheckOutPostBackEventArgument =
        "discardUserCheckout";
}

  3. Build the class library project.

Deploying the Quick Access Toolbar Button

The Page Editing toolbar configures Quick Access buttons based on the contents of two XML files: QuickAccess.xml and CustomQuickAccess.xml. QuickAccess.xml contains the default Quick Access button configuration of the Page Editing toolbar and is located in the following folder:

%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\EditingMenu

You can customize the default Quick Access button configuration through the CustomQuickAccess.xml Quick Access button configuration file. CustomQuickAccess.xml is located in the Editing Menu folder under the Master Page Gallery. The Page Editing toolbar first reads the default QuickAccess.xml file and then reads the custom CustomQuickAccess.xml file to apply incremental customizations.

Note

Do not modify the default QuickAccess.xml file. Doing so will break compatibility with future releases of Office SharePoint Server. Edit the contents of the CustomQuickAccess.xml file.

To modify the CustomQuickAccess.xml file to add the Quick Access button to the Page Editing toolbar

  1. Start Office SharePoint Designer 2007.

  2. From within SharePoint Designer, on the File menu, click Open Site.

  3. In the Open Site dialog box, type the URL of the SharePoint site, and then click Open. SharePoint Designer displays the contents of the site.

  4. Locate the CustomQuickAccess.xml file in the SharePoint Designer Folder List. The CustomQuickAccess.xml file is located in the Editing Menu folder under the Master Page Gallery folder in the Folder List.

    Figure 3. Locating CustomQuickAccess.xml

    Locating CustomQuickAccess.xml

  5. Double-click the file in the SharePoint Designer Folder List to edit the contents of the CustomQuickAccess.xml file. SharePoint Designer prompts that the file is under source control and asks for confirmation before checking it out. Click Yes to check out the file. SharePoint Designer checks out the file and opens it for editing.

  6. Replace the contents of the CustomQuickAccess.xml with the following markup:

    <Console>
  <references>
    <reference TagPrefix="demo"
      assembly="PageEditingToolbarControls, Version=1.0.0.0,
        Culture=neutral, PublicKeyToken=Public Key Token"
        namespace="PageEditingToolbarControls" /> 
  </references>
  <structure>
    <ConsoleNode Action="demo:DiscardOtherUserCheckoutAction"
      DisplayText="Discard Checkout" ConfigMenu="Add"
      UseResourceFile="false" Sequence="1700" RequiredRightsMode="Any"
      ImageUrl="/_layouts/images/ActionsSettings.gif" 
      ID="DiscardCheckedout" />
  </structure>
</Console>

  7. The markup shown above uses the placeholder text Public Key Token as the value of the Quick Access button assembly public key token. Replace the placeholder text with the actual public key token for the class library assembly. To determine the public key token, open a Visual Studio Command window, navigate to the folder containing the assembly, and run the strong name tool, sn.exe, with the -T option against the assembly. For example:

    sn -T PageEditingToolbarControls.dll

    Note

    Uppercase T must be specified for the sn.exe option.

  8. Save the changes to the CustomQuickAccess.xml file.

The next step in the deployment process is adding the Quick Access button assembly to the Global Assembly Cache (GAC). There are two ways to do this, depending on whether the computer running Visual Studio has Office SharePoint Server 2007 installed.

Adding the Quick Access button assembly to the GAC on a computer running Office SharePoint Server 2007

  1. Open a Visual Studio Command window and navigate to the folder containing the assembly.

  2. Run the GAC utility, gacutil.exe, with the /i option against the assembly. For example:

    gacutil /i PageEditingToolbarControls.dll

Adding the Quick Access button assembly to the GAC on a computer that is not running Office SharePoint Server 2007

  1. Copy the PageEditingToolbarControls.dll assembly to a folder on the computer running Office SharePoint Server.

  2. From the computer running Office SharePoint Server, open an instance of Windows Explorer and navigate to the folder containing the PageEditingToolbarControls.dll assembly that you copied in Step 1.

  3. Drag the PageEditingToolbarControls.dll into the %windir%\Assembly folder.

The final step in the deployment process is to add the DiscardOtherUserCheckoutAction class to the list of safe controls on the computer running Office SharePoint Server.

To add the DiscardOtherUserCheckoutAction class to the list of safe controls

  1. Locate and open the web.config file for the SharePoint site.

  2. Add the following entry to the <SafeControls> section of the web.config file, replacing the Public Key Token placeholder text with the actual public key token for the Quick Access button assembly:

    <SafeControl Assembly="PageEditingToolbarControls, Version=1.0.0.0,
  Culture=neutral, PublicKeyToken=Public Key Token"
  Namespace="PageEditingToolbarControls"
  TypeName="DiscardOtherUserCheckoutAction" Safe="True" />

  3. To pick up the changes to the web.config file, restart IIS.

You can test the Quick Access button assembly after it is deployed to the computer running Office SharePoint Server.

You can display the Discard Checkout Quick Access button on the Page Editing toolbar. To do this, connect to the SharePoint site as a user with permissions to cancel checkouts, and then display the Page Editing toolbar on a page that is currently checked out to another user. You can undo the page checkout by clicking the Discard Checkout Quick Access button.

Figure 4. Discard Checkout Quick Access Button

Discard Checkout Quick Access button

Read It

This article explores how to customize the Page Editing menu and the Quick Access buttons of the Page Editing toolbar in Microsoft Office SharePoint Server 2007. To customize the Page Editing menu, the CustomEditingMenu.xml file was modified by using SharePoint Designer. To add a Discard Checkout button to the Quick Access buttons, the following steps were performed:

  1. Creating a Class Library project in Visual Studio 2005.

  2. Adding references to the required assemblies to the Visual Studio project.

  3. Signing the class library assembly with a strong name.

  4. Implementing the Quick Access toolbar button.

  5. Deploying the Quick Access toolbar button.

Explore It