Customizing Page Editing Toolbar Components in SharePoint Server 2007
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.
Applies to: 2007 Microsoft Office System, Microsoft Office SharePoint Server 2007, Microsoft SharePoint Designer 2007
Joel Krist, Akona Systems
February 2008
Code It | Read It | Explore It
Code It
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:
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.
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
Start Office SharePoint Designer 2007.
On the File menu, click Open Site.
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.
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
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.
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>
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
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:
Creating a Class Library project in Visual Studio 2005.
Adding references to the required assemblies to the Visual Studio project.
Signing the class library assembly with a strong name.
Implementing the Quick Access toolbar button.
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
Start Visual Studio.
On the File menu, click New, and then click Project.
In the New Project dialog box, on the Project Types pane, select Visual C# or Visual Basic, and then select the Windows category.
In the Templates pane, select Class Library.
Type PageEditingToolbarControls for the Name of the project.
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.
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
In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Add Reference.
In the Add Reference dialog box, on the .NET tab, click Microsoft.SharePoint.Publishing.dll.
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.
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
In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Add Reference.
In the Add Reference dialog box, on the Browse tab, navigate to the local folder containing the copies of the SharePoint assemblies.
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.
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
In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Add Reference.
In the Add Reference dialog box, on the .NET tab, select System.Web.dll.
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
In the Visual Studio Solution Explorer, right-click the PageEditingToolbarControls project, and then click Properties.
On the project properties page, on the Signing tab, select the Sign the Assembly check box.
In the Choose a Strong Name Key file list, click New.
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.
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
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.
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"; }
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
Start Office SharePoint Designer 2007.
From within SharePoint Designer, on the File menu, click Open Site.
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.
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
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.
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>
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.
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
Open a Visual Studio Command window and navigate to the folder containing the assembly.
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
Copy the PageEditingToolbarControls.dll assembly to a folder on the computer running Office SharePoint Server.
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.
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
Locate and open the web.config file for the SharePoint site.
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" />
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
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:
Creating a Class Library project in Visual Studio 2005.
Adding references to the required assemblies to the Visual Studio project.
Signing the class library assembly with a strong name.
Implementing the Quick Access toolbar button.
Deploying the Quick Access toolbar button.