L'elemento personalizzato <devsite-catalog> fornisce contenuti dinamici filtrabili che includono un'interfaccia utente di filtro a livello di piattaforma. Esegue una query sui contenuti di proprietà di DevSite per caricare risorse relative a un determinato argomento in una pagina di questo sito. Questo elemento personalizzato può caricare risorse da qualsiasi tenant di DevSite, nonché risorse esterne che sono state aggiunte al corpus dei contenuti esterni di DevSite.

Utilizzo

Per iniziare a utilizzare l'elemento personalizzato <devsite-catalog>:

1. Aggiungi l'elemento personalizzato alla pagina.
2. Isola il set di dati con una query Contenuti dinamici.
3. Aggiungi filtri.
4. Seleziona le opzioni di rendering.
5. Codifica i tuoi contenuti.
6. Modificare il layout.

Aggiungere l'elemento personalizzato

Aggiungi l'elemento personalizzato <devsite-catalog> alla tua pagina nella posizione che preferisci.

HTML

Per le pagine HTML, l'elemento personalizzato può essere aggiunto come qualsiasi altro elemento HTML:

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

YAML

Per una riga della pagina di destinazione con contenuti aggiuntivi correlati all'elemento personalizzato, utilizza una riga per un singolo articolo con l'opzione description-100 dalle opzioni riga della pagina di destinazione.

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>

Puoi utilizzare anche un campo custom_html se non hai bisogno di altri campi a livello di articolo, ad esempio heading o description:

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

Markdown

Per i file Markdown, l'elemento personalizzato deve essere aggregato in un elemento <div> o <section>:

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

Isolare il set di dati

Determina una query sui contenuti dinamici che isoli l'intero set di dati che vuoi rendere disponibile nel catalogo e aggiungilo all'attributo della query nel nuovo catalogo.

Ad esempio, per aggiungere alla tua pagina un catalogo di tutti i prodotti elencati su developers.google.com, aggiungi il catalogo seguente alla pagina.

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

Aggiungi filtri

Per aggiungere filtri al catalogo, segui le istruzioni riportate di seguito per ciascuna delle seguenti opzioni:

Una casella di inserimento di testo Una sezione laterale dei filtri delle caselle di controllo

Filtro di input di testo

Aggiungi una casella di immissione che filtri i risultati man mano che l'utente inserisce il testo. La casella di filtro corrisponde al testo dell'utente all'interno del titolo, della descrizione e delle parole chiave di ogni risultato.

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

Filtri delle caselle di controllo

All'interno dell'elemento <devsite-catalog>, aggiungi un elemento <select> per ogni dimensione filtrabile, ad esempio tipo di documento, prodotto e linguaggio di programmazione. L'attributo name determina la dimensione del filtro, che corrisponde allo spazio dei nomi di una parola chiave strutturata o al nome di un campo DevSite come keywords. Specifica un'etichetta di dimensione per i lettori utilizzando l'attributo etichetta. Assicurati di specificare anche più attributi per ogni elemento <select> per garantire che l'interfaccia utente del filtro generato sia corretta.

Aggiungi un elemento <option> per ogni valore del filtro nella dimensione specificata nell'elemento <select> principale. Specifica il valore filtrabile nell'attributo value di ogni <option>. Aggiungi etichette di filtro leggibili tra i tag <option>; verranno tradotte se la pagina è localizzata.

Il seguente codice aggiunge a lato dei risultati una sezione di filtri per tipo di documento e filtri per parole chiave in un'interfaccia utente di filtro:

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

Filtri delle caselle di controllo iniziali

L'attributo initial-checkbox-filters determina i filtri delle caselle di controllo numeri da mostrare al caricamento iniziale. Il valore predefinito è 3.

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

Selezionare le opzioni di rendering

<devsite-catalog> supporta tutte le opzioni di rendering e gli attributi degli elementi personalizzati per il widget Contenuti dinamici.

Utilizza l'attributo fields per specificare quali dati vuoi visualizzare sulla scheda del tuo catalogo. Oltre ai fields documentati per <devsite-dynamic-content>, puoi specificare uno qualsiasi degli spazi dei nomi di parole chiave strutturate documentati per eseguire il rendering dei tag applicati a ciascun documento all'interno di tale spazio dei nomi. Ad esempio, se specifichi product, tutti i tag dei prodotti verranno applicati a ogni pagina visualizzata nella scheda della pagina in questione. Puoi anche specificare tags per visualizzare tutti i tag Nomenclature applicati al documento.

Il seguente codice configura l'esempio precedente per fornire un massimo di 1000 risultati ordinati per recency con un'interfaccia utente di impaginazione numerica che inizia con 9 risultati e 9 risultati aggiuntivi per pagina. Configura i risultati in modo che vengano visualizzati come schede con titolo, riepilogo e pulsante denominato "Scopri di più" nonché i tag per product e 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>

Se il tuo team supporta l'esperienza utente (UXE), puoi creare un modello personalizzato per le schede del catalogo aggiungendo un nuovo modello Soy all' elemento personalizzato e specificando il nuovo modello tramite l'attributo modello nel tuo catalogo.

Taggare i contenuti

I contenuti possono essere filtrati solo se sono taggati in base ai tuoi filtri. È possibile aggiungere filtri utilizzando le seguenti dimensioni:

parole chiave strutturate codificate in modo esplicito parole chiave (non strutturate) page_type parole chiave strutturate dedotte dal grafico Nomenclatura La maggior parte delle caselle di controllo e dei filtri di selezione filtra i contenuti in base a parole chiave strutturate, dove la dimensione del filtro deve corrispondere a uno spazio dei nomi delle parole chiave strutturate e il valore del filtro deve corrispondere al resto della parola chiave strutturata. Per ulteriori informazioni sulle parole chiave strutturate e sugli spazi dei nomi supportati, consulta la documentazione relativa alla Nomenclatura.

Per nascondere una pagina da tutti i cataloghi, imposta il tag dei metadati hide_from_catalogs su true in quella pagina.

Modificare il layout

Per modificare il layout predefinito delle colonne (che è di due colonne per gli elementi template="activity" o di tre colonne altrimenti), aggiungi un attributo items-a cross con un valore di 1, 2, 3 o 4.

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

Man mano che l'area visibile si restringe, il layout degli elementi si adatta per assicurare che rimangono accessibili. Per i valori items-across di 3 o 4, il layout passa a due colonne sui tablet e tutti i layout vengono impostati su una singola colonna sui dispositivi mobili.

Esempi

Di seguito sono riportati alcuni esempi per dimostrare l'aspetto e la funzionalità delle caratteristiche di base dell'elemento personalizzato <devsite-catalog>.

Cloud Architecture Center

Di seguito è riportato un esempio del catalogo utilizzato per Cloud Architecture Center. Oltre a title e summary, specifica product e api nell'attributo fields per aggiungere alle schede tag per questi spazi dei nomi.

Demo

Best practice Progetto iniziale Concetto Pattern Architettura di riferimento Tutorial Best practice Progetto iniziale Concetto Pattern Architettura di riferimento Tutorial

Visualizza a grandezza originale

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

Catalogo codelab

Di seguito è riportato un esempio del catalogo di codelab che utilizza parole chiave piatte, impaginazione non numerata e nessun input di filtro di testo.

Demo

Best practice Progetto iniziale Concetto Pattern Architettura di riferimento Tutorial Best practice Progetto iniziale Concetto Pattern Architettura di riferimento Tutorial

Visualizza a grandezza originale

Filtri preapplicati

Il widget Catalogo monitora lo stato dei filtri applicati dall'utente nell'URL della pagina, consentendo di aggiungere ai preferiti o condividere configurazioni di filtri specifiche. Ogni dimensione del filtro è rappresentata da un parametro URL. I parametri URL sono strutturati come segue:

Per i controlli filtro che hanno un singolo valore come i filtri di tipo select, il valore del parametro URL è il valore del filtro normalizzato. Per i controlli filtro che supportano più valori come le caselle di controllo, il valore del parametro URL è un elenco separato da virgole dei valori del filtro normalizzati. Tutti gli altri parametri URL (non di filtro) non sono interessati dal widget Catalog. Ad esempio, se un utente inserisce "Big Data" nel filtro di testo e hai selezionato Python e JavaScript dalle caselle di controllo Linguaggio, l'URL della pagina riflette questi filtri con la stringa di query "text=Big%20Data&language=python,JavaScript".

Quando una pagina contenente il widget Catalogo viene caricata con parametri di filtro nell'URL, questo widget precompila i controlli filtro corrispondenti e filtra i risultati in modo appropriato.

Ad esempio, il seguente è l'URL per la demo di Cloud Architecture Center:

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

Ecco alcuni esempi di stringhe di query che potresti aggiungere all'URL:

?doctype=bestpractices seleziona la casella di controllo Best practice nella sezione Scegli un tipo di contenuti, che corrisponde alla dimensione del filtro doctype. ?doctype=bestpractices,blueprint seleziona entrambe le caselle di controllo Best practice e Progetto nella stessa sezione. ?text=Cloud%20SQL compila l'input del filtro di testo con "Cloud SQL".

Puoi anche combinare le dimensioni dei parametri di filtro. Il seguente URL contiene i parametri doctype e text:

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

Questo URL seleziona le caselle di controllo appropriate e compila l'input di testo, come mostrato nella demo seguente.

Best practice Progetto iniziale Concetto Pattern Architettura di riferimento Tutorial Best practice Progetto iniziale Concetto Pattern Architettura di riferimento Tutorial

Visualizza a grandezza originale