Developing Page Components for the Server Ribbon

A page component is an ECMAScript (JavaScript, JScript) object that is used to interact with the Server ribbon. It enables commands on the ribbon and responds to the commands that you define in the Server ribbon XML. All page components must derive from the CUI.Page.PageComponent Class class and implement the required methods. This topic explains those methods and how they are used when interacting with the ribbon.

Commands in a Page Component

---

A page component contains two types of commands—global and focused. A page component only responds to focused commands if it has the focus. With global commands, a page component responds to the command regardless of the focus. The page component registers to respond to both types of commands through the SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method and the SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method. These methods are covered in more detail later in this topic.

Required Page Component Methods

---

The following methods are required for the page component to operate.

init

The SP.Ribbon.PageState.PageStateHandler.init() Method initializes the page component. You can use this method to initialize any variables for your page component. This includes initializing the list of commands that your page component can handle and also registering the array of methods that are used to handle commands. The list of commands is used in the SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method and the SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method. The array of methods is used in the SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method and the SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method.

ECMAScript

init: function CustomPageComponents_MyCustomPageComponent$init() {

   // Create an array of methods used to handle commands passed to the page component.
   this._myHandledCommands = new Object;
   this._myHandledCommands['MyFocusedRibbonCommands.EnableCustomTab'] = this.canHandleEnableCustomTab;
   this._myHandledCommands['MyFocusedRibbonCommands.EnableCustomGroup'] = this.canHandleEnableCustomGroup;

   // Create a list of commands that your page component can handle.
   this._myCommandList = ['MyFocusedRibbonCommands.EnableCustomTab', 'MyFocusedRibbonCommands.EnableCustomGroup', 'MyFocusedRibbonCommands.HelloWorldCommand', 'MyFocusedRibbonCommands.GoodbyeWorldCommand'];
}

getFocusedCommands

The SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method returns a string array with the names of the focused commands. The page component only responds to these commands if it has the focus. There are two approaches to returning the list of commands. You can either declare a list in the method or create an array of command names as shown in the SP.Ribbon.PageState.PageStateHandler.init() Method. The following code shows both approaches.

ECMAScript

getFocusedCommands: function CustomPageComponents_MyCustomPageComponent$getFocusedCommands() {
   return ['MyFocusedRibbonCommands.EnableCustomTab', 'MyFocusedRibbonCommands.EnableCustomGroup', 'MyFocusedRibbonCommands.HelloWorldCommand', 'MyFocusedRibbonCommands.GoodbyeWorldCommand'];

   // The alternative method using an array of strings. This is defined in the init method.
   // return this._myCommandList;
}

getGlobalCommands

The SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method returns a string array with the names of the global commands. The page component responds to these commands when it is on the page. There are two approaches to returning a list of commands. You can either declare a list in the method or create an array of command names as shown in the SP.Ribbon.PageState.PageStateHandler.init() Method. The following code shows both approaches.

ECMAScript

getGlobalCommands: function CustomPageComponents_MyCustomPageComponent$getGlobalCommands() {
   return ['MyGlobalRibbonCommands.EnableCustomTab', 'MyGlobalRibbonCommands.EnableCustomGroup', 'MyGlobalRibbonCommands.HelloWorldCommand', 'MyGlobalRibbonCommands.GoodbyeWorldCommand'];

   // The alternative method using an array of strings. This is defined in the init method.
   // return this._myCommandList;
}

isFocusable

The SP.Ribbon.PageState.PageStateHandler.isFocusable() Method returns a Boolean that indicates whether the page component can receive the focus. If this method returns false, the page manager will not register the page component's focused commands.

ECMAScript

isFocusable: function CustomPageComponents_MyCustomPageComponent$isFocusable() {
        return true;
    }

canHandleCommand

The SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method returns a Boolean that indicates whether the page component can handle the command that was passed to it. There are multiple approaches to returning a value from this method. If you are defining a small number of commands, use an if statement or a switch statement. If you are defining a large number of commands, use an associative array of commands indexed by the command name. The following code examples show the different approaches.
The if statement and switch statement approaches.

ECMAScript

// Using an if statement.
canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {
   if ((commandId === 'MyFocusedRibbonCommands.EnableCustomTab') || (commandId === 'MyFocusedRibbonCommands.EnableCustomGroup')) {
      return true; }
}

// Using a switch statement.
canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {
   switch(commandId)
   {
     case 'MyFocusedRibbonCommands.EnableCustomTab':
     case 'MyFocusedRibbonCommands.EnableCustomGroup':
        return true;
     default: return false;
   }
}

The array of commands approach.

ECMAScript

canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {

// The this._myHandledCommands object is a global array of command functions. This is demonstrated in the init method.
   var canHandle = this._myHandledCommands[commandId];

   if(canHandle)
     return true;
   else
     return false;
}

handleCommand

The SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method is used to handle a command that is passed to the page component. You can call other JavaScript functions or write code in the SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method. There are multiple approaches to handling a command in this method. You use the same method that you used for the SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method. The following code examples show both of these approaches.
The if statement and switch statement approaches.

ECMAScript

// Using an if statement.
handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
   if (commandId === 'MyFocusedRibbonCommands.HelloWorldCommand')
   {
     alert('I handled the Hello World command.');
   }
   else if(commandId === 'MyFocusedRibbonCommands.GoodbyeWorldCommand')
   {
     alert('I handled the Goodbye World command.');
   }
}

// Using a switch statement.
handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
   switch(commandId)
   {
     case 'MyFocusedRibbonCommands.HelloWorldCommand':
       alert('I handled the Hello World command.');
       break;
     case 'MyFocusedRibbonCommands.GoodbyeWorldCommand':
        alert('I handled the Goodbye World Command.');
       break;
   }
}

The array of commands approach.

ECMAScript

handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {

// The this._myHandledCommands object is a global array of commands. This is demonstrated in the init method.
   return this._myHandledCommands[commandId](commandId, properties, sequence);
}

Optional Page Component Methods

---

The following methods are optional in the page component.

yieldFocus

The SP.Ribbon.PageState.PageStateHandler.yieldFocus() Method is called when the page component loses focus.

ECMAScript

yieldFocus: function CustomPageComponents_MyCustomPageComponent$yieldFocus() {
   alert('The page component has lost focus.');
}

receiveFocus

The SP.Ribbon.PageState.PageStateHandler.receiveFocus() Method is used when the page component receives focus.

ECMAScript

receiveFocus: function CustomPageComponents_MyCustomPageComponent$receiveFocus() {
   alert('The page component has received focus.');
}

Sample Page Component

---

ECMAScript

Type.registerNamespace('CustomPageComponents');

CustomPageComponents.MyCustomPageComponent = function CustomPageComponents_MyCustomPageComponent(){
   CustomPageComponents.MyCustomPageComponent.initializeBase(this);
}

CustomPageComponents.MyCustomPageComponent.prototype = {
    init: function CustomPageComponents_MyCustomPageComponent$init() {  },
    getFocusedCommands: function CustomPageComponents_MyCustomPageComponent$getFocusedCommands() {
       return ['CustomContextualTab.EnableCustomTab', 'CustomContextualTab.EnableCustomGroup', 'CustomContextualTab.HelloWorldCommand', 'CustomContextualTab.GoodbyeWorldCommand'];
     },
 
    getGlobalCommands: function CustomPageComponents_MyCustomPageComponent$getGlobalCommands() {
        return [];
    },
 
    
    canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {

        // Contextual Tab commands
        if ((commandId === 'CustomContextualTab.EnableCustomTab') || (commandId === 'CustomContextualTab.EnableCustomGroup') || (commandId === 'CustomContextualTab.HelloWorldCommand') || (commandId === 'CustomContextualTab.GoodbyeWorldCommand')) {
            return true;
        }
    },
 
    handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
 
        if (commandId === 'CustomContextualTab.HelloWorldCommand') {
            alert('Hello, world!');
        }
        if (commandId === 'CustomContextualTab.GoodbyeWorldCommand') {
            alert('Good-bye, world!');
        }
    },
 
    getId: function CustomPageComponents_MyCustomPageComponent$getId() {
        return this._webPartPageComponentId;
    }
}


CustomPageComponents.MyCustomPageComponent.registerClass('CustomPageComponents.MyCustomPageComponent', CUI.Page.PageComponent);
SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("CustomContextualTabPageComponent.js");

Change History

---