XML du Ruban serveur

Dernière modification : lundi 7 février 2011

S’applique à : SharePoint Foundation 2010

La rubrique suivante décrit le XML du Ruban serveur et explique les valeurs qui sont utilisées pour les attributs.

Présentation détaillée du code XML du Ruban serveur

    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition 
          Location="Ribbon.Tabs._children">
          <Tab 
            Id="Ribbon.CustomTabExample" 
            Sequence="501" 
            Description="My New Tab" 
            Title="My New Tab">

L’attribut Location de l’élément CommandUIDefinition définit à quel endroit les contrôles qu’il renferme seront affichés. Dans cet exemple, vous référencez la collection Tabs du Ruban serveur. La convention _children indique au Ruban d’insérer le code XML suivant dans la sortie en vue de son affichage. Dans ce cas, vous insérez le XML de l’élément Tab. L’attribut Sequence définit l’endroit où l’onglet sera restitué par rapport aux autres onglets. Les onglets par défaut utilisent des multiples de 100, si bien que l’attribut Sequence ne doit pas être un multiple de 100, et ce afin d’éviter les conflits. Évitez les conflits afin de garantir la manipulation correcte du code XML du Ruban.

            <Scaling
              Id="Ribbon.CustomTabExample.Scaling">
              <MaxSize
                Id="Ribbon.CustomTabExample.MaxSize" 
                GroupId="Ribbon.CustomTabExample.CustomGroupExample" 
                Size="OneLargeTwoMedium"/>
              <Scale 
                Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"
                GroupId="Ribbon.CustomTabExample.CustomGroupExample" 
                Size="OneLargeTwoMedium" />
            </Scaling>

Lorsque vous créez un onglet personnalisé, vous devez définir comment l’onglet sera mis à l’échelle lors de l’ajout de contrôles. Cette opération est gérée à l’aide de l’élément Scaling et d’un GroupTemplate. L’élément MaxSize définit la taille maximale des contrôles dans le groupe. L’élément Scale définit la mise à l’échelle du groupe suivant les situations. L’attribut GroupId associe un groupe à la taille de la mise à l’échelle. L’attribut Size est défini par l’élément Layout, qui est défini plus loin dans cette rubrique.

            <Groups Id="Ribbon.CustomTabExample.Groups">
              <Group 
                Id="Ribbon.CustomTabExample.CustomGroupExample" 
                Description="This is a custom group!" 
                Title="Custom Group" 
                Sequence="52" 
                Template="Ribbon.Templates.CustomTemplateExample">
                <Controls Id="Ribbon.CustomTabExample.CustomGroupExample.Controls">
                  <Button 
                    Id="Ribbon.CustomTabExample.CustomGroupExample.HelloWorld" 
                    Command="CustomTabExample.HelloWorldCommand" 
                    Sequence="15" 
                    Description="Says Hello to the World!" 
                    LabelText="Hello, World!" 
                    TemplateAlias="cust1"/>

L’élément Groups définit les groupes qui seront affichés sous l’onglet. L’élément Group lui-même possède des attributs similaires aux autres contrôles, ainsi qu’un attribut Template. L’attribut Template référence le GroupTemplate défini plus loin dans cette rubrique. L’élément Controls contient les contrôles qui seront affichés dans le groupe. Les types acceptables de contrôles sont définis dans Architecture du Ruban serveur. Les contrôles dans le groupe doivent définir les attributs TemplateAlias et Command. Comme les onglets, chaque contrôle dispose d’un attribut Sequence qui définit où il sera affiché dans le groupe. Les contrôles par défaut sont basés sur des multiples de 10, si bien qu’aucun contrôle personnalisé ne doit utiliser un multiple de 10, et ce afin d’éviter les conflits. L’attribut Command est utilisé par l’élément CommandUIHandler, mais est requis même si l’élément CommandUIHandler n’est pas spécifié. L’attribut TemplateAlias définit l’emplacement auquel le contrôle sera affiché par rapport au GroupTemplate.

          <GroupTemplate Id="Ribbon.Templates.CustomTemplateExample">
            <Layout 
              Title="OneLargeTwoMedium" 
              LayoutTitle="OneLargeTwoMedium">
              <Section Alignment="Top" Type="OneRow">
                <Row>
                  <ControlRef DisplayMode="Large" TemplateAlias="cust1" />
                </Row>
              </Section>
              <Section Alignment="Top" Type="TwoRow">
                <Row>
                  <ControlRef DisplayMode="Medium" TemplateAlias="cust2" />
                </Row>
                <Row>
                  <ControlRef DisplayMode="Medium" TemplateAlias="cust3" />
                </Row>
              </Section>
            </Layout>
          </GroupTemplate>

Lorsque vous définissez un modèle de groupe, vous devez le définir dans un autre CommandUIDefinition. Le CommandUIDefinition a pour emplacement Ribbon.Templates._children. Il s’agit du même modèle que celui utilisé pour les groupes et les onglets.

L’élément GroupTemplate contient un élément Layout qui contient des éléments Section ou OverflowSection. L’élément Layout possède un attribut Title qui est utilisé pour l’attribut Size sur les éléments MaxSize et Scale.

L’élément Section possède deux attributs. L’attribut Alignment définit le positionnement des contrôles dans les éléments suivants Row. L’attribut Type définit le nombre de lignes à afficher dans cette section. Un élément Section dispose au maximum de 3 éléments Row.

L’élément Row contient un ou plusieurs éléments ControlRef. Chaque élément ControlRefdéfinit l’affichage d’un contrôle spécifique dans le Ruban. L’attribut DisplayMode possède les valeurs suivantes.

Attention
Toutes les valeurs DisplayMode ne sont pas disponibles pour tous les contrôles.

Vous pouvez également utiliser un élément OverflowSection plutôt qu’un élément Section. Cet élément définit une zone dans laquelle plusieurs contrôles peuvent s’afficher sans qu’il soit nécessaire de recourir à des éléments Row. Tous les contrôles s’affichent dans la taille définie par l’attribut DisplayMode. Les attributs DividerAfter et DividerBefore définissent où le séparateur s’affiche lors du rendu de la section de dépassement de capacité.

Lorsque vous ajoutez des contrôles pour les emplacements de Ruban par défaut, vous devez déterminer le modèle de groupe et la mise à l’échelle à utiliser. L’ajout d’un contrôle pour les emplacements par défaut peut modifier le rendu du groupe. La plupart des modèles de groupe par défaut contiennent des sections de dépassement de capacité dont la taille augmente en raison de la présence de vos contrôles personnalisés. Dans les scénarios plus avancés, vous pouvez substituer la mise à l’échelle pour restituer les contrôles en fonction de votre conception.

      <CommandUIHandlers>
        <CommandUIHandler 
          Command="CustomTabExample.HelloWorldCommand" 
          CommandAction="javascript:alert('Hello, world!');" />
        <CommandUIHandler 
          Command="CustomTabExample.GoodbyeWorldCommand" 
          CommandAction="javascript:alert('Good-bye, world!');" />
        <CommandUIHandler 
          Command="CustomTabExample.LoveWorldCommand" 
          CommandAction="javascript:alert('I love you, world!');" />
      </CommandUIHandlers>
    </CommandUIExtension>

L’élément CommandUIHandlers contient tous les éléments CommandUIHandler. Les éléments CommandUIHandler définissent la façon dont les contrôles du Ruban répondent à une action. L’attribut Command est un nom unique pour la commande qui est utilisée conjointement avec l’attribut Command défini avec les contrôles. L’attribut CommandAction contient l’action effectuée pour le contrôle. Il peut s’agir de code ECMAScript (JavaScript, JScript), d’une URL ou de tout ce qui était précédemment contenu dans un élément UrlAction.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <CustomAction 
    Id="MyCustomRibbonTab" 
    Location="CommandUI.Ribbon.ListView" 
    RegistrationId="101" 
    RegistrationType="List"> 
    ...
  </CustomAction>
</Elements>

Lors de la personnalisation du Ruban, vous utilisez un élément CustomActionavec le code XML du Ruban. Pour plus d’informations sur les actions personnalisées, voir Action personnalisée. L’attribut Location indique à CustomAction où appliquer la personnalisation. Le tableau suivant explique les valeurs.

Voir aussi

Concepts

Personnalisation déclarative du Ruban serveur

Emplacements des personnalisations du Ruban serveur par défaut

Architecture du Ruban serveur

Schéma du Ruban serveur