Modèles d'affichage du gestionnaire de conception SharePoint
Importante
Cette option d’extensibilité est disponible uniquement pour des expériences SharePoint classiques. Vous ne pouvez pas l’utiliser avec des expériences modernes dans SharePoint Online, telles que des sites de communication. Nous vous déconseillons d’utiliser l’expérience classique ou les techniques de personnalisation.
Découvrez les modèles d’affichage, y compris la façon dont ils sont liés aux composants WebPart de recherche et la façon dont les modèles sont structurés. Découvrez également comment mettre en correspondance des propriétés, utiliser des variables et jQuery, ainsi que créer un modèle d’affichage personnalisé dans SharePoint.
Présentation des modèles d’affichage
Les modèles d’affichage dans SharePoint sont utilisés dans les composants WebPart. Ils utilisent la technologie de recherche (désignée par le terme composants WebPart de recherche dans cet article) pour afficher les résultats d’une requête envoyée à l’index de recherche. Les modèles d’affichage contrôlent l’affichage et la présentation des propriétés gérées dans le composant WebPart. Chaque modèle d’affichage est constitué de deux fichiers : une version HTML du modèle d’affichage que vous pouvez modifier dans votre éditeur HTML et un fichier .js utilisé par SharePoint.
Remarque
Seuls les composants WebPart De recherche peuvent utiliser des modèles d’affichage. Le composant WebPart Requête de contenu n’étant pas piloté par la recherche, il n’utilise pas de modèles d’affichage.
Vous pouvez afficher les modèles d'affichage existants dans le gestionnaire de conception, mais vous ne pouvez pas les créer dans ce dernier de la même façon que vous créez des pages maîtres et des mises en page. Au lieu de cela, vous devez procéder comme suit :
Ouvrez votre lecteur réseau mappé à la galerie de pages maîtres.
Ouvrez l’un des quatre dossiers dans le dossier Modèles d’affichage.
Remarque
Le dossier que vous choisissez dépend du type de modèle d’affichage que vous voulez utiliser. Par exemple, si votre site se sert de la publication intersites, copiez un modèle d’affichage du dossier Composants WebPart de contenu. Pour plus d’informations, consultez la rubrique Référence des modèles d’affichage dans SharePoint.
Copiez le fichier HTML d'un modèle d'affichage existant semblable au modèle souhaité. L'emplacement précis vers lequel vous copiez le fichier importe peu, tant qu'il se trouve dans la galerie de pages maîtres.
Ouvrez et modifiez votre copie dans un éditeur HTML.
Lorsque vous utilisez un modèle d'affichage existant comme point de départ pour un nouveau modèle, vous bénéficiez d'informations utiles sur le processus de personnalisation dans les commentaires des modèles d'affichage par défaut et vous disposez d'une infrastructure pour les tâches de base, telles que le mappage des champs d'entrée. Cela garantit également que vos modèles utilisent la structure de page de base appropriée.
Lorsque vous créez un modèle d'affichage en copiant le fichier HTML d'un modèle existant figurant dans le dossier des modèles d'affichage situé dans la galerie de pages maîtres:
Un fichier .js qui porte le même nom est créé dans l’emplacement où vous avez copié le fichier HTML.
La totalité des balises requises par SharePoint sont ajoutées au fichier .js afin que le modèle s’affiche correctement.
Le fichier HTML et le fichier .js sont associés, de sorte que toutes les modifications ultérieures effectuées dans le fichier HTML soient synchronisées dans le fichier .js lorsque le fichier HTML est enregistré.
Remarque
La synchronisation est à sens unique. Les modifications apportées au modèle d’affichage HTML sont synchronisées dans le fichier .js associé. Contrairement aux pages maîtres et aux mises en page, lorsqu'il s'agit des modèles d'affichage, vous ne pouvez pas choisir de travailler uniquement avec le fichier .js en annulant l'association entre les fichiers. Vous devez entrer tous les codes HTML et JavaScript dans le fichier HTML.
Présentation de la relation entre les modèles d’affichage et les composants WebPart de recherche
Il existe deux types de modèles d'affichage principaux :
Les modèles de contrôle déterminent la structure globale de la présentation des résultats. Cela inclut des listes, des listes avec paginations et des diaporamas.
Les modèles d'élément déterminent le mode d'affichage de chaque résultat dans l'ensemble. Cela inclut des images, du texte, des vidéos et d'autres éléments.
Pour plus d’informations sur ces modèles d’affichage et sur d’autres modèles d’affichage, voir Informations de référence sur les modèles d’affichage dans SharePoint.
Une fois que vous avez ajouté un composant WebPart de recherche (tel que le composant WebPart de recherche de contenu) à une page, vous devez, pour configurer le composant WebPart, sélectionner à la fois un modèle d’affichage de contrôle et un modèle d’affichage d’élément, comme illustré à la figure 1.
Figure 1. Volet d’outils du composant WebPart de recherche de contenu
Le modèle d'affichage de contrôle fournit du code HTML afin de structurer la disposition globale souhaitée pour présenter les résultats de recherche. Par exemple, le modèle d'affichage de contrôle peut fournir le code HTML pour un titre et le début ou la fin d'une liste. Le modèle d’affichage de contrôle n’est rendu qu’une seule fois dans le composant WebPart.
Le modèle d'affichage d'élément fournit du code HTML qui détermine l'affichage de chaque élément dans le jeu de résultats. Par exemple, le modèle d'affichage d'élément peut fournir le code HTML pour un élément de liste contenant une image et trois lignes de texte mappées sur des propriétés gérées différentes associées à l'élément. Le modèle d'affichage d'élément est rendu une fois pour chaque élément du jeu de résultats. Ainsi, si le jeu de résultats contient 10 éléments, le modèle d'affichage d'élément crée une section de code HTML dix fois.
Lorsqu’ils sont utilisés ensemble de cette manière, le modèle d’affichage de contrôle et le modèle d’affichage d’élément sont combinés pour créer un bloc de code HTML cohésif qui est affiché dans le composant WebPart, comme illustré à la figure 2.
Figure 2. Sortie HTML combinée d’un modèle d’affichage de contrôle et d’un modèle d’affichage d’élément
Pour plus d’informations sur les modèles d’affichage, consultez la section « Composants WebPart et modèles d’affichage pilotés par la recherche » dans Vue d’ensemble du modèle de page SharePoint.
Comprendre la structure des modèles d'affichage
Le fichier HTML utilisé pour un modèle d'affichage est un document HTML formé, mais il ne représente pas une page web HTML complète. SharePoint convertit les éléments du fichier HTML du modèle d'affichage en JavaScript. Cette section décrit les quatre parties principales d’un modèle d’affichage.
Balise de titre
Le texte de la balise <title> au sein d’un fichier de modèle d’affichage est utilisé comme nom d’affichage dans la section Modèles d’affichage du volet d’édition du composant WebPart lorsque le composant WebPart de recherche est en mode Édition. L’exemple suivant concerne le modèle d’affichage d’élément nommé Item_Picture3Lines.html :
<title>Picture on left, 3 lines on right</title>
Propriétés de l’en-tête
Immédiatement après la balise <title>, un ensemble d’éléments personnalisés liés par la balise suivante apparaît :
<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
…
</mso:CustomDocumentProperties>
</xml><![endif]-->
Ces éléments et leurs propriétés fournissent des informations importantes sur le modèle d'affichage à l'environnement SharePoint. Le tableau 1 décrit les propriétés personnalisées utilisées dans les modèles d'affichage.
Remarque
Les propriétés personnalisées ne sont pas toutes utilisées dans chacun des modèles d’affichage. Certaines propriétés peuvent également être modifiées en modifiant les propriétés du fichier de modèle d’affichage dans le gestionnaire de conception.
Tableau 1. Liste des entrées CustomDocumentProperties
| Propriété | Description |
|---|---|
| TemplateHidden |
Valeur booléenne qui indique s’il faut masquer le modèle d’affichage de la liste des modèles disponibles dans le composant WebPart. Cette valeur peut être modifiée dans les propriétés du fichier de modèle d'affichage. |
| ManagedPropertyMapping |
Mappe les champs affichés par les éléments de résultat de recherche sur les propriétés disponibles pour JavaScript. Utilisé uniquement dans les modèles d'élément. |
| MasterPageDescription |
Fournit une description conviviale du modèle d'affichage. Les utilisateurs peuvent la voir dans l'environnement d'édition de SharePoint. Cette valeur peut être modifiée dans les propriétés du fichier de modèle d'affichage. |
| ContentTypeId |
ID du type de contenu associé au modèle d'affichage. |
| TargetControlType |
Indique le contexte dans lequel le modèle d'affichage est utilisé. Cette valeur peut être modifiée dans les propriétés du fichier de modèle d'affichage. |
| HtmlDesignAssociated |
Valeur booléenne indiquant si un fichier HTML de modèle d'affichage est associé à un fichier .js. |
| HtmlDesignConversionSucceeded |
Indique si le processus de conversion a réussi. Cette valeur est automatiquement ajoutée au fichier par SharePoint et elle est utilisée uniquement dans les modèles d'affichage personnalisés. |
| HtmlDesignStatusAndPreview |
Contient l'URL vers le fichier HTML et le texte de la colonne Statut ( La conversion a réussi ou Avertissements et erreurs). Cette valeur est automatiquement ajoutée au fichier par SharePoint et elle est utilisée uniquement dans les modèles d’affichage personnalisés. |
Bloc de script
À l’intérieur de la balise <body>, vous pouvez observer la balise <script> suivante :
<script>
$includeLanguageScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Language Files/{Locale}/CustomStrings.js");
</script>
Par défaut, cette ligne est incluse dans tous les modèles d’affichage. Vous pouvez ajouter davantage de lignes de code à l’intérieur de la balise <script> pour référencer des fichiers CSS ou autres fichiers JavaScript en dehors de votre fichier principal de modèle d’affichage HTML. Le tableau 2 décrit des exemples permettant d’apprendre à inclure d’autres ressources.
Tableau 2. Exemples d’inclusion de ressources externes dans la balise de <script>
| Si vous voulez inclure les éléments suivants : | Utilisez le code suivant : |
|---|---|
| Un fichier JavaScript faisant partie de la collection de sites actuelle |
$includeScript(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyScripts.js"); |
| Un fichier JavaScript externe |
$includeScript(this.url, "http://www.contoso.com/ExternalScript.js"); |
| Un fichier CSS faisant partie de la collection de sites actuelle |
$includeCSS(this.url, "~sitecollection/_catalogs/masterpage/Display Templates/Content Web Parts/MyCSS.css"); |
| Un fichier CSS qui se trouve dans un emplacement relatif au modèle d’affichage actuel |
$includeCSS(this.url,"../../MyStyles/MyCSS.css"); |
Remarque
Si l’approbation du contenu est obligatoire pour les éléments de la galerie de pages maîtres, tous les fichiers de ressources (y compris les fichiers CSS et .js) doivent être publiés avant d’être disponibles sur les pages maîtres et les mises en page. Pour plus d’informations, reportez-vous à Exiger l’approbation d’éléments dans une liste ou une bibliothèque de site.
Bloc DIV
Après la balise <script> se trouve une balise <div> avec un ID. Par défaut, l’ID pour cette balise <div> correspond au nom du fichier HTML. Tout HTML ou code que vous souhaitez voir fourni par le modèle d’affichage doit être inclus dans cette balise <div>. Cependant, la balise elle-même n’est pas incluse dans la marque de révision produite au moment de l’exécution de la page web.
Remarque
Si vous voulez attribuer un style CSS ou un ID au bloc HTML restitué sur la page au moment de l’exécution, vous pouvez ajouter une nouvelle balise à l’intérieur de la première balise <div>. Vous pouvez également attribuer un style CSS ou un ID au code HTML qui entoure la variable _#= ctx.RenderGroups(ctx) =#_ dans le modèle de contrôle. La variable _#= ctx.RenderGroups(ctx) =#_ est utilisée pour afficher le code HTML qui entoure les résultats de la requête produits par le modèle d’élément.
Dans la première <balise div> , vous verrez du code à l’intérieur des blocs de commentaires qui commencent par <!--#_ et se terminent par _#-->. Vous utilisez du code JavaScript à l’intérieur de ces blocs, et HTML en dehors des blocs. Vous pouvez également utiliser ces blocs pour contrôler le code HTML avec des instructions conditionnelles. Pour ce faire, utilisez un bloc de commentaires avec l’instruction conditionnelle et un crochet ouvrant suivi de votre HTML, suivi d’un autre bloc de commentaires avec le crochet fermant. Dans l’exemple suivant, la balise d’ancrage n’est produite sur la page que si la valeur pour l’objet linkURL n’est pas vide.
<!--#_
if(!linkURL.isEmpty)
{
_#-->
<a class="cbs-pictureImgLink" href="_#= linkURL =#_" title="_#= $htmlEncode(line1.defaultValueRenderer(line1)) =#_" id="_#= pictureLinkId =#_">
<!--#_
}
_#-->
Mise en correspondance de propriétés d’entrée et obtention de leurs valeurs
La section d'en-tête d'un modèle d'affichage d'élément possède une propriété de document personnalisée nommée ManagedPropertyMapping. Cette propriété prend les propriétés gérées utilisées par la recherche et les mappe sur des valeurs qui peuvent être utilisées par le modèle d'affichage. La propriété est une liste de valeurs séparées par des virgules qui utilise le format suivant : ' nom d'affichage de la propriété'{ nom de la propriété}:' propriété gérée'. Par exemple : 'Picture URL'{Picture URL}:'PublishingImage;PictureURL;PictureThumbnailURL'.
Examinons le format plus en détail :
Le nom d’affichage de la propriété est le nom de la propriété affiché dans le Panneau de modification du composant WebPart lorsque le modèle d’affichage est sélectionné.
Le nom de la propriété est un identifiant qui utilise les ressources de chaînes localisées pour rechercher le nom de la propriété gérée. Il s’agit également de la valeur qui apparaît dans la section Mappages de propriétés du menu des paramètres du composant WebPart. Lorsque vous modifiez les paramètres d’un composant WebPart, vous pouvez modifier cette valeur pour modifier la propriété managée associée au champ qui apparaît dans le composant WebPart.
La propriété gérée est une chaîne d'une ou plusieurs propriétés gérées, séparées par des points-virgules. Au moment de l'exécution, la liste est évaluée de gauche à droite et la première valeur qui correspond au nom de la propriété gérée de l'élément de recherche actuel est mappée sur cet emplacement. Cela vous permet d'écrire un modèle d'affichage qui peut fonctionner avec plusieurs types d'éléments et d'utiliser un rendu cohérent si des propriétés compatibles sont présentes.
Après avoir mappé une propriété, vous pouvez obtenir sa valeur dans le script à l’aide du code suivant : var pictureURL = $getItemValue(ctx, "Picture URL");
Le deuxième paramètre transmis à $getItemValue() doit correspondre au nom d'affichage de la propriété entre guillemets simples utilisé dans l'élément ManagedPropertyMapping. Dans cet exemple, Picture URL est le nom de la propriété transmis à $getItemValue().
Ce code renvoie un objet d'information de valeur ( valueInfoObj). Cet objet comporte une représentation brute de la valeur d'entrée, ainsi que la valeur avec un codage qui lui est appliqué par défaut.
Vous pouvez utiliser des variables dans les sections de code JavaScript comme vous le feriez habituellement, afin de manipuler des variables et de créer des chaînes HTML destinées à être rendues sur la page au moment de l'exécution. En revanche, pour référencer des variables déclarées dans le script directement dans le code HTML, vous devez utiliser le format suivant : #= nomVariable =#. Par exemple, pour utiliser la variable pictureURL comme la valeur d'une image, vous devez utiliser le code HTML suivant : <img src="_#= pictureURL =#_" />
Utiliser jQuery avec des modèles d'affichage
Vous pouvez utiliser jQuery avec vos modèles d'affichage. Toutefois, tenez compte de deux facteurs importants :
Pour inclure des bibliothèques jQuery dans votre modèle d’affichage, suivez les instructions décrites dans la section Bloc de script, plus haut dans cet article.
Si vous utilisez des sélecteurs d’ID dans jQuery, utilisez le code suivant pour créer une variable pour l’ID :
var containerQueryId = '#' + '_#= containerId =#_';Utilisez le code suivant pour référencer le sélecteur dans jQuery :
$('_#= containerQueryId =#_')
Créer un modèle d'affichage
Pour pouvoir créer un modèle d'affichage à l'aide de la procédure suivante, vous devez disposer d'un lecteur réseau mappé qui pointe vers la galerie des pages maîtres. Pour plus d’informations, voir Guide pratique pour mapper un lecteur réseau à la galerie de pages maîtres SharePoint.
Pour créer un modèle d'affichage
À l'aide de l'Explorateur Windows, ouvrez le lecteur réseau mappé à la galerie de pages maîtres.
Ouvrez le dossier Modèles d’affichage, puis ouvrez le dossier Composants WebPart de contenu.
Copiez le fichier HTML pour obtenir un modèle d’affichage semblable à ce que vous voulez créer. Pour obtenir la liste des modèles d’affichage par défaut et leurs descriptions, voir Informations de référence sur les modèles d’affichage dans SharePoint.
À ce stade, SharePoint copie le fichier HTML dans un fichier .js qui porte le même nom. Par exemple, si le fichier HTML copié est nommé Item_Picture3Line_copy.html, un fichier .js correspondant nommé Item_Picture3Lines_copy.js est également créé. Si vous décidez de renommer le fichier, le nom du fichier .js correspondant est aussi modifié.
Pour personnaliser le modèle d'affichage, modifiez le fichier HTML qui réside sur le serveur à l'aide d'un éditeur HTML afin d'ouvrir et de modifier le fichier HTML dans le lecteur mappé. Chaque fois que vous enregistrez le fichier HTML, toutes les modifications sont synchronisées dans le fichier .js associé.
Accédez à votre site de publication.
Dans le coin supérieur droit de la page, sélectionnez Paramètres, puis Gestionnaire de conception.
In Design Manager, in the left navigation pane, choose Edit Display Templates. Your HTML file now appears with a Status column that shows one of two statuses:
Avertissements et erreurs
La conversion a réussi
Remarque
Contrairement aux pages maîtres et aux mises en page, vous ne pouvez pas utiliser la page d’aperçu pour obtenir un aperçu côté serveur instantané de votre modèle d’affichage. Pour afficher un aperçu du modèle d’affichage, vous devez ajouter un composant WebPart Recherche de contenu à une page, puis appliquer le modèle d’affichage dans le volet d’édition du composant WebPart Recherche de contenu. S’il existe des erreurs dans le modèle d’affichage, le composant WebPart Recherche de contenu affiche un message d’erreur. Les erreurs doivent être corrigées pour que le modèle d'affichage puisse s'afficher correctement.
- Pour corriger les erreurs, modifiez le fichier HTML qui réside sur le serveur à l'aide d'un éditeur HTML afin d'ouvrir et de modifier le fichier HTML dans le lecteur mappé. Enregistrez le modèle d’affichage, puis rechargez la page qui contient le composant WebPart Recherche de contenu qui utilise le modèle d’affichage.
Voir aussi
- Vue d'ensemble du gestionnaire de conception dans SharePoint
- Développer la conception de site dans SharePoint
- Procédure : Convertir un fichier HTML en page maître dans SharePoint
- Procédure : Créer une mise en page dans SharePoint
- Fonctionnalités de personnalisation et la conception de 2013 le gestionnaire de conception SharePoint