Widgets: Katalog

Das benutzerdefinierte Element <devsite-catalog> bietet filterbare dynamische Inhalte und eine plattformweite Filter-UI. Sie fragt Inhalte der DevSite ab, um Ressourcen zu einem bestimmten Thema auf einer DevSite-Seite zu laden. Dieses benutzerdefinierte Element kann Ressourcen von jedem DevSite-Mandanten sowie von externen Ressourcen laden, die dem Korpus für externe Inhalte der DevSite hinzugefügt wurden.

Nutzung

So verwenden Sie das benutzerdefinierte Element <devsite-catalog>:

  1. Fügen Sie das benutzerdefinierte Element zu Ihrer Seite hinzu.
  2. Isolieren Sie Ihren Datensatz mit einer Abfrage für dynamischen Content.
  3. Fügen Sie Filter hinzu.
  4. Wählen Sie die gewünschten Renderingoptionen aus.
  5. Tagge deine Inhalte.
  6. Layout anpassen:

Benutzerdefiniertes Element hinzufügen

Fügen Sie Ihrer Seite an der gewünschten Stelle das benutzerdefinierte Element <devsite-catalog> hinzu.

HTML

Bei HTML-Seiten kann das benutzerdefinierte Element wie jedes andere HTML-Element hinzugefügt werden:

<devsite-catalog query="project_url:/devsite"></devsite-catalog>

YAML

Verwenden Sie für eine Landingpage-Zeile mit zusätzlichem Inhalt in Bezug auf das benutzerdefinierte Element eine Zeile für einen einzelnen Artikel mit der Option „description-100“ aus den Zeilenoptionen für die Landingpage.

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>

Sie können auch das Feld custom_html verwenden, wenn Sie keine weiteren Felder auf Artikelebene wie heading oder description benötigen:

rows:
- custom_html: >
    <devsite-catalog query="project_url:/devsite"></devsite-catalog>

Markdown

Bei Markdown-Dateien muss das benutzerdefinierte Element in ein <div>- oder <section>-Element eingeschlossen sein:

<div>
  <devsite-catalog query="project_url:/devsite"></devsite-catalog>
</div>

Datensatz isolieren

Legen Sie eine Abfrage für dynamische Inhalte fest, mit der der vollständige Datensatz isoliert wird, der für Ihren Katalog verfügbar sein soll, und fügen Sie ihn dem Abfrageattribut in Ihrem neuen Katalog hinzu.

Wenn Sie beispielsweise Ihrer Seite einen Katalog mit allen auf developers.google.com aufgeführten Produkten hinzufügen möchten, fügen Sie Ihrer Seite den folgenden Katalog hinzu.

<devsite-catalog query="type:product"></devsite-catalog>

Filter hinzufügen

Wenn du deinem Katalog Filter hinzufügen möchtest, folge der Anleitung unten für die folgenden Optionen:

Ein Texteingabefeld Ein Bereich mit Kästchenfiltern auf der Seite

Texteingabefilter

Fügen Sie ein Eingabefeld hinzu, mit dem Ergebnisse gefiltert werden, während der Nutzer Text eingibt. Das Filterfeld sucht im Titel, in der Beschreibung und in den Suchbegriffen der einzelnen Ergebnisse nach dem Text des Nutzers.

<devsite-catalog query="type:product">
  <input type="text" placeholder="Filter results">
</devsite-catalog>

Kästchenfilter

Fügen Sie im <devsite-catalog>-Element ein <select>-Element für jede filterbare Dimension wie Dokumenttyp, Produkt und Programmiersprache hinzu. Das Attribut name bestimmt die Filterdimension, die einem strukturierten Keyword-Namespace oder einem DevSite-Feldnamen wie keywords entspricht. Gib für deine Leser mithilfe des Attributs „label“ ein Dimensionslabel an. Geben Sie auch für jedes <select>-Element ein mehrfaches Attribut an, damit die generierte Filterbenutzeroberfläche korrekt ist.

Fügen Sie für jeden Filterwert in der angegebenen Dimension dem übergeordneten <select>-Element ein <option>-Element hinzu. Geben Sie Ihren filterbaren Wert im Wertattribut jedes <option> an. Fügen Sie lesbare Filterlabels zwischen den <option>-Tags ein. Diese werden übersetzt, wenn deine Seite lokalisiert ist.

Mit dem folgenden Code wird ein Abschnitt mit Dokumenttyp- und Suchbegrifffiltern in einer Filteroberfläche neben den Ergebnissen hinzugefügt:

<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>

Filter für anfängliche Kästchen

Das Attribut initial-checkbox-filters bestimmt die Anzahl der Kästchenfilter, die beim anfänglichen Ladevorgang angezeigt werden sollen. Der Standardwert ist 3.

<devsite-catalog query="project_url:/devsite" initial-checkbox-filters="5">
  ...
</devsite-catalog>

Renderingoptionen auswählen

<devsite-catalog> unterstützt alle Renderingoptionen und benutzerdefinierten Elementattribute für das Widget für dynamische Inhalte.

Mit dem Attribut fields kannst du angeben, welche Daten auf der Karte deines Katalogs angezeigt werden sollen. Zusätzlich zu dem für <devsite-dynamic-content> dokumentierten fields können Sie jeden der dokumentierten strukturierten Suchbegriff-Namespaces angeben, um die auf die einzelnen Dokumente in diesem Namespace angewendeten Tags zu rendern. Wenn Sie beispielsweise product angeben, werden alle Produkt-Tags, die auf jede Seite angewendet werden, auf der Karte für diese Seite gerendert. Sie können auch tags angeben, um alle auf das Dokument angewendeten Nomenklatur-Tags zu sehen.

Der folgende Code konfiguriert das obige Beispiel so, dass maximal 1.000 Ergebnisse, sortiert nach Neuheit, mit einer numerischen Paginierungs-UI angezeigt werden, die mit neun Ergebnissen und 9 zusätzlichen Ergebnissen pro Seite beginnt. Die Ergebnisse werden so konfiguriert, dass sie als Karten mit einem Titel, einer Zusammenfassung und einer Schaltfläche mit der Bezeichnung „Weitere Informationen“ gerendert werden. sowie Tags für product und 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>

Wenn Ihr Team UXE-Support hat, können Sie eine benutzerdefinierte Vorlage für Ihre Katalogkarten erstellen. Fügen Sie dazu dem benutzerdefinierten Element eine neue Soy-Vorlage hinzu und geben Sie Ihre neue Vorlage mithilfe des Vorlagenattributs in Ihrem Katalog an.

Inhalte taggen

Inhalte können nur gefiltert werden, wenn sie gemäß Ihren Filtern getaggt sind. Sie können Filter mit den folgenden Dimensionen hinzufügen:

explizit getaggten strukturierten Keywords (unstrukturierte) Keywords page_type aus der Nomenklaturgrafik abgeleitete strukturierte Keywords Mit den meisten Kästchen- und Auswahlfiltern wird der Inhalt nach strukturierten Keywords gefiltert. Dabei muss die Filterdimension einem strukturierten Keyword-Namespace und der Filterwert dem Rest des strukturierten Keywords entsprechen. Weitere Informationen zu strukturierten Suchbegriffen und unterstützten Namespaces finden Sie in der Nomenklaturdokumentation.

Um eine Seite aus allen Katalogen auszublenden, setzen Sie das Metadaten-Tag hide_from_catalogs auf dieser Seite auf „true“.

Layout anpassen

Um das Standardspaltenlayout zu ändern (entweder zwei Spalten für template="activity"-Elemente oder drei Spalten andernfalls), fügen Sie ein Element auf mehreren Ebenen mit einem Wert von 1, 2, 3 oder 4 hinzu.

<devsite-catalog items-across="2" query="type:product"></devsite-catalog>

Wenn der Darstellungsbereich schmaler wird, wird das Layout der Elemente angepasst, um sicherzustellen, und Inhalte zugänglich bleiben. Bei items-across-Werten von 3 oder 4 wechselt das Layout auf Tablets zu zwei Spalten und alle Layouts wechseln auf Mobilgeräten zu einer einzigen Spalte.

Beispiele

Die folgenden Beispiele veranschaulichen das Aussehen und die Funktionalität der grundlegenden Funktionen des benutzerdefinierten Elements <devsite-catalog>.

Cloud Architecture Center

Im Folgenden finden Sie ein Beispiel für den Katalog, der für das Cloud Architecture Center verwendet wird. Zusätzlich zu title und summary werden im Attribut fields product und api angegeben, um den Karten Tags für diese Namespaces hinzuzufügen.

Demo

In Originalgröße ansehen

<span class="devsite-heading" role="heading" aria-level="4">Source</span>

Codelabs-Katalog

Das folgende Beispiel zeigt den Katalog von Codelabs mit flachen Keywords, nicht nummerierter Paginierung und ohne Textfiltereingabe.

Demo

In Originalgröße ansehen

Vorab angewendete Filter

Das Katalog-Widget verfolgt den Status der vom Nutzer angewendeten Filter in der Seiten-URL, sodass bestimmte Filterkonfigurationen als Lesezeichen gespeichert oder freigegeben werden können. Jede Filterdimension wird durch einen URL-Parameter dargestellt. Die URL-Parameter sind wie folgt aufgebaut:

Bei Filtersteuerungen mit einem einzelnen Wert wie Auswahlfilter ist der URL-Parameterwert der normalisierte Filterwert. Bei Filtersteuerungen, die mehrere Werte wie Kästchen unterstützen, ist der URL-Parameterwert eine durch Kommas getrennte Liste der normalisierten Filterwerte. Alle anderen (ohne Filter) URL-Parameter sind vom Katalog-Widget nicht betroffen. Wenn ein Nutzer beispielsweise „Big Data“ in den Textfilter ein und haben Python und JavaScript in den Kästchen für die Sprache ausgewählt. Die Seiten-URL spiegelt diese Filter mit dem Abfragestring 'text=Big%20Data&language=python,javascript' wider.

Wenn eine Seite, die das Katalog-Widget enthält, mit Filterparametern in der URL geladen wird, füllt das Katalog-Widget die entsprechenden Filtersteuerungen vorab aus und filtert die Ergebnisse entsprechend.

So sieht die URL für die Cloud Architecture Center-Demo aus:

https://developers.google.com/devsite/reference/widgets/catalog/architecture

Hier sind einige Beispiele für Abfragestrings, die Sie an diese URL anhängen könnten:

?doctype=bestpractices markiert im Bereich Inhaltstyp auswählen das Kästchen Best Practices, das der Filterdimension doctype entspricht. ?doctype=bestpractices,blueprint aktiviert die Kästchen Best Practices und Blueprint im selben Abschnitt. ?text=Cloud%20SQL gibt „Cloud SQL“ in die Textfiltereingabe ein.

Die Filterparameter-Dimensionen können auch kombiniert werden. Die folgende URL enthält sowohl den DOCTYPE- als auch den Textparameter:

https://developers.google.com/devsite/reference/widgets/catalog/architecture?doctype=bestpractices%2Cblueprint&amp;text=Cloud%20SQL

Mit dieser URL werden die entsprechenden Kontrollkästchen aktiviert und die Texteingabe wird wie in der folgenden Demo gezeigt.

In Originalgröße ansehen