How to: Customize Page Editing Toolbar Components

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 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 NavigateUrl
        {
            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"
      NavigateUrl="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"  
        NavigateUrl="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"  
        NavigateUrl="/_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 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.

Tags :


Community Content

Andrew Connell [MVP]
Documentation is misleading... here's the corrections...

If you follow these steps explicitly, it won't work. 

Under the section To create a custom server control that can change the configuration of the Quick Access buttons, steps 9-11 say to create the CustomQuickAccess.XML file and save it with your changes. That implies the file should reside in the same directory as the QuickAccess.xml file. Using the out-of-the-box Publishing Portal template, that won't work. This is because an actual CustomQuickAccess.XML file was created when the site was created within the Editing Menu folder in the Master Page Gallery. This is the file that the Page Editing Toolbar will examine to add custom buttons. The same applies for the Page Editing menu (not just the Quick Access buttons).

Therefore, don't save your changes in a new file. Take the changes and apply them to the CustomQuickAccess.XML file within the Editing Menu in the Master Page Gallery.

The documentation seems to imply this further up on the same page under the Caution note in the Modify XML Data Source Files section.

-AC, MVP MOSS [www.andrewconnell.com/blog]

Tags :

Wes Hackett
Using the XmlConsoleDataSource with a custom xml and control

The Publishing Console Menus use javascript postbacks to invoke the underlying actions. Faced with a requirement to have the same functions available without javascript the obvious solution was to replace the menus with accessible html and command buttons. (Not as visually appealing but thats not the point ;) )

At this point you can choose to follow the above and hide the OOB and replace them with your own custom actions or create a brand new xml file.

The files can be located in two locations:

(install location)12\Template\Layouts\EditingMenu

Or in the masterpage gallery under the Editing Menu sub folder

The format of the xml file follows the expected format above.

In order to invoke your custom action manifest in a control you will need to use the XmlConsoleDataSource control http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.publishing.webcontrols.xmlconsoledatasource.aspx

This is the same way the publishing features manipulate the SiteActions menu.

In the OnLoad event of your control include the following code:

XmlConsoleDataSource myDataSource;

myDataSource = new XmlConsoleDataSource();
myDataSource.ConfigurationProvider = "WesQuickAccess";
myDataSource.IsBuiltInConfiguration = true;

myDataSource.Page = this.Page;
Controls.Add(myDataSource);
myDataSource.ForceInitLoad(e);

IHierarchicalEnumerable myHE = myDataSource.GetHierarchicalView("").Select();

This then gives you access to a trimmed collection of ConsoleNode's and their Action

One thing to note is the importance of calling ForceInitLoad(e) as the data select will return nothing until its called.

From here you have an enumerable and can use the data how you see fit, in my case to create command buttons to call the action.

Wes

Tags :

lwatzon
Cannot find reference
Not sure what version of MOSS is used in the example, but the Assembly reference is wrong for our version.

<references>
<reference TagPrefix="cms" assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" namespace="Microsoft.SharePoint.Publishing.WebControls.EditingMenuActions" />
</references>

And as Andrew Connell said above, you can simply edit the xml files that are stored in the MasterPage gallery.

:)
Tags :

Page view tracker