L'element personalitzat <devsite-catalog> proporciona contingut dinàmic filtrable que inclou una interfície d'usuari de filtratge per a tota la plataforma. Consulta contingut propietat de DevSite per carregar recursos relacionats amb un tema concret en una pàgina de DevSite. Aquest element personalitzat pot carregar recursos de qualsevol inquilí de DevSite, així com recursos externs que s'han afegit al corpus de contingut extern de DevSite.

Ús

Per començar a utilitzar l'element personalitzat <devsite-catalog> , feu el següent:

1. Afegiu l'element personalitzat a la vostra pàgina.
2. Aïlleu el vostre conjunt de dades amb una consulta de contingut dinàmic.
3. Afegeix filtres.
4. Seleccioneu les vostres opcions de renderització.
5. Etiqueta el teu contingut.
6. Ajustar la disposició.

Afegiu l'element personalitzat

Afegiu l'element personalitzat <devsite-catalog> a la vostra pàgina a la ubicació desitjada.

HTML

Per a pàgines HTML, l'element personalitzat es pot afegir com qualsevol altre element HTML:

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

YAML

Per a una fila de la pàgina de destinació amb contingut addicional relacionat amb l'element personalitzat, utilitzeu una fila d'un sol element amb l'opció description-100 de les opcions de fila de la pàgina de destinació .

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>

També podeu utilitzar un camp custom_html si no necessiteu cap altre camp a nivell d'element, com ara heading o description :

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

Reducció

Per als fitxers Markdown, l'element personalitzat s'ha d'embolicar en un element <div> o <section> :

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

Aïlla el teu conjunt de dades

Determineu una consulta de contingut dinàmic que aïlli el conjunt de dades complet que voleu que estigui disponible al vostre catàleg i afegiu-lo a l'atribut de consulta del vostre nou catàleg.

Per exemple, per afegir un catàleg de tots els productes que figuren a developers.google.com a la vostra pàgina, afegiu el següent catàleg a la vostra pàgina.

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

Afegeix filtres

Per afegir filtres al vostre catàleg, seguiu les instruccions següents per a cadascuna de les opcions següents:

Un quadre d'entrada de text Una secció de filtres de caselles de selecció al lateral

Filtre d'entrada de text

Afegiu un quadre d'entrada que filtra els resultats a mesura que l'usuari introdueix text. El quadre de filtrat coincideix amb el text de l'usuari dins del títol, la descripció i les paraules clau de cada resultat.

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

Filtres de caselles de selecció

Dins del vostre element <devsite-catalog> , afegiu un element <select> per a cada dimensió filtrable, com ara el tipus de document, el producte i el llenguatge de programació. L'atribut name determina la dimensió de filtratge, que correspon a un espai de noms de paraula clau estructurat o a un nom de camp DevSite, com ara keywords . Especifiqueu una etiqueta de dimensió per als vostres lectors mitjançant l'atribut label. Assegureu-vos d'especificar també l'atribut múltiple per a cada element <select> per assegurar-vos que la interfície d'usuari del filtre generada sigui correcta.

Afegiu un element <option> per a cada valor de filtre a la dimensió especificada a l'element <select> principal. Especifiqueu el vostre valor filtrable a l'atribut value de cada <option> . Afegiu etiquetes de filtre llegibles entre les vostres etiquetes <option> ; aquests es traduiran si la vostra pàgina està localitzada.

El codi següent afegeix una secció de filtres de tipus de document i filtres de paraules clau en una interfície d'usuari de filtratge al costat dels resultats:

<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 caselles de selecció inicials

L'atribut initial-checkbox-filters determina el nombre de filtres de caselles que es mostraran a la càrrega inicial. El valor per defecte és 3 .

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

Seleccioneu les vostres opcions de renderització

<devsite-catalog> admet totes les opcions de representació i els atributs d'elements personalitzats per al giny de contingut dinàmic.

Utilitzeu l'atribut fields per especificar quines dades voleu mostrar a la targeta del vostre catàleg. A més dels fields documentats per a <devsite-dynamic-content> , podeu especificar qualsevol dels espais de noms de paraules clau estructurats documentats per representar les etiquetes aplicades a cada document d'aquest espai de noms. Per exemple, si especifiqueu product , totes les etiquetes de producte aplicades a cada pàgina es mostraran a la targeta d'aquesta pàgina. També podeu especificar tags per veure totes les etiquetes de nomenclatura aplicades al document.

El codi següent configura l'exemple anterior per proporcionar un màxim de 1000 resultats ordenats per recentitat amb una IU de paginació numèrica que comença amb 9 resultats i 9 resultats addicionals per pàgina. Configura els resultats perquè es mostrin com a targetes amb un títol, un resum i un botó amb l'etiqueta "Més informació", així com etiquetes per al product i 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 el vostre equip té suport UXE, podeu crear una plantilla personalitzada per a les vostres targetes de catàleg afegint una nova plantilla Soy al element personalitzat i especificant la vostra nova plantilla mitjançant l'atribut de plantilla del vostre catàleg.

Etiqueta el teu contingut

El contingut només es pot filtrar si està etiquetat segons els vostres filtres. És possible afegir filtres amb les dimensions següents:

paraules clau estructurades etiquetades explícitament (no estructurades) paraules clau page_type paraules clau estructurades inferides del gràfic de nomenclatura La majoria dels filtres de caselles de selecció i d'estil de selecció filtraran el contingut segons paraules clau estructurades, on la dimensió del filtre ha de coincidir amb un espai de noms de paraula clau estructurada i el valor del filtre ha de coincidir amb la resta de la paraula clau estructurada. Consulteu la documentació de la nomenclatura per obtenir més informació sobre paraules clau estructurades i espais de noms admesos.

Per amagar una pàgina de tots els catàlegs, establiu l'etiqueta de metadades hide_from_catalogs com a true en aquesta pàgina.

Ajustar la disposició

Per canviar el disseny de la columna predeterminat (que són dues columnes per als elements template="activity" o tres columnes en cas contrari), afegiu un atribut elements-across amb un valor d' 1 , 2 , 3 o 4 .

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

A mesura que la finestra gràfica es fa més estreta, la disposició dels elements s'ajusta per garantir que el contingut dels elements segueix sent accessible. Per als items-across valors de 3 o 4 , el disseny canvia a dues columnes a les tauletes i tots els dissenys canvien a una sola columna als dispositius mòbils.

Exemples

Els següents són exemples per demostrar l'aparença i la funcionalitat de les característiques bàsiques de l'element personalitzat <devsite-catalog> .

Centre d'Arquitectura del Núvol

A continuació es mostra un exemple del catàleg utilitzat per al Cloud Architecture Center. A més del title i summary , especifica product i api a l'atribut fields per afegir etiquetes per a aquests espais de noms a les targetes.

Demostració

Bones pràctiques Plànol Concepte Patró Arquitectura de referència Tutorial Bones pràctiques Plànol Concepte Patró Arquitectura de referència Tutorial

Veure a mida completa

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

Catàleg de Codelabs

El següent és un exemple del catàleg de laboratoris de codi que utilitzen paraules clau planes, paginació no numerada i cap entrada de filtre de text.

Demostració

Bones pràctiques Plànol Concepte Patró Arquitectura de referència Tutorial Bones pràctiques Plànol Concepte Patró Arquitectura de referència Tutorial

Veure a mida completa

Filtres pre-aplicats

El widget del Catàleg fa un seguiment de l'estat dels filtres aplicats per l'usuari a l'URL de la pàgina, permetent que les configuracions de filtres específiques siguin marcades o compartides. Cada dimensió de filtre està representada per un paràmetre d'URL. Els paràmetres d'URL s'estructuren de la següent manera:

Per als controls de filtre que tenen un sol valor, com ara els filtres d'estil de selecció, el valor del paràmetre d'URL és el valor del filtre normalitzat. Per als controls de filtre que admeten diversos valors, com ara caselles de selecció, el valor del paràmetre d'URL és una llista separada per comes dels valors de filtre normalitzats. La resta de paràmetres d'URL (que no són de filtre) no es veuen afectats pel widget del Catàleg. Per exemple, si un usuari ha introduït "Big Data" al filtre de text i ha seleccionat Python i JavaScript a les caselles de selecció Idioma, l'URL de la pàgina reflecteix aquests filtres amb la cadena de consulta "text=Big%20Data&language=python,javascript".

Quan una pàgina que conté el giny del catàleg es carrega amb paràmetres de filtre a l'URL, el giny del catàleg omple prèviament els controls de filtre corresponents i filtra els resultats de manera adequada.

Per exemple, el següent és l'URL de la demostració del Cloud Architecture Center :

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

Aquests són alguns exemples de cadenes de consulta que podeu afegir a aquest URL:

?doctype=bestpractices marca la casella de selecció Pràctiques recomanades a la secció Trieu un tipus de contingut , que correspon a la dimensió del filtre doctype . ?doctype=bestpractices,blueprint marca les caselles de selecció de Pràctiques recomanades i Blueprint a la mateixa secció. ?text=Cloud%20SQL omple l'entrada del filtre de text amb "Cloud SQL".

Les dimensions del paràmetre del filtre també es poden combinar. L'URL següent conté els paràmetres doctype i text:

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

Aquest URL selecciona les caselles de selecció adequades i omple l'entrada de text, tal com es mostra a la demostració següent.

Bones pràctiques Plànol Concepte Patró Arquitectura de referència Tutorial Bones pràctiques Plànol Concepte Patró Arquitectura de referència Tutorial

Veure a mida completa