Créer un bouton de ruban personnalisé dans le site web hôte d’un complément SharePointCreate a custom ribbon button in the host web of a SharePoint Add-in

Cet article est le neuvième d’une série sur les concepts de base du développement de compléments SharePoint hébergés par SharePoint. Vous devez tout d’abord avoir pris connaissance de la rubrique Compléments SharePoint et des articles précédents de la série, disponibles dans la rubrique Commencer à créer des compléments SharePoint hébergés par SharePoint.This is the ninth in a series of articles about the basics of developing SharePoint-hosted SharePoint Add-ins. You should first be familiar with SharePoint Add-ins and the previous articles in this series:

Note

Si vous avez consulté les articles sur les compléments hébergés par SharePoint, votre solution Visual Studio vous sera utile pour continuer à parcourir cette rubrique.If you have been working through this series about SharePoint-hosted add-ins, you have a Visual Studio solution that you can use to continue with this topic. Vous pouvez également télécharger le référentiel sur SharePoint_SP-hosted_Add-Ins_Tutorials et ouvrir le fichier BeforeRibbon.sln.You can also download the repository at SharePoint_SP-hosted_Add-Ins_Tutorials and open the BeforeRibbon.sln file.

Tous les compléments SharePoint peuvent être exécutés à partir de la page Contenu du site du site web hôte en sélectionnant la vignette du complément.All SharePoint Add-ins can be run from the Site Contents page of the host web by selecting the add-in's tile. La fonctionnalité d’un complément SharePoint peut également être affichée sur le site web hôte au moyen des actions personnalisées, qui correspondent à des boutons de ruban ou à des éléments de menu personnalisés.The functionality of a SharePoint Add-in can also be exposed on the host web through custom actions, which are custom ribbon buttons or custom menu items. Dans cet article, vous allez apprendre à ajouter un bouton sur le ruban d’un site web hôte.In this article you add a button to the ribbon on a host web.

Préparer le site web hôtePrepare the host web

Pour ajouter le bouton dans le ruban d’un calendrier sur le site web hôte, suivez les étapes ci-dessous dans l’interface utilisateur de votre site de développeur SharePoint.To add the button to the ribbon of a calendar on the host web, take the following steps in the UI of your SharePoint developer site.

  1. Sur la page d’accueil du site, sélectionnez Contenu du site > Ajouter un complément > Calendrier.From the home page of the site, select Site Contents > add and add-in > Calendar.

  2. Dans la boîte de dialogue Ajout du calendrier, entrez Programme d’orientation de l’employé comme nom, puis sélectionnez Créer.In the Adding Calendar dialog, for the Name, enter Employee Orientation Schedule, and then select Create.

  3. Quand le calendrier s’ouvre, placez le curseur sur une date jusqu’à ce que le lien Ajouter apparaisse, puis sélectionnez Ajouter.When the calendar opens, put the cursor on any date until the Add link appears on the date, and then select Add.

  4. Dans la boîte de dialogue Programme d’orientation de l’employé - Nouvel élément, entrez Orientation Charline Leblanc comme titre.In the Employee Orientation Schedule - New Item dialog, for the Title, enter Orient Cassi Hicks. Dans les autres champs, laissez les valeurs par défaut, puis sélectionnez Enregistrer.Leave the other fields at their defaults, and then select Save.

    Le calendrier doit ressembler à l’exemple suivant :The calendar should look similar to the following:

    Figure 1. Calendrier personnaliséFigure 1. Custom calendar

    Calendrier intitulé Programme d’orientation de l’employé avec un élément le 1er juin indiquant « Orientation Charline Leblanc »

Important

La procédure suivante nécessite que le calendrier soit visible dans l’interface utilisateur de Visual Studio (pour cela, Visual Studio devait être fermé quand vous avez créé le calendrier).The next procedure requires that the calendar be visible in the UI of Visual Studio, but it won't be if Visual Studio was open when you created the calendar. Avant de continuer, fermez Visual Studio et déconnectez-vous de toutes les fenêtres de navigateur et consoles PowerShell avec lesquelles vous êtes connecté à votre site de développeur.Before you continue, close Visual Studio, and sign out of any browser windows and PowerShell consoles where you are signed in to your developer site.

Ajouter une action personnalisée du rubanAdd a ribbon custom action

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit de la souris sur le projet EmployeeOrientation, puis sélectionnez Ajouter > Nouvel élément > Office/SharePoint > Action personnalisée de ruban. In Solution Explorer, right-click the EmployeeOrientation project, and select Add > New Item > Office/SharePoint > Ribbon Custom Action. Nommez l’élément RunOrientationAdd-in, puis sélectionnez Ajouter.Name it RunOrientationAdd-in, and then select Add.

  2. L’Assistant Créer une action personnalisée pour le ruban vous pose une série de questions.The Create Custom Action for Ribbon Wizard asks you a series of questions. Répondez à ces questions en vous aidant du tableau suivant, puis sélectionnez Terminer.Give the answers from the following table, and then select Finish.

    Question de la propriétéProperty question RéponseAnswer
    Où souhaitez-vous exposer l’action personnalisée ?Where do you want to expose the custom action? Sélectionnez Site web hôte.Select Host Web.
    Sur quoi l’action personnalisée doit-elle porter ?Where is the custom action scoped to? Sélectionnez Instance de liste (et non Modèle de liste).Select List Instance (not List Template).
    Sur quel élément particulier l’action personnalisée doit-elle porter ?Which particular item is the custom action scoped to? Sélectionnez Programme d’orientation de l’employé.Select Employee Orientation Schedule.
    Où le contrôle se trouve-t-il ?Where is the control located? Ne sélectionnez pas les options de la liste déroulante.Do not use the drop-down selections. Entrez Ribbon.Calendar.Events.Actions.Controls._children.Instead, enter Ribbon.Calendar.Events.Actions.Controls._children. (Le troisième composant Events désigne l’onglet du ruban et le quatrième composant Actions identifie le groupe de boutons.)(The third part, Events, identifies the tab of the ribbon, and the fourth part, Actions, identifies the button group.)
    Quel est le texte de l’élément de menu ?What is the text on the menu item? Entrez Orientation de l’employé.Enter Employee Orientation.
    Où mène l’action personnalisée ?Where does the custom action navigate to? Ne sélectionnez pas les options de la liste déroulante.Do not use the drop-down selections. Entrez ~appWebUrl/Lists/NewEmployeesInSeattle.Instead, enter ~appWebUrl/Lists/NewEmployeesInSeattle. Il s’agit de la page en mode liste de la liste, qui se trouve sur le site web de complément. Ainsi, le bouton de ruban du site web hôte ouvre une page sur le site web de complément.This is the list view page for the list, which is on the add-in web, so the ribbon button on the host web opens a page on the add-in web.

Inspecter la fonctionnalité de site web de complémentInspect the add-in web feature

Dans l’Explorateur de solutions, développez le dossier Fonctionnalités et sélectionnez la fonctionnalité NewEmployeeOrientationComponents.In Solution Explorer, expand the Features folder, and select the NewEmployeeOrientationComponents feature. Le concepteur de fonctionnalités s’ouvre.The Feature designer opens.

Notez que l’action personnalisée que vous avez créée, RunOrientationAdd-in, est répertoriée dans Éléments de la solution, et non dans Éléments de la fonctionnalité.Notice that the custom action that you created, RunOrientationAdd-in, is listed in Items in the solution, but not in Items in the feature. En effet, la fonctionnalité est déployée sur le site web de complément, alors que votre action personnalisée est déployée sur le site web hôte.This is because the feature is deployed to the add-in web, but your custom action is deployed to the host web.

Quand vous créer le package du complément dans Visual Studio pour le déployer sur l’environnement de production, ou quand vous appuyez sur F5 dans Visual Studio, les outils de développement Office pour Visual Studio créent une fonctionnalité de site web hôte spécifique, ajoutent l’action personnalisée à cette fonctionnalité et la déploient sur le site web hôte.When you package the add-in in Visual Studio for deployment to production, or when you select F5 in Visual Studio, the Office Developer Tools for Visual Studio creates a special host web feature, adds the custom action to it, and deploys it to the host web. Ne modifiez jamais la fonctionnalité de site web hôte (c’est pourquoi elle n’a pas été créée avant la création du package).You should never edit the host web feature; that is why it is not created until packaging time.

Figure 2. Concepteur de fonctionnalitésFigure 2. Feature designer

Concepteur de fonctionnalités avec des colonnes intitulées « Éléments de la solution » et « Éléments de la fonctionnalité ».

Exécuter et tester le complémentRun and test the add-in

  1. Utilisez la touche F5 pour déployer et exécuter votre complément. Visual Studio effectue une installation temporaire du complément sur votre site SharePoint de test et exécute immédiatement celui-ci.Use the F5 key to deploy and run your add-in. Visual Studio makes a temporary installation of the add-in on your test SharePoint site and immediately runs the add-in.

  2. La page par défaut du complément SharePoint s’ouvre.The default page of the SharePoint Add-in opens. Accédez à la page d’accueil de votre site de développeur (qui est le site web hôte).Go to the home page of your developer site (which is the host web). Un lien de navigation vers cette page figure dans le coin supérieur gauche de la page.There is a breadcrumb link to it in the upper-left corner of the page.

  3. Sur la page d’accueil du site web hôte, sélectionnez Contenu du site, et sur la page Contenu du site, sélectionnez le calendrier Programme d’orientation de l’employé (et non le complément Orientation de l’employé).On the host web's home page, select Site Contents, and on the Site Contents page, select the Employee Orientation Schedule calendar (not the Employee Orientation add-in).

  4. Quand le calendrier s’ouvre, sélectionnez l’événement Orientation Charline Leblanc.When the calendar opens, select the event Orient Cassie Hicks. Si l’onglet Événements du ruban ne s’ouvre pas automatiquement, ouvrez-le.If the Events tab on the ribbon doesn't open automatically, open it. Voici à quoi elle doit ressembler :It should look similar to the following:

    Figure 3. Onglet de ruban Événements avec le bouton personnaliséFigure 3. Events ribbon tab with custom button

    Ruban d’événements avec un bouton personnalisé nommé « Orientation de l’employé »

  5. Dans le groupe Actions du ruban, sélectionnez Orientation de l’employé.In the Actions group on the ribbon, select Employee Orientation. La page en mode liste Nouveaux employés à Seattle s’ouvre.The list view page for New Employees in Seattle opens.

  6. Pour terminer la session de débogage, fermez la fenêtre du navigateur ou arrêtez le débogage dans Visual Studio.To end the debugging session, close the browser window or stop debugging in Visual Studio. Quand vous appuyez sur F5, Visual Studio retire la version précédente du complément et installe la dernière.Each time that you select F5, Visual Studio will retract the previous version of the add-in and install the latest one.

  7. Vous allez travailler avec ce complément et la solution Visual Studio dans d’autres articles. Nous vous recommandons donc de retirer le complément une dernière fois quand vous avez terminé de travailler et que vous ne comptez pas le réutiliser pendant un moment.You will work with this add-in and Visual Studio solution in other articles, and it's a good practice to retract the add-in one last time when you are done working with it for a while. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions et sélectionnez Retirer.Right-click the project in Solution Explorer and select Retract.

Étapes suivantesNext steps

Dans l’article suivant de cette série, vous allez ajouter du code JavaScript au complément SharePoint et accéder aux données SharePoint avec le modèle objet JavaScript de SharePoint : Utilisation des API JavaScript SharePoint pour exploiter les données SharePoint.In the next article in this series, you'll add JavaScript to the SharePoint Add-in and access SharePoint data with SharePoint's JavaScript object model: Use the SharePoint JavaScript APIs to work with SharePoint data.