Développement de composants de page pour le Ruban serveur

Dernière modification : mercredi 9 février 2011

S’applique à : SharePoint Foundation 2010

Dans cet article
Commandes dans un composant de page
Méthodes de composant de page requises
Méthodes de page de composants facultatifs facultatives
Exemple de composant de page

Un composant de page est un objet ECMAScript (JavaScript, JScript) qui permet d’interagir avec le Ruban serveur. Il active les commandes du Ruban et répond aux commandes que vous définissez dans le XML du Ruban serveur. Tous les composants de page doivent dériver de la clase CUI.Page.PageComponent Class et implémenter les méthodes requises. Cette rubrique vous explique ces méthodes et comment elles sont utilisées lors de l’interaction avec le Ruban.

Commandes dans un composant de page

Un composant de page contient deux types de commandes : des commandes globales et des commandes spécialisées. Un composant de page ne répond aux commandes spécialisées que s’il a le focus. Dans le cas des commandes globales, un composant de page répond à une commande indépendamment du focus. Le composant de page s’enregistre pour répondre à ces deux types de commandes par le biais de la méthode SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method et de la SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method. Ces méthodes sont couvertes plus en détail plus loin dans cette rubrique.

Méthodes de composant de page requises

Les méthodes suivantes sont nécessaires pour que le composant de page fonctionne.

init

La SP.Ribbon.PageState.PageStateHandler.init() Method initialise le composant de page. Vous pouvez utiliser cette méthode pour initialiser des variables pour votre composant de page. Cela comprend l’initialisation de la liste de commandes que votre composant de page peut gérer, ainsi que l’enregistrement du tableau de méthodes servant à gérer des commandes. La liste de commandes est utilisée dans la SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method et la SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method. Le tableau de méthodes est utilisé dans la SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method et la 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

La SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method retourne un tableau de chaînes avec les noms des commandes spécialisées. Le composant de page ne répond à ces commandes que s’il a le focus. Il existe deux approches pour retourner la liste de commandes. Vous pouvez déclarer une liste dans la méthode ou créer un tableau de noms de commandes, comme illustré dans la SP.Ribbon.PageState.PageStateHandler.init() Method. Le code suivant illustre les deux approches.

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

La SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method retourne un tableau de chaînes avec les noms des commandes globales. Le composant de page répond à ces commandes lorsqu’il se trouve sur la page. Il existe deux approches pour retourner une liste de commandes. Vous pouvez déclarer une liste dans la méthode ou créer un tableau de noms de commandes, comme illustré dans la SP.Ribbon.PageState.PageStateHandler.init() Method. Le code suivant illustre les deux approches.

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

La SP.Ribbon.PageState.PageStateHandler.isFocusable() Method retourne une valeur Boolean qui indique si le composant de page peut recevoir le focus. Si cette méthode retourne false, le Gestionnaire de pages n’enregistre pas les commandes spécialisées du composant de page.

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

canHandleCommand

La SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method retourne une valeur Boolean qui indique si le composant de page peut traiter la commande qui lui a été transmise. Il existe plusieurs approches pour retourner une valeur à partir de cette méthode. Si vous définissez un petit nombre de commandes, utilisez une instruction if ou une instruction switch. Si vous définissez un grand nombre de commandes, utilisez un tableau associatif de commandes indexé par le nom de commande. Les exemples de code suivants illustrent les différentes approches.

Approches avec l’instruction if et avec l’instruction 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;
   }
}

Approche avec le tableau de commandes

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

La SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method est utilisée pour traiter une commande passée au composant de page. Vous pouvez appeler d’autres fonctions JavaScript ou écrire du code dans la SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method. Il existe plusieurs approches pour le traitement d’une commande dans cette méthode. Vous allez utiliser la même méthode que vous avez utilisée pour la SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method. Les exemples de code suivants illustrent ces deux approches.

Approches avec l’instruction if et avec l’instruction 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;
   }
}

Approche avec le tableau de commandes

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

Méthodes de page de composants facultatifs facultatives

Les méthodes suivantes sont facultatives dans le composant de page.

yieldFocus

La SP.Ribbon.PageState.PageStateHandler.yieldFocus() Method est appelée lorsque le composant de page perd le focus.

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

receiveFocus

La SP.Ribbon.PageState.PageStateHandler.receiveFocus() Method est utilisée lorsque le composant de page reçoit le focus.

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

Exemple de composant de page

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