Custom Ribbon Buttons

Date: 14.11.2012

SharePoint ribbon buttons provide a simple and effective way to enhance usability, as contextual functionality can be placed and grouped dynamically in one place.

MatchPoint 3.1 supports the definition of contextual ribbon buttons on the following Web Parts: all Form based Web Parts (Form Web Part, Workspace Editor Web Part), Data Grid Web Part and Composite Web Part.

The following post explains how to set up a contextual ribbon button on a Data Grid Web Part. The business case is quite simple: Archiving and restoring a workspace. The archiving functionality is callable through the MatchPoint API (Workspace.Archive(bool deleteFromWorkspaceList)) and does the following:

On the workspace web, a hidden archiving document library is created (called MatchPoint Workspace Archive) where the workspace redirector item is copied to. The workspace is set to readonly, meaning that no more editing is possible until the workspace is restored. The redirector item on the workspace list can either be deleted or not. The Workspace.Restore() function restores the workspace, setting Workspace.ReadOnly to false and copying the redirector item back to the workspace list.

The following two screenshots show a small preview on the result of our work:

Defining a User Control Configuration

What we need for this scenario in the background is a User Control Configuration where we put some custom MatchPoint code for archiving and restoring workspaces.

A User Control Configuration is a new configuration type introduced with MatchPoint 3.1 which integrates custom ASP.NET user controls into the MatchPoint framework - it will be explained in a separate post in detail. For this example it is important to know that every User Control Configuration is "exposed" as an expression variable. E.g. having a UserControlConfiguration called 'Helper.xml' provides a new expression variable Helper having all public properties and methods available that are defined in the user control.

Here is the code for this sample:

<%@ Control Language='C#' AutoEventWireup='true' %>
<%@ Assembly Name="Colygon.MatchPoint, Version=3.0.0.0, Culture=neutral, PublicKeyToken=c1901c20b4a53672" %>
<%@ Import Namespace="Colygon.MatchPoint.Core.Expressions" %>
<%@ Import Namespace="Colygon.MatchPoint.Core" %>
<%@ Import Namespace="Colygon.MatchPoint.Workspaces.Model" %>

<script runat='server' language='C#'>

  [ClientCallable]
  public void Archive(string url, bool deleteRedirectorItem)
  {
    using(new MPInstanceScope(new MPInstance(url)))
    {
      using (Workspace ws = new Workspace(url))
      {
        ws.Archive(deleteRedirectorItem);
      }
    }
  }

  public void Restore(string url)
  {
    using(new MPInstanceScope(new MPInstance(url)))
    {
      using (Workspace ws = new Workspace(url))
      {
        ws.Restore();
      }
    }
  }
</script>

We call this configuration 'WorkspaceHelper.xml'. In the expression console, there is a new expression variable called WorkspaceHelper where we can call the two methods Archive() and Restore(). The Archive() method has a boolean parameter indicating whether to delete the redirector item or not. We will see later in this post how to pass a javascript variable to this method call. This is also the reason why we give this method the ClientCallable attribute.

The ClientCallable attribute is a MatchPoint attribute that can be used when implementing custom ASP.NET user controls. A method marked with this attribute can be called using $$.Invoke('MyControl.MyMethod') or MP.ExpressionEvaluator.Eval('MyControl.MyMethod()') - or the shortcut introduced with MatchPoint 3.1 $$.Eval('MyControl.MyMethod()') - the ClientCallable attribute is a security mechanism to prevent calls to any public method not using this attribute.

As we now have our custom code, we will configure the ribbon buttons.

Ribbon Button Introduction

In the Data Grid Configuration a ContextualRibbonGroups element is added to the root element of the configuration. A group consists of a TabTitle and a Title - the descriptions below are self-explaining. The button definition provides a very flexible and simple way to implement ribbon functionality. The properties used in this example are:

• OnClickScript can be used to configure javascript code that is executed after OnClickExpression. The result of OnClickExpression can be accessed by the "resultValue" variable.
• OnClickExpression defines a MatchPoint expression that is evaluated server-side.
• EnabledExpression must evaluate to bool and determines whether the button is enabled or not.

Please note for all available configuration properties:

Dynamic changes of the controls are only triggered by "ConnectionData" expressions. "DataItem" or something like this is not availabe.

Archive Ribbon Button Using OnClickScript

The button definition contains a Label, IconUrl and LargeIconUrl. As we want to pass a boolean user input result to Archive(string, bool), the whole expression handling is done by the OnClickScript section. The result of a simple javascript confirm window is saved in var "res". The call to the expression uses the MatchPoint expression evaluator mechanism, retrieving the second parameter WorkspaceUrl from the selected Data Grid row: ConnectionData.Workspaces.SelectedRow.Url. After the expression evaluation the window is reloaded.

The OnClickScript code:

var res = confirm("Do you want delete the redirector item as well?");
$$.Eval("WorkspaceHelper.Archive(ConnectionData.Workspaces.SelectedRow.Url, " + res + ")");
return true;

In the EnabledExpression, some validation check can be implemented, e.g. only enable the button if it is not yet archived (!ConnectionData.Workspaces.SelectedRow.ReadOnly or something like ConnectionData.Workspaces.SelectedRow.IsUserInRole('Administrator')).

Archive Ribbon Button Using OnClickExpression

The button definition for the restore button just uses the OnClickExpression field passing the workspace url to the method and, same as above, a check for the EnableExpression.