How to: Customize Page Editing Toolbar Components

  • Article

The Page Editing toolbar is a panel of user interface (UI) elements that provide page information and ways to interact with the page. This topic demonstrates two ways to modify the Page Editing Toolbar. You can:

  • Modify the XML data source files.

  • Create a custom server control and then reference a custom XML file in your control.

The Page Editing toolbar is divided into three main areas, or UI controls.

UI Control Description

Page Status bar

Provides information about the current version of the page. Examples include Version information and the page's Status.

Page Editing menu

Enables a user to interact with the page by performing such actions as publishing a version, approving a pending version, and checking in the page to share a draft.

Quick Access buttons

Makes available the most popular actions, given the page status and context.

Both the Page Editing menu and the Quick Access buttons separate the data source from the UI control, and you can modify the data source and the UI control independently.

Modify XML Data Source Files

The EditingMenu.xml and QuickAccess.xml files are the XML data sources for the Page Editing menu and Quick Access buttons, respectively. Data sources specified in XML files drive the configuration and behavior of the menu items on the Page Editing menu and the actions that are associated with the Quick Access buttons. In this example, we create an object that overrides the ConsoleAction class and modify the CustomQuickAccess.xml file to add a new button to the Page Editing toolbar. After following the procedure, a new button appears on the Page Editing toolbar that, when clicked, allows users with the appropriate permissions to cancel another user's Checked Out status on a specified page.

Caution   For compatibility reasons, do not change the contents of EditingMenu.xml and QuickAccess.xml files. To customize the actions and items that these files control, edit the CustomEditingMenu.xml and CustomQuickAccess.xml files, found in the Editing Menu folder in the Master Page gallery, instead.

Note

You can also apply the customizations described here to the Quick Access button and Site Actions menus.

To create a custom server control that can change the configuration of the Quick Access buttons

  1. Open Microsoft Visual Studio.

  2. On the File menu, click New and click ASP.NET Web Site.

  3. Create a new project.

  4. Copy and paste the following code into a .cs file in the project.

    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;
namespace PageEditingToolbarMenuItemControls
{
    /// <remarks>
    /// Adds to the Quick Access toolbar a button that checks in
    /// a document that is checked out by another user.
    /// </remarks>
    public sealed class DiscardOtherUserCheckoutAction : ConsoleAction
    {
        /// <summary>
        /// This is the constructor of the specific ConsoleAction
        /// </summary>
        public DiscardOtherUserCheckoutAction() : base()
        {
            this.DisplayText = "Discard Other User's Checkout";
        }
        /// <summary>
        /// SPBasePermissions are required to use this Action.
        /// </summary>
        /// <value></value>
        public override SPBasePermissions UserRights
        {
            get { return SPBasePermissions.CancelCheckout; }
        }
        /// <summary>
        /// Checks for 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 URL for this control 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>
        /// Specifies the URL for this Action.
        /// </summary>
        /// <value></value>
        public override string href
        {
            get
            {
                return "javascript:" + Page.ClientScript.GetPostBackEventReference(this, DiscardOtherUserCheckoutAction.DiscardCheckOutPostBackEventArgument);
            }
        }
       private const string DiscardCheckOutPostBackEventArgument = "discardUserCheckout";
    }
}

  5. Save changes.

  6. Build the project as a new assembly, register the assembly with the general assembly cache, and add a new <SafeControl> entry in your web.config file that corresponds to the assembly and the namespace of your custom control (PageEditingToolbarMenuItemControls).

  7. Restart Internet Information Services (IIS).

  8. Navigate to the \Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\EditingMenu folder.

  9. Copy and paste the QuickAccess.xml file and then rename the duplicate to CustomQuickAccess.xml.

  10. Edit CustomQuickAccess.xml and replace its content with the following markup:

    <Console>
  <references>
  ///The following tag must refer to the assembly you created
  ///and compiled in step 3.
    <reference TagPrefix="demo" assembly="WebControlLibrary1, Version=1.0.11.876, Culture=neutral, PublicKeyToken=b3795d44e71a79a4" namespace="PageEditingToolbarMenuItemControls" /> 
  </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>

  11. Save and close CustomQuickAccess.xml.

Create a Custom Server Control and Reference XML File

You can programmatically extend the contents of the CustomEditingMenu.xml file and override the settings contained in its parent EditingMenu.xml file. The markup included in the following procedure includes sample code for a CustomEditingMenu.xml file that adds a new Links menu with two new items, as well as a View Pages gallery and a View Master Page gallery, to the Page Editing menu.

You can modify the Page Editing menu and the Quick Access buttons by creating a custom Web server control. The code sample below demonstrates how to create a custom server control that reverts a checked-out document to a checked-in state.

You can change the UI configuration of the Page Editing toolbar or the Quick Access buttons by modifying the XML data source directly or by writing and deploying a custom server control. However, if the XML data sources are customized and a custom server control is running, the custom server control always takes precedence and overrides the XML data sources.

To modify the XML data source and change the Page Editing toolbar UI configuration

  1. Open an XML editor.

  2. Navigate to the \Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\LAYOUTS\EditingMenu folder.

  3. Copy and paste the EditingMenu.xml and QuickAccess.xml files to create duplicates. Rename the duplicates to CustomEditingMenu.xml and CustomQuickAccess.xml.

  4. Copy and paste the following code into the CustomEditingMenu.xml and CustomQuickAccess.xml files.

    <?xml version="1.0" encoding="utf-8" ?> 
<Console>
  <references>
    <reference TagPrefix="cms" assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral,
      PublicKeyToken=93de0004b6e3fcc5" 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>

  5. Modify key elements in the sample code. The following table presents a sample of key elements and attributes in the sample XML file.

    Tag Description

    References

    Contains the assemblies references in the ConsoleNode section. You can add your assemblies for your customized actions to the menu.

    Note

    In the code sample, the <references> tag is optional. Set this parameter to True if you want to support localization. Also, the <references> tag must be present with a PublicKeyToken attribute that matches the build of the application that you are currently using.

    ConsoleNode

    Contains the menu items of the Page Editing menu. Each menu can contain the DisplayText property, UserRights property, RequiredRightsMode property, and PermissionContext enumeration in which the menu is visible. The menu may be an action that is mapped to a server control in the assembly or may be a URL.

    You can also replace or delete existing entries by specifying the existing node ID.

    Structure

    Indicates the menu structure.

  6. Use a Boolean expression to configure optional bit mask attributes. Each ConsoleNode has two optional bit mask attributes that you can set to control conditions such as when and where the ConsoleNode appears to the user.

    Type Attribute name Description

    Context

    RequiredStates

    The required state of the page or the editing mode before the node is enabled or disabled. Examples of states include InEditModeTrue, InEditModeFalse, and IsCheckedOutToCurrentUserTrue.

    User Rights

    UserRights

    Responsible for trimming access to the ConsoleNode based on Windows SharePoint Services permissions.

    This example Boolean expression, UserRights="BrowseDirectories|ManageLists, allows users with BrowseDirectories or ManageLists permissions to access the ConsoleNode.

  7. Save the CustomEditingMenu.xml file.