L'élément personnalisé <devsite-catalog> fournit un contenu dynamique filtrable qui inclut une interface utilisateur de filtrage à l'échelle de la plate-forme. Il interroge le contenu appartenant au site DevSite pour charger des ressources liées à un sujet particulier sur une page DevSite. Cet élément personnalisé peut charger des ressources à partir de n'importe quel locataire DevSite, ainsi que des ressources externes qui ont été ajoutées au corpus de contenu externe DevSite.
Utilisation
Pour commencer à utiliser l'élément personnalisé <devsite-catalog>, procédez comme suit:
- Ajoutez l'élément personnalisé à votre page.
- Isolez votre ensemble de données à l'aide d'une requête de contenu dynamique.
- Ajoutez des filtres.
- Sélectionnez vos options d'affichage.
- Ajoutez des tags à vos contenus.
- Ajustez la mise en page.
Ajouter l'élément personnalisé
Ajoutez l'élément personnalisé <devsite-catalog> à votre page, à l'emplacement souhaité.
HTML
Pour les pages HTML, l'élément personnalisé peut être ajouté comme n'importe quel autre élément HTML:
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
YAML
Pour une ligne de page de destination comportant du contenu supplémentaire lié à l'élément personnalisé, utilisez une ligne d'un seul élément avec l'option description-100 issue des options de ligne de la page de destination.
rows:
- options:
- description-100
heading: Row-level heading
description: >
Row-level description with an overview of the catalog.
items:
- heading: Catalog heading
description: >
<p>Additional lead-in copy.</p>
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
Vous pouvez également utiliser un champ custom_html si vous n'avez pas besoin d'autres champs au niveau de l'article, tels que heading ou description:
rows:
- custom_html: >
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
Markdown
Pour les fichiers Markdown, l'élément personnalisé doit être encapsulé dans un élément <div> ou <section>:
<div>
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
</div>
Isoler votre ensemble de données
Déterminez une requête de contenu dynamique qui isole l'ensemble de données complet que vous souhaitez mettre à la disposition de votre catalogue, puis ajoutez-le à l'attribut de requête de votre nouveau catalogue.
Par exemple, pour ajouter à votre page un catalogue de tous les produits listés sur developers.google.com, ajoutez le catalogue suivant à votre page.
<devsite-catalog query="type:product"></devsite-catalog>
Ajouter des filtres
Pour ajouter des filtres à votre catalogue, suivez les instructions ci-dessous pour chacune des options suivantes:
Une zone de saisie de texte Section de filtres de case à cocher sur le côté
Filtre de saisie de texte
Ajoutez une zone de saisie qui filtre les résultats à mesure que l'utilisateur saisit du texte. La zone de filtrage fait correspondre le texte de l'utilisateur dans le titre, la description et les mots clés de chaque résultat.
<devsite-catalog query="type:product">
<input type="text" placeholder="Filter results">
</devsite-catalog>
Filtres de cases à cocher
Dans votre élément <devsite-catalog>, ajoutez un élément <select> pour chaque dimension filtrable comme le type de document, le produit et le langage de programmation. L'attribut name détermine la dimension de filtrage, qui correspond à un espace de noms de mot clé structuré ou à un nom de champ DevSite tel que keywords. Spécifiez un libellé de dimension pour vos lecteurs à l'aide de l'attribut label. Veillez également à spécifier l'attribut multiple pour chaque élément <select> afin de vous assurer que l'interface utilisateur du filtre générée est correcte.
Ajoutez un élément <option> pour chaque valeur de filtre dans la dimension spécifiée dans l'élément parent <select>. Spécifiez la valeur filtrable dans l'attribut "value" de chaque <option>. Ajoutez des étiquettes de filtre lisibles entre vos balises <option>. ceux-ci seront traduits si votre page est localisée.
Le code suivant ajoute une section de filtres de type de document et de mots clés dans une UI de filtrage à côté des résultats:
<devsite-catalog query="project_url:/devsite">
<select name="doctype" label="Choose a content type" multiple>
<option value="BestPractices">Best Practices</option>
<option value="Blueprint">Blueprint</option>
<option value="Concept">Concept</option>
<option value="Pattern">Pattern</option>
<option value="ReferenceArchitecture">Reference Architecture</option>
<option value="Tutorial">Tutorial</option>
</select>
<select name="keywords" label="Choose a keyword" multiple>
<option value="BestPractices">Best Practices</option>
<option value="Blueprint">Blueprint</option>
<option value="Concept">Concept</option>
<option value="Pattern">Pattern</option>
<option value="ReferenceArchitecture">Reference Architecture</option>
<option value="Tutorial">Tutorial</option>
</select>
</devsite-catalog>
Filtres de cases à cocher initiaux
L'attribut initial-checkbox-filters détermine les filtres de cases à cocher numériques à afficher lors du chargement initial. La valeur par défaut est 3.
<devsite-catalog query="project_url:/devsite" initial-checkbox-filters="5">
...
</devsite-catalog>
Sélectionner vos options d'affichage
<devsite-catalog> est compatible avec toutes les options d'affichage et les attributs d'élément personnalisés pour le widget de contenu dynamique.
Utilisez l'attribut fields pour spécifier les données que vous souhaitez afficher sur la fiche de votre catalogue. En plus du fields documenté pour <devsite-dynamic-content>, vous pouvez spécifier l'un des espaces de noms de mots clés structurés documentés pour afficher les tags appliqués à chaque document dans cet espace de noms. Par exemple, si vous spécifiez product, tous les tags de produit appliqués à chaque page seront affichés sur la fiche correspondante. Vous pouvez également spécifier tags pour afficher toutes les balises Nomenclature appliquées au document.
Le code suivant configure l'exemple ci-dessus pour fournir un maximum de 1 000 résultats triés par récence, avec une interface utilisateur de pagination numérique commençant avec 9 résultats et 9 résultats supplémentaires par page. Il configure les résultats à afficher sous forme de fiches avec un titre, un résumé et un bouton intitulé "En savoir plus". ainsi que les balises pour product et api.
<devsite-catalog query="project_url:/devsite"
maxresults="1000"
sortorder="recency"
items-per-page="9"
fields="title summary product api"
pagination-type="numeric"
link-type="button"
button-label="Learn more"
template="card">
<select name="doctype" label="Choose a content type" multiple>
<option value="BestPractices">Best Practices</option>
<option value="Blueprint">Blueprint</option>
<option value="Concept">Concept</option>
<option value="Pattern">Pattern</option>
<option value="ReferenceArchitecture">Reference Architecture</option>
<option value="Tutorial">Tutorial</option>
</select>
<select name="keywords" label="Choose a keyword" multiple>
<option value="BestPractices">Best Practices</option>
<option value="Blueprint">Blueprint</option>
<option value="Concept">Concept</option>
<option value="Pattern">Pattern</option>
<option value="ReferenceArchitecture">Reference Architecture</option>
<option value="Tutorial">Tutorial</option>
</select>
</devsite-catalog>
Si votre équipe dispose d'une assistance en matière d'expérience utilisateur, vous pouvez créer un modèle personnalisé pour vos fiches de catalogue. Pour ce faire, ajoutez un nouveau modèle Soy à l'
Ajoutez des tags à vos contenus
Le contenu n'est filtrable que s'il est tagué selon vos filtres. Vous pouvez ajouter des filtres à l'aide des dimensions suivantes:
des mots clés structurés avec des balises explicites Mots clés (non structurés) page_type Mots clés structurés déduits du graphique de la nomenclature La plupart des filtres de type "Cases à cocher" et "Sélectionner" permettent de filtrer le contenu en fonction de mots clés structurés, où la dimension de filtre doit correspondre à un espace de noms de mot clé structuré et la valeur de filtre doit correspondre au reste du mot clé structuré. Pour en savoir plus sur les mots clés structurés et les espaces de noms acceptés, consultez la documentation de Nomenclature.
Pour masquer une page dans tous les catalogues, définissez la balise de métadonnées hide_from_catalogs sur "true" sur cette page.
Ajuster la mise en page
Pour modifier la mise en page par défaut des colonnes (deux colonnes pour les éléments template="activity" ou trois colonnes pour les autres éléments), ajoutez un attribut "items-part" avec la valeur 1, 2, 3 ou 4.
<devsite-catalog items-across="2" query="type:product"></devsite-catalog>
Plus la fenêtre d'affichage se réduit, plus la mise en page des éléments s'ajuste le contenu reste accessible. Pour les valeurs items-across de 3 ou 4, la mise en page passe à deux colonnes sur les tablettes, et toutes les mises en page passent à une seule colonne sur les appareils mobiles.
Exemples
Les exemples suivants illustrent l'apparence et le fonctionnement des fonctionnalités de base de l'élément personnalisé <devsite-catalog>.
Centre d'architecture cloud
Voici un exemple du catalogue utilisé pour le Centre d'architecture cloud. En plus de title et summary, il spécifie product et api dans l'attribut fields afin d'ajouter des balises pour ces espaces de noms aux cartes.
Démo
<span class="devsite-heading" role="heading" aria-level="4">Source</span>
Catalogue des ateliers de programmation
Voici un exemple du catalogue d'ateliers de programmation utilisant des mots clés plats, une pagination non numérotée et aucune saisie de filtre de texte.
Démo
Filtres pré-appliqués
Le widget de catalogue suit l'état des filtres appliqués par l'utilisateur dans l'URL de la page, ce qui permet d'ajouter aux favoris ou de partager des configurations de filtre spécifiques. Chaque dimension de filtre est représentée par un paramètre d'URL. Les paramètres d'URL sont structurés comme suit:
Pour les commandes de filtrage qui n'ont qu'une seule valeur, comme les filtres de style "Sélectionner", la valeur du paramètre d'URL correspond à la valeur normalisée du filtre. Pour les commandes de filtrage qui acceptent plusieurs valeurs, telles que les cases à cocher, la valeur du paramètre d'URL est une liste des valeurs de filtre normalisées séparées par une virgule. Les autres paramètres d'URL (hors filtre) ne sont pas affectés par le widget de catalogue. Par exemple, si un utilisateur a saisi "Big Data" dans le filtre de texte et sélectionné Python et JavaScript dans les cases à cocher "Langue", l'URL de la page reflète ces filtres avec la chaîne de requête "text=Big%20Data&language=python,javascript".
Lorsqu'une page contenant le widget de catalogue est chargée avec des paramètres de filtre dans l'URL, le widget de catalogue préremplit les commandes de filtrage correspondantes et filtre les résultats en conséquence.
Par exemple, voici l'URL de la démonstration du Centre d'architecture cloud:
https://developers.google.com/devsite/reference/widgets/catalog/architecture
Voici quelques exemples de chaînes de requête que vous pouvez ajouter à cette URL:
?doctype=bestpractices coche la case Bonnes pratiques dans la section Sélectionner un type de contenu, qui correspond à la dimension de filtre doctype.
?doctype=bestpractices,blueprint coche les cases Bonnes pratiques et Plan dans la même section.
?text=Cloud%20SQL renseigne l'entrée du filtre de texte avec "Cloud SQL".
Les dimensions des paramètres de filtre peuvent également être combinées. L'URL suivante contient à la fois les paramètres doctype et text:
Cette URL permet de cocher les cases appropriées et d'insérer le texte, comme illustré dans la démonstration suivante.