Server リボンのページ コンポーネントを開発する

  • [アーティクル]

最終更新日: 2011年2月9日

適用対象: SharePoint Foundation 2010

この記事の内容
ページ コンポーネントのコマンド
ページ コンポーネントの必須メソッド
ページ コンポーネントのオプションのメソッド
サンプル ページ コンポーネント

ページ コンポーネントは、Server リボンを操作するときに使用する ECMAScript (JavaScript、JScript) オブジェクトで、リボンのコマンドを有効にして、Server リボン XML で定義するコマンドに応答します。すべてのページ コンポーネントが CUI.Page.PageComponent クラスから派生し、必須メソッドを実装している必要があります。ここでは、これらのメソッドと、そのメソッドを使用してリボンを操作する方法について説明します。

ページ コンポーネントのコマンド

ページ コンポーネントには、グローバル コマンドとフォーカスされたコマンドの 2 つの種類のコマンドが含まれます。ページ コンポーネントにフォーカスがある場合、そのコンポーネントは、フォーカスされたコマンドにのみ応答します。グローバル コマンドを使用すると、ページ コンポーネントは、フォーカスに関係なくすべてのコマンドに応答します。ページ コンポーネントが両方の種類のコマンドに応答するように登録するには、SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method および SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method を使用します。このメソッドについては、このトピックで後で詳しく説明します。

ページ コンポーネントの必須メソッド

ページ コンポーネントが動作するには、以下のメソッドが必要です。

init

SP.Ribbon.PageState.PageStateHandler.init() Method はページ コンポーネントを初期化します。このメソッドは、ページ コンポーネントの任意の変数を初期化するときに使用できます。たとえば、ページ コンポーネントで処理できるコマンドのリストを初期化したり、コマンドを処理するときに使用されるメソッドの配列を登録したりできます。コマンドのリストは、SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method および SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method で使用されます。メソッドの配列は、SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method および SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method で使用されます。

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

SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method は、フォーカスされたコマンドの名前を表す文字列配列を返します。ページ コンポーネントにフォーカスがある場合、そのコンポーネントは、フォーカスされたコマンドにのみ応答します。コマンドのリストを返す方法は 2 つあります。メソッドでリストを宣言する方法と、SP.Ribbon.PageState.PageStateHandler.init() Method で説明したようにコマンド名の配列を作成する方法です。以下のコードは、両方の方法を示しています。

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

SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method は、グローバル コマンドの名前を表す文字列配列を返します。ページ コンポーネントがページ上にある場合、そのコンポーネントは、これらのコマンドに応答します。コマンドのリストを返す方法は 2 つあります。メソッドでリストを宣言する方法と、SP.Ribbon.PageState.PageStateHandler.init() Method で説明したようにコマンド名の配列を作成する方法です。以下のコードは、両方の方法を示しています。

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

SP.Ribbon.PageState.PageStateHandler.isFocusable() Method は、ページ コンポーネントがフォーカスを受け取ることができるかどうかを示す Boolean を返します。このメソッドが false を返す場合、ページ マネージャーでは、ページ コンポーネントのフォーカスされたコマンドが登録されません。

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

canHandleCommand

SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method は、ページ コンポーネントが、自身に渡されたコマンドを処理できるかどうかを示す Boolean を返します。このメソッドから値を返す方法は複数あります。定義するコマンドの数が少ない場合は、if ステートメントまたは switch ステートメントを使用します。多数のコマンドを定義する場合は、コマンド名によってインデックスが設定されたコマンドの連想配列を使用します。以下のコード例は、それぞれの方法を示しています。

if ステートメントおよび switch ステートメントを使用する場合

// 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;
   }
}

コマンドの配列を使用する場合

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

SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method は、ページ コンポーネントに渡されたコマンドを処理するときに使用します。他の JavaScript 関数を呼び出すか、SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method にコードを記述することができます。このメソッドにはコマンドを処理する方法が複数あります。使用するのは、SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method で使用した方法と同じものです。以下のコード例は、その両方の方法を示しています。

if ステートメントおよび switch ステートメントを使用する場合

// 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;
   }
}

コマンドの配列を使用する場合

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);
}

ページ コンポーネントのオプションのメソッド

以下のメソッドは、ページ コンポーネントのオプションのメソッドです。

yieldFocus

SP.Ribbon.PageState.PageStateHandler.yieldFocus() Method は、ページ コンポーネントがフォーカスを失うと呼び出されます。

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

receiveFocus

SP.Ribbon.PageState.PageStateHandler.receiveFocus() Method は、ページ コンポーネントがフォーカスを受け取ったときに使用されます。

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

サンプル ページ コンポーネント

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");