Procédure pas à pas : création d’un composant WebPart personnalisé avec un onglet contextuel
Dernière modification : vendredi 4 février 2011
S’applique à : SharePoint Foundation 2010
Dans cet article
Création d’un projet SharePoint
Implémentation du composant WebPart
Création du composant de page
Déploiement de la personnalisation
Cette rubrique décrit la procédure de création d’un composant WebPart qui ouvre un onglet contextuel sur le Ruban serveur de Microsoft SharePoint Foundation.
Conditions requises
Microsoft SharePoint Foundation 2010
Outils de développement SharePoint dans Microsoft Visual Studio 2010
Création d’un projet SharePoint
Pour créer le composant WebPart et la personnalisation du Ruban, commencez par créer un projet SharePoint vide.
Pour créer un projet SharePoint
Démarrez Visual Studio 2010.
Dans le menu Fichier, pointez sur Nouveau, puis cliquez sur Projet.
Dans Types de projets, sous C#, sélectionnez Projet SharePoint vide.
Tapez ContextualTabWebPart en guise de nom de projet, puis cliquez sur OK.
Dans l’Assistant Personnalisation de SharePoint, sélectionnez Déployer en tant que solution de batterie de serveurs, puis cliquez sur Terminer.
Implémentation du composant WebPart
À présent, vous devez implémenter le composant WebPart.
Pour implémenter le composant WebPart
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur Références, puis sélectionnez Ajouter une référence.
Dans la boîte de dialogue Ajouter une référence, sélectionnez l’onglet .NET, puis Microsoft.Web.CommandUI.dll. Cliquez sur OK.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet ContextualTabWebPart, pointez sur Ajouter, puis sélectionnez Nouvel élément.
Dans la boîte de dialogue Ajouter un nouvel élément, sélectionnez Composant WebPart. Tapez ContextualTabWebPart en tant que nom.
Une fois le composant WebPart ajouté et le fichier ContextualTabWebPart.cs affiché, ajoutez les instructions suivantes.
using System.Xml; using Microsoft.Web.CommandUI;Implémentez ensuite l’interface IWebPartPageComponentProvider comme illustré dans le code suivant. Vous l’utiliserez par la suite.
public class ContextualTabWebPart : WebPart, IWebPartPageComponentProviderLa prochaine étape consiste à créer deux variables String globales pour le Ruban XML. Ces deux variables définissent l’onglet contextuel et les modèles de groupe. Pour plus d’informations sur le code XML du Ruban, voir XML du Ruban serveur.
Dans la chaîne contextualTab, notez la présence de l’élément ContextualGroup. Cet élément définit l’élément Tab suivant en tant qu’onglet contextuel. L’attribut Color définit la couleur de l’onglet une fois rendu. Id et ContextualGroupId sont des identificateurs uniques pour le groupe. L’attribut Sequence définit l’emplacement de l’onglet contextuel après rendu. Le code suivant implémente deux variables String globales.
private string contextualTab = @" <ContextualGroup Color=""Magenta"" Command=""CustomContextualTab.EnableContextualGroup"" Id=""Ribbon.CustomContextualTabGroup"" Title=""Custom Contextual Tab Group"" Sequence=""502"" ContextualGroupId=""CustomContextualTabGroup""> <Tab Id=""Ribbon.CustomTabExample"" Title=""My Custom Tab"" Description=""This holds my custom commands!"" Command=""CustomContextualTab.EnableCustomTab"" Sequence=""501""> <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> <Groups Id=""Ribbon.CustomTabExample.Groups""> <Group Id=""Ribbon.CustomTabExample.CustomGroupExample"" Description=""This is a custom group!"" Title=""Custom Group"" Command=""CustomContextualTab.EnableCustomGroup"" Sequence=""52"" Template=""Ribbon.Templates.CustomTemplateExample""> <Controls Id=""Ribbon.CustomTabExample.CustomGroupExample.Controls""> <Button Id=""Ribbon.CustomTabExample.CustomGroupExample.HelloWorld"" Command=""CustomContextualTab.HelloWorldCommand"" Sequence=""15"" Description=""Says hello to the World!"" LabelText=""Hello, World!"" TemplateAlias=""cust1""/> <Button Id=""Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"" Command=""CustomContextualTab.GoodbyeWorldCommand"" Sequence=""17"" Description=""Says good-bye to the World!"" LabelText=""Good-bye, World!"" TemplateAlias=""cust2""/> </Controls> </Group> </Groups> </Tab> </ContextualGroup>"; private string contextualTabTemplate = @" <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>";Créez une nouvelle propriété de type chaîne nommée DelayScript. DelayScript contient ECMAScript (JavaScript, JScript) qui ajoute et enregistre votre composant de page personnalisé. Vous créerez le composant de page personnalisé plus loin dans cette rubrique. La méthode _addCustomPageComponent crée le composant de page personnalisé et l’ajoute au gestionnaire de pages. Chaque composant WebPart contient un composant de page ; vous utiliserez l’ID du composant de page du composant WebPart lorsque vous créerez un objet de composant de page personnalisé. Cela s’avère nécessaire pour associer le composant WebPart au composant de page pour permettre le basculement contextuel vers votre onglet de Ruban personnalisé. La méthode _registerCustomPageComponent enregistre votre fichier JavaScript lors du chargement de la page.
Le code suivant implémente DelayScript.
public string DelayScript { get { string webPartPageComponentId = SPRibbon.GetWebPartPageComponentId(this); return @" <script type=""text/javascript""> //<![CDATA[ function _addCustomPageComponent() { var _customPageComponent = new ContextualTabWebPart.CustomPageComponent('" + webPartPageComponentId + @"'); SP.Ribbon.PageManager.get_instance().addPageComponent(_customPageComponent); } function _registerCustomPageComponent() { SP.SOD.registerSod(""CustomContextualTabPageComponent.js"", ""\/_layouts\/CustomContextualTabPageComponent.js""); SP.SOD.executeFunc(""CustomContextualTabPageComponent.js"", ""ContextualWebPart.CustomPageComponent"", _addCustomPageComponent); } SP.SOD.executeOrDelayUntilScriptLoaded(_registerCustomPageComponent, ""sp.ribbon.js""); //]]> </script>"; } }Créez une nouvelle fonction sous le nom AddContextualTab. À l’intérieur de la méthode AddContextualTab, vous allez insérer du code pour enregistrer l’onglet contextuel et les modèles personnalisés avec le Ruban. La méthode RegisterDataExtension(XmlNode, String) sera utilisée pour enregistrer les extensions du Ruban. RegisterDataExtension(XmlNode, String) indique au Ruban où charger le code XML qui lui a été transmis. Vous utilisez les identificateurs des éléments ContextualTabs et Templates de CMDUI.xml.
Le code suivant implémente la méthode AddContextualTab.
private void AddContextualTab() { // Get the current instance of the ribbon on the page. Microsoft.Web.CommandUI.Ribbon ribbon = SPRibbon.GetCurrent(this.Page); // Prepare an XmlDocument object used to load the ribbon extensions. XmlDocument ribbonExtensions = new XmlDocument(); // Load the contextual tab XML and register the ribbon extension. ribbonExtensions.LoadXml(this.contextualTab); ribbon.RegisterDataExtension(ribbonExtensions.FirstChild, "Ribbon.ContextualTabs._children"); // Load the custom templates and register the ribbon extension. ribbonExtensions.LoadXml(this.contextualTabTemplate); ribbon.RegisterDataExtension(ribbonExtensions.FirstChild, "Ribbon.Templates._children"); }À présent, vous devez implémenter la propriété WebPartContextualInfo de l’interface IWebPartPageComponentProvider. Pour implémenter l’interface, cliquez avec le bouton droit sur IWebPartPageComponentProvider, sélectionnez Implémenter l’interface, puis Implémenter l’interface explicitement.
Cette interface informe le Ruban qu’un composant WebPart est sélectionné et lui indique le groupe et l’onglet contextuel à afficher. Lorsque vous ajoutez le groupe contextuel, vous lui envoyez l’identificateur du groupe contextuel et les paramètres VisibilityContext et Command. L’identificateur est mappé à la propriété Id de l’élément ContextualGroup du Ruban XML. Le paramètre VisibilityContext permet de regrouper les contrôles afin de les afficher ou de les masquer. Le paramètre Command est mappé au paramètre Command de l’élément ContextualGroup du Ruban XML. Vous devez également ajouter l’onglet qui a été défini dans le Ruban XML. Vous devez uniquement transmettre les paramètres Id et VisibilityContext pour l’onglet. Insérez le code suivant pour WebPartContextualInfo.
public WebPartContextualInfo WebPartContextualInfo { get { WebPartContextualInfo info = new WebPartContextualInfo(); WebPartRibbonContextualGroup contextualGroup = new WebPartRibbonContextualGroup(); WebPartRibbonTab ribbonTab = new WebPartRibbonTab(); // Create the contextual group object and initialize its values. contextualGroup.Id = "Ribbon.CustomContextualTabGroup"; contextualGroup.Command = "CustomContextualTab.EnableContextualGroup"; contextualGroup.VisibilityContext = "CustomContextualTab.CustomVisibilityContext"; // Create the tab object and initialize its values. ribbonTab.Id = "Ribbon.CustomTabExample"; ribbonTab.VisibilityContext = "CustomContextualTab.CustomVisibilityContext"; // Add the contextual group and tab to the WebPartContextualInfo. info.ContextualGroups.Add(contextualGroup); info.Tabs.Add(ribbonTab); info.PageComponentId = SPRibbon.GetWebPartPageComponentId(this); return info; } }Vous devez ensuite implémenter la méthode OnPreRender. Cela vous permet d’ajouter des éléments au Ruban avant sa restitution sur la page. À l’intérieur de OnPreRender, vous devez appeler la méthode AddContextualTab et inscrire DelayScript auprès de ClientScriptManager.
Le code suivant implémente la méthode OnPreRender.
protected override void OnPreRender(EventArgs e) { base.OnPreRender(e); this.AddContextualTab(); ClientScriptManager clientScript = this.Page.ClientScript; clientScript.RegisterClientScriptBlock(this.GetType(), "ContextualTabWebPart", this.DelayScript); }Le composant WebPart est terminé. Vous devez à présent créer le composant de page.
Création du composant de page
Un composant de page est un objet JavaScript qui permet d’interagir avec le Ruban serveur. Pour une présentation approfondie du composant de page, voir Développement de composants de page pour le Ruban serveur. Pour que le composant de page fonctionne correctement, vous devez le déployer à l’aide d’un module dans le répertoire %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\\TEMPLATES\LAYOUTS. Il active les commandes du Ruban et répond aux commandes que vous définissez dans le Ruban XML.
Pour ajouter et définir le composant de page
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet ContextualTabWebPart, pointez sur Ajouter, puis sélectionnez Nouvel élément.
Dans la boîte de dialogue Ajouter un nouvel élément, sélectionnez le modèle Module et tapez CustomContextualTabPageComponent en tant que nom. Cliquez sur Ajouter.
Les fichiers par défaut qui sont ajoutés ne vous sont d’aucune utilité. Dans l’Explorateur de solutions, supprimez Elements.xml et Sample.txt.
À présent, vous devez ajouter le fichier JavaScript. Cliquez avec le bouton droit sur CustomContextualTabPageComponent, pointez sur Ajouter, puis sélectionnez Nouvel élément.
Dans la liste Modèles installés, sous Visual C#, sélectionnez Web. Sélectionnez le type Fichier Jscript, puis tapez CustomContextualTabPageComponent en tant que nom.
Vous devez définir l’emplacement de déploiement de façon à placer le fichier dans le répertoire _layouts. Pour ce faire, dans l’Explorateur de solutions, sélectionnez CustomContextualTabPageComponent.js. Dans la fenêtre Propriétés, en guise de Type de déploiement, sélectionnez Fichier racine. Ouvrez la propriété Emplacement de déploiement, puis tapez TEMPLATE\LAYOUTS dans la propriété Chemin d’accès.
Ajoutez le code suivant au fichier CustomContextualTabPageComponent.js pour implémenter votre composant de page personnalisé.
Type.registerNamespace('ContextualTabWebPart'); var _webPartPageComponentId; ContextualTabWebPart.CustomPageComponent = function ContextualTabWebPart_CustomPageComponent(webPartPcId) { this._webPartPageComponentId = webPartPcId; ContextualTabWebPart.CustomPageComponent.initializeBase(this); } ContextualTabWebPart.CustomPageComponent.prototype = { init: function ContextualTabWebPart_CustomPageComponent$init() { }, getFocusedCommands: function ContextualTabWebPart_CustomPageComponent$getFocusedCommands() { return ['CustomContextualTab.EnableCustomTab', 'CustomContextualTab.EnableCustomGroup', 'CustomContextualTab.HelloWorldCommand', 'CustomContextualTab.GoodbyeWorldCommand']; }, getGlobalCommands: function ContextualTabWebPart_CustomPageComponent$getGlobalCommands() { return []; }, isFocusable: function ContextualTabWebPart_CustomPageComponent$isFocusable() { return true; }, canHandleCommand: function ContextualTabWebPart_CustomPageComponent$canHandleCommand(commandId) { // Contextual Tab commands if ((commandId === 'CustomContextualTab.EnableCustomTab') || (commandId === 'CustomContextualTab.EnableCustomGroup') || (commandId === 'CustomContextualTab.HelloWorldCommand') || (commandId === 'CustomContextualTab.GoodbyeWorldCommand')) { return true; } }, handleCommand: function ContextualTabWebPart_CustomPageComponent$handleCommand(commandId, properties, sequence) { if (commandId === 'CustomContextualTab.HelloWorldCommand') { alert('Hello, world!'); } if (commandId === 'CustomContextualTab.GoodbyeWorldCommand') { alert('Good-bye, world!'); } }, getId: function ContextualTabWebPart_CustomPageComponent$getId() { return this._webPartPageComponentId; } } ContextualTabWebPart.CustomPageComponent.registerClass('ContextualTabWebPart.CustomPageComponent', CUI.Page.PageComponent); SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("CustomContextualTabPageComponent.js");
Déploiement de la personnalisation
Le projet est déployé automatiquement par les Outils de développement SharePoint dans Visual Studio 2010. Le pool d’applications est automatiquement réinitialisé dans le cadre du processus de déploiement.
Pour déployer le composant WebPart
Appuyez sur F5. Les Outils de développement SharePoint dans Visual Studio 2010 génèrent et déploient automatiquement le composant WebPart et le fichier JavaScript.
Accédez à votre site.
Cliquez sur le bouton Modifier.
Sous l’onglet Insertion, cliquez sur le bouton Composant WebPart.
Dans Composant WebPart, sélectionnez la catégorie Personnalisé.
Dans la liste de composants WebPart, sélectionnez ContextualTabWebPart, puis cliquez sur Ajouter.
Une fois le composant WebPart ajouté à la page, cliquez sur le composant WebPart ContextualTabWebPart.
Comme vous pouvez le constater, l’onglet Afficher l'onglet contextuel personnalisé est maintenant affiché.
Voir aussi
Concepts
Développement de composants de page pour le Ruban serveur