Desarrollo de componentes de página para la cinta de Server

Última modificación: miércoles, 09 de febrero de 2011

Hace referencia a: SharePoint Foundation 2010

En este artículo
Comandos de un componente de página
Métodos de componentes de páginas necesarios
Métodos de componente de página opcionales
Ejemplo de componente de página

Un componente de página es un objeto ECMAScript (JavaScript, JScript) que se usa para interactuar con la Cinta de Server. Habilita los comandos de la cinta de opciones y responde a los comandos que se definen en el XML de la Cinta de Server. Todos los componentes de la página deben derivar de la clase CUI.Page.PageComponent Class e implementar los métodos necesarios. En este tema se explican dichos métodos y cómo se usan al interactuar con la cinta de opciones.

Comandos de un componente de página

Un componente de página contiene dos tipos de comandos: globales y específicos. Un componente de página solo responde a los comandos específicos si tiene el foco. Con los comandos globales, un componente de página responde al comando, independientemente del foco. El componente de página se registra para responder a los dos tipos de comandos a través del SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method y el SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method. Estos métodos se tratan con más detalle más adelante en este tema.

Métodos de componentes de páginas necesarios

Se requieren los métodos siguientes para que funcione el componente de página.

init

El SP.Ribbon.PageState.PageStateHandler.init() Method inicializa el componente de página. Se puede usar este método para inicializar las variables del componente de página. Esto incluye la inicialización de la lista de comandos que puede controlar el componente de página, así como el registro de la matriz de los métodos usados para controlar los comandos. La lista de comandos se usa en el SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method y en el SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method. La matriz de métodos se usa en el SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method y en el 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

El SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method devuelve una matriz de cadenas con los nombres de los comandos específicos. El componente de página solo responde a estos comandos si tiene el foco. Existen dos métodos para devolver la lista de comandos. Se puede declarar una lista en el método o crear una matriz de nombres de comando tal como se muestra en el SP.Ribbon.PageState.PageStateHandler.init() Method. El código siguiente muestra ambos enfoques.

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

El SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method devuelve una matriz de cadenas con los nombres de los comandos globales. El componente de la página responde a estos comandos cuando se encuentra en la página. Existen dos métodos para devolver una lista de comandos. Se puede declarar una lista en el método o crear una matriz de nombres de comando tal como se muestra en el SP.Ribbon.PageState.PageStateHandler.init() Method. El código siguiente muestra ambos enfoques.

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

El SP.Ribbon.PageState.PageStateHandler.isFocusable() Method devuelve un valor Boolean que indica si el componente de la página puede recibir el foco. Si este método devuelve false, el administrador de la página no registrará los comandos específicos del componente de página.

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

canHandleCommand

El SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method devuelve un valor Boolean que indica si el componente de página puede controlar el comando que se le pasó. Existen varios métodos para devolver un valor de este método. Si va a definir un número reducido de comandos, use una instrucción if o una instrucción switch. Si va a definir un gran número de comandos, use una matriz asociativa de comandos indizada por el nombre de comando. En el código siguiente se muestran los diferentes enfoques.

Los enfoques de la instrucción if y la instrucción 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;
   }
}

El enfoque de la matriz de comandos.

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

El SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method se usa para controlar un comando que se pasa al componente de página. Puede llamar a otras funciones JavaScript o escribir código en el SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method. Existen varios métodos para controlar un comando en este método. Se usa el mismo método que se usó para el SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method. En el código siguiente se muestran ambos enfoques.

Los enfoques de la instrucción if y la instrucción 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;
   }
}

El enfoque de la matriz de comandos.

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étodos de componente de página opcionales

Los métodos siguientes son opcionales en el componente de página.

yieldFocus

Se realiza una llamada al SP.Ribbon.PageState.PageStateHandler.yieldFocus() Method cuando el componente de página pierde el foco.

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

receiveFocus

El SP.Ribbon.PageState.PageStateHandler.receiveFocus() Method se usa cuando el componente de página recibe el foco.

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

Ejemplo de componente de página

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