Créer des composants de complément à installer avec votre complément pour SharePoint
Les composants de complément vous permettent d'illustrer l'expérience offerte à l'utilisateur du complément directement dans les pages du site web SharePoint. Un composant de complément affiche la page web (généralement un formulaire interactif ou un affichage dynamique de données) que vous spécifiez à l'aide d'un IFrame (aussi appelé cadre) dans une page du site web hôte.
Pour obtenir plus de contexte sur les composants de complément, reportez-vous aux articles suivants :
- Accéder au complément à partir de l'interface utilisateur
- Conception de l'expérience utilisateur pour les compléments dans SharePoint
- Extension de l’interface SharePoint dans les compléments
La figure suivante illustre la manière dont le composant de complément est affiché dans une page SharePoint.
Contenu de composant de complément affiché dans une page SharePoint
Un composant de complément est implémenté avec la classe ClientWebPart et, comme tous les composants WebPart, il est disponible dans la galerie de composants WebPart après qu’un utilisateur a installé le complément SharePoint qui l’inclut. Vos utilisateurs peuvent personnaliser davantage le composant de complément à l’aide des propriétés que vous fournissez. (Pour obtenir un exemple de propriétés configurables dans un composant de complément, voir la figure page SharePoint hébergeant un composant de complément de base plus loin dans cet article.)
L’exemple de cet article utilise une page web hébergée sur un serveur distant, et non sur SharePoint, comme page de contenu. N’oubliez pas que vous pouvez également utiliser des pages SharePoint pour héberger le contenu du composant de complément, comme décrit dans la section Autres scénarios courants de composants de complément plus loin dans cet article.
Conditions requises pour utiliser l’exemple de cet article
Pour suivre les étapes de cet exemple, vous avez besoin des éléments suivants :
- Visual Studio
- Outils de développement Microsoft Office pour Visual Studio
- Un environnement de développement SharePoint. Si vous avez besoin d’aide pour configurer un environnement de développement, voir Deux types de compléments SharePoint : hébergés par SharePoint et hébergés par un fournisseur.
Créer un composant de complément à installer sur le site web hôte
Plusieurs tâches sont à réaliser pour créer et installer votre composant de complément sur le site web hôte :
- Créer les projets de Complément SharePoint et de site web distant.
- Ajouter un formulaire pour le contenu du composant de complément.
- Ajouter le composant de complément au projet de Complément SharePoint.
Une fois les tâches terminées, votre composant de complément doit ressembler à la figure suivante lorsque le composant de complément est en mode édition. Nous pouvons y voir (1) le contenu du complément affiché dans une page SharePoint et (2) les propriétés personnalisées du composant de complément.
Page SharePoint hébergeant un composant de complément de base
Ajouter un formulaire pour le contenu du composant de complément
Créez un complément SharePoint hébergé par un fournisseur, en suivant les étapes décrites dans l’article Commencer à créer des compléments hébergés par un fournisseur pour SharePoint, mais nommez le projet TestAppPart.
Une fois la solution Visual Studio créée, cliquez avec le bouton droit de la souris sur le projet d’application web (et non le projet de complément SharePoint) et ajoutez un nouveau formulaire web en sélectionnant Ajouter>Nouvel élément>Web>Formulaire web. Nommez le formulaire AppPartContent.aspx.
Dans le fichier AppPartContent.aspx, remplacez l’ensemble de l’élément HTML et ses enfants par le code HTML suivant. Ne modifiez pas les balises situées au-dessus de l’élément HTML. Le code HTML contient un JavaScript qui effectue les tâches suivantes :
- Il extrait les valeurs des propriétés par défaut de la chaîne de requête.
- Il affiche les valeurs des propriétés
Notez que le code attend certains paramètres dans la chaîne de requête. Le composant de complément fournit ses propriétés personnalisées via la chaîne de requête, afin que la page web puisse les utiliser. La tâche suivante explique comment déclarer des propriétés personnalisées et les rendre disponibles pour la page web du complément.
<html> <body> <div id="content"> <!-- Placeholders for properties --> String property: <span id="strProp"></span><br /> Integer property: <span id="intProp"></span><br /> Boolean property: <span id="boolProp"></span><br /> Enumeration property: <span id="enumProp"></span><br /> </div> <!-- Main JavaScript function, controls the rendering logic based on the custom property values --> <script lang="javascript"> "use strict"; var params = document.URL.split("?")[1].split("&"); var strProp; var intProp; var boolProp; var enumProp; // Extracts the property values from the query string. for (var i = 0; i < params.length; i = i + 1) { var param = params[i].split("="); if (param[0] == "strProp") strProp = decodeURIComponent(param[1]); else if (param[0] == "intProp") intProp = parseInt(param[1]); else if (param[0] == "boolProp") boolProp = (param[1] == "true"); else if (param[0] == "enumProp") enumProp = decodeURIComponent(param[1]); } document.getElementById("strProp").innerText = strProp; document.getElementById("intProp").innerText = intProp; document.getElementById("boolProp").innerText = boolProp; document.getElementById("enumProp").innerText = enumProp; </script> </body> </html>Enregistrez et fermez le fichier.
Ajouter le composant de complément au projet de complément SharePoint
Cliquez avec le bouton droit sur le projet de complément SharePoint (et non sur le projet d’application web), puis sélectionnez Ajouter un>nouveau composant> WebPartOffice/SharePoint>Client (site web hôte). (« Composant WebPart client » est une autre façon de désigner un « composant de complément ».)
Nommez le composant Composant de complément de base.
Dans la boîte de dialogue Spécifier la page du composant WebPart client , sélectionnez Sélectionner ou entrer une URL pour une page web existante. Sélectionnez la page TestAppWebPart/AppPartContent.aspx dans la liste déroulante. (Une fois votre choix effectué, l'URL de la page peut apparaître dans la zone, dans laquelle « TestAppWebPart » est remplacé par ~remoteAppUrl et où {StandardTokens } est ajouté pour les paramètres de requête.)
Sélectionnez Terminer.
Cliquez avec le bouton droit de la souris sur Composant de complément de base dans l’Explorateur de solutions, puis sélectionnez Propriétés.
Dans le volet Propriétés, sélectionnez Propriétés personnalisées, puis sélectionnez le bouton de légende (...).
À partir de la boîte de dialogue Propriétés personnalisées, ajoutez quatre propriétés personnalisées au composant de complément. Vous devez définir cinq attributs de chacune des quatre propriétés personnalisées. Les noms et les valeurs des attributs sont répertoriés dans le tableau 1. Pour créer les propriétés, suivez la procédure ci-dessous :
Cliquez sur Ajouter.
Dans la liste des attributs, sélectionnez le premier attribut de la table 1 : DefaultValue (Valeur par défaut).
Définissez la valeur, par exemple Valeur de chaîne par défaut.
Sélectionnez l'attribut suivant, Name et définissez sa valeur, par exemplestrProp.
Continuez avec les attributs Type, WebCategory et WebDisplayName.
Sélectionnez à nouveau Ajouter et répétez le processus pour les quatre lignes du tableau 1. Ne fermez pas la boîte de dialogue.
Tableau 1. Attributs des propriétés personnalisées du composant de complément
DefaultValue Nom Type WebCategory WebDisplayName Valeur par défaut de la chaîne strProp string Catégorie de composant de complément de base Propriété de type chaîne 0 intProp int Catégorie de composant de complément de base Propriété de type entier false boolProp boolean Catégorie de composant de complément de base Propriété de type booléen 1st enumProp enum Catégorie de composant de complément de base Propriété de type énumération À ce stade, la boîte de dialogue doit avoir l'aspect suivant :
Boîte de dialogue Propriétés personnalisées pour un composant WebPart client
Sélectionnez la propriété enumProp, l’attribut EnumItems, puis le bouton de légende (...).
Utilisez l' éditeur de collections ClientWebPartEnumItem pour ajouter trois éléments. Vous devez définir deux attributs de chacun d'entre eux. Les noms et les valeurs des attributs sont répertoriés dans le tableau 1. Pour créer les propriétés, suivez la procédure ci-dessous :
Cliquez sur Ajouter.
Dans la liste des attributs, sélectionnez le premier attribut de la table 2 : Value.
Définissez la valeur de l'attribut, par exemple, 1st.
Sélectionnez l'attribut suivant, WebDisplayName et définissez sa valeur, par exemple Première option.
Sélectionnez de nouveau Ajouter et répétez le processus pour toutes les lignes du Tableau 2.
Tableau 2. Éléments enum de la propriété enumProp
Valeur WebDisplayName 1st Première option 2nd Deuxième option 3rd Troisième option La boîte de dialogue doit avoir l'aspect suivant lorsque vous avez terminé :
Éditeur de collections ClientWebPartEnumItem
Sélectionnez OK pour fermer la boîte de dialogue, puis sélectionnez une nouvelle fois OK pour fermer la boîte de dialogue Propriétés personnalisées.
Visual Studio génère le code XML suivant pour le fichier elements.xml du composant de complément (retours à la ligne ajoutés pour plus de clarté). Notez que l'attribut Title de l'élément ClientWebPart est défini sur « Basic add-in part Title » (Titre de composant de complément de base) et que la description indique « Basic add-in part Description » (Description du composant de complément de base). Supprimez le mot « Title » du premier, puis remplacez le deuxième par un composant de complément De base.
<?xml version="1.0" encoding="UTF-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<ClientWebPart
Name="Basic add-in part"
Title="Basic add-in part Title"
Description="Basic add-in part Description" >
<!-- The properties are passed through the query string
using the following notation: _propertyName_
in the Src property of the Content element.
-->
<Content
Src="~remoteAppUrl/AppPartContent.aspx?strProp=_strProp_&amp;intProp=_intProp_&amp;boolProp=_boolProp_&amp;enumProp=_enumProp_"
Type="html"/>
<Properties>
<Property
Name="strProp"
Type="string"
RequiresDesignerPermission="true"
DefaultValue="String default value"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type string.">
</Property>
<Property
Name="intProp"
Type="int"
RequiresDesignerPermission="true"
DefaultValue="0"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type integer.">
</Property>
<Property
Name="boolProp"
Type="boolean"
RequiresDesignerPermission="true"
DefaultValue="false"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type boolean.">
</Property>
<Property
Name="enumProp"
Type="enum"
RequiresDesignerPermission="true"
DefaultValue="1st"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type enum.">
<EnumItems>
<EnumItem WebDisplayName="First option" Value="1st"/>
<EnumItem WebDisplayName="Second option" Value="2nd"/>
<EnumItem WebDisplayName="Third option" Value="3rd"/>
</EnumItems>
</Property>
</Properties>
</ClientWebPart>
</Elements>
Définir la page de démarrage du complément sur la page d’accueil du site web hôte
L’exemple de complément SharePoint n’a pas de site web de complément et son application web distante existe uniquement pour héberger le formulaire. Ce complément n'offre pas un environnement immersif en pleine page. Ainsi, la page de démarrage du complément doit être configurée comme page d’accueil du site web hôte.
Pour commencer, sélectionnez le projet de complément SharePoint (et non le projet d’application web) dans Explorateur de solutions et copiez la valeur de la propriété URL du site, y compris le protocole (par exemplehttps://contoso.sharepoint.com) dans le Presse-papiers.
Ouvrez le manifeste du complément, puis collez l'URL dans la zone Page de démarrage.
Vous pouvez également supprimer la page Default.aspx du projet d’application web, car elle n’est pas utilisée dans le complément SharePoint.
Créer et tester la solution
Sélectionnez la touche F5.
Remarque
Quand vous sélectionnez F5, Visual Studio génère la solution, installe le complément et ouvre la page des autorisations pour le complément.
Sélectionnez le bouton Approuver.
Ajoutez le composant de complément de base à partir de la galerie de composants de complément. Pour obtenir des instructions détaillées, reportez-vous à Ajouter un composant de complément à une page.
Lorsque le complément est installé sur le site web hôte, le composant de complément de base est disponible dans la galerie de composants de complément. Il doit ressembler beaucoup à la figure suivante.
Composant de complément dans la galerie de composants de compléments
Une fois le composant de complément ajouté, sélectionnez la flèche vers le bas située à droite du titre Composant de complément de base, puis sélectionnez Modifier le composant WebPart.
Le composant de complément doit apparaître en mode Édition.
Ouvrez Catégorie de composant de complément de base et modifiez certaines valeurs de propriétés.
Sélectionnez OK pour enregistrer les modifications et vérifiez que les propriétés ont changé dans le composant de complément.
Lorsque vous mettez fin à la session de débogage et n'allez plus utiliser F5 pendant un temps sur ce projet, nous vous recommandons de retirer le Complément SharePoint une dernière fois pour vous assurer que le composant de complément de test a été supprimé de votre page d'accueil. Cliquez avec le bouton droit sur le projet complément SharePoint et sélectionnez Retirer.
Dépannage de la solution
| Problème | Solution |
|---|---|
| Le composant de complément n’affiche aucun contenu. Le composant de complément affiche l’erreur suivante : La navigation vers la page web a été annulée. Cette erreur se produit parce que le navigateur a bloqué la page de contenu. | Activez le contenu mixte. La procédure peut être différente selon le navigateur que vous utilisez : Internet Explorer 9 et 10 affichent le message suivant en bas de la page : Seul le contenu sécurisé s’affiche. Sélectionnez Afficher tout le contenu pour afficher le contenu du composant de complément. Internet Explorer 8 shows a dialog box with the following message: Do you want to view only the webpage content that was delivered securely? Select No to display the add-in part content. Sinon, vous pouvez activer le contenu mixte dans la zone Internet dans laquelle vous travaillez. Pour la plupart des développeurs, cette zone Internet est un intranet local. Si ce n'est pas le cas pour vous, remplacez Intranet local par la zone Internet dans laquelle vous travaillez. Dans Internet Explorer, sélectionnez Outils>Options Internet. Dans la boîte de dialogue Options Internet , sous l’onglet Sécurité , sélectionnez Intranet local, puis sélectionnez le bouton Niveau personnalisé . Dans la boîte de dialogue Paramètres de sécurité, activez Afficher un contenu mixte dans la section Divers. |
Autres scénarios courants utilisant des composants de complément
Cet article montre comment créer un composant de complément de base avec des propriétés personnalisées à l'aide d'une page web distante en tant que page de contenu. Vous pouvez également explorer les scénarios et détails suivants concernant les composants de complément.
Utiliser une page SharePoint en tant que page de contenu
Dans la plupart des cas, une page web ne peut pas être affichée dans un cadre si elle renvoie un en-tête HTTP X-Frame-Options dans la réponse. Par défaut, les pages SharePoint contiennent l'en-tête X-Frame-Options. Si vous utilisez une page web SharePoint hébergée sur le site web de complément, vous pouvez rencontrer l’erreur suivante (illustrée dans la figure suivante) : Ce contenu ne peut pas être affiché dans un cadre.
Composant de complément ne pouvant pas afficher son contenu dans un cadre
N’oubliez pas que certains scénarios sont vulnérables aux attaques clickjacking lorsque les pages web sont affichées dans un cadre. Examinez vos scénarios de composant de complément avec soin pour vous assurer qu'il n'existe aucun risque d'attaque de type détournement de clic.
Si votre page hébergée sur le site web du complément n’est pas vulnérable aux attaques ClickJacking, vous pouvez utiliser le composant WebPart AllowFraming pour supprimer l’en-tête X-Frame-Options de la réponse de votre page. L’exemple de code suivant montre comment utiliser le composant WebPart AllowFraming sur une page SharePoint. Copiez ce balisage dans la page qui est hébergée sur le site web de complément. Placez-le immédiatement au-dessus du premier élément asp:content de la page. Il ne doit pas être le composant enfant d'un autre élément.
<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />
Pour savoir comment utiliser une page SharePoint comme page de contenu, vous pouvez télécharger un exemple de code de composant de complément destiné à afficher le contenu du site web de complément sur le site web hôte à l’aide d’un composant de complément.
Redimensionner le composant de complément
Si vous utilisez du contenu dynamique dans votre composant de complément, le contenu peut changer de largeur et de hauteur. En raison de la nature dynamique du contenu, il peut ne pas tenir dans le cadre. Vous pouvez également utiliser trop d’espace. Avec le contenu dynamique, il peut être difficile de spécifier une taille fixe dans votre déclaration de composant de complément. Toutefois, vous pouvez redimensionner le cadre en fonction de la largeur et de la hauteur du contenu.
Vous pouvez utiliser des messages POST de votre page web de contenu pour spécifier la taille du cadre. L'exemple de JavaScript suivant montre comment envoyer un message POST pour redimensionner le cadre dans lequel votre composant de complément est hébergé. En règle générale, le cas se présente dans une méthode JavaScript dans un fichier JavaScript que vous appelez à partir de la page. Par exemple, la page peut contenir un contrôle dans lequel l'utilisateur spécifie la taille de la fenêtre du composant de complément. La méthode personnalisée est ensuite appelée à partir du gestionnaire onchange du contrôle.
Pour obtenir un exemple complet de composant de complément qui redimensionne dynamiquement les composants, consultez l’exemple de code : redimensionner les composants de complément de façon dynamique dans les compléments SharePoint.
window.parent.postMessage("<message senderId={SenderId}>resize(120, 300)</message>", {hostweburl});
Dans l’exemple ci-dessus, la valeur senderId est automatiquement définie sur la chaîne de requête de la page par le code du composant de complément lorsque la page est affichée. Votre page doit simplement lire la valeur SenderId à partir de la chaîne de requête et l'utiliser lors d'une demande de redimensionnement. Vous pouvez récupérer l'URL du site web hôte à partir de la chaîne de requête en ajoutant le jeton StandardTokens ou HostUrl à l'attribut Src dans la définition du composant de complément.
Utiliser la feuille de style SharePoint dans le contenu de votre composant de complément
Étant donné que votre composant de complément est hébergé dans une page SharePoint, vous pouvez faire en sorte que le contenu du composant de complément ressemble à celui qu’il fait partie de la page. L'une des façons d'obtenir une apparence similaire consiste à utiliser les mêmes classes de style que la page SharePoint qui héberge le composant de complément. Pour rendre la feuille de style du site web SharePoint disponible pour le composant de complément, ajoutez une référence au fichier defaultcss.ashx à partir du site web de complément.
Pour savoir comment référencer le fichier defaultcss.ashx dans vos compléments SharePoint, consultez l’article Utilisation d’une feuille de style de site web SharePoint dans les compléments SharePoint.
Pour obtenir un composant de complément qui référence la feuille de style, téléchargez l’exemple de code : afficher le contenu d’une page web distante à l’aide du composant de complément cafetière.
Détecter le passage en mode d’édition du composant de complément
Les utilisateurs peuvent modifier le composant de complément pour modifier ses propriétés. Par exemple, un utilisateur peut modifier l'une des propriétés Apparence ou Disposition. Si votre composant de complément est en mode d’édition, vous voudrez peut-être modifier la logique de rendu ou empêcher certains traitements inutiles de se produire. Prenez, par exemple, un composant de complément qui appelle une base de données principale à chaque rechargement de la page hôte. La modification d'une valeur de propriété de composant de complément en mode d'édition entraîne le rechargement de la page, mais vous ne souhaitez peut-être pas que l'appel réseau soit déclenché dans ce cas. Vous pouvez utiliser le jeton editMode pour détecter si les utilisateurs sont en train de modifier votre composant de complément.
Pour utiliser le jeton editMode, ajoutez un paramètre de chaîne de requête à l'attribut Src de l'élément Content dans la déclaration du composant de complément.
<Content Src="content_page_url&amp;editmode=_editMode_">
Le jeton editMode permet à votre page de contenu de déterminer si le composant de complément est en mode d'édition. Si tel est le cas, le jeton editMode est résolu en 1 ; sinon, il est résolu en 0.