El elemento personalizado <devsite-catalog> proporciona contenido dinámico filtrable que incluye una IU de filtrado en toda la plataforma. Consulta contenido que es propiedad de DevSite para cargar recursos relacionados con un tema en particular en una página de DevSite. Este elemento personalizado puede cargar recursos de cualquier usuario de DevSite, así como recursos externos que se hayan agregado al corpus de contenido externo de DevSite.
Uso
Para comenzar a usar el elemento personalizado <devsite-catalog>, haz lo siguiente:
- Agrega el elemento personalizado a tu página.
- Aísla tu conjunto de datos con una consulta de contenido dinámico.
- Agrega filtros.
- Selecciona las opciones de renderización.
- Etiqueta tu contenido.
- Ajusta el diseño.
Agrega el elemento personalizado
Agrega el elemento personalizado <devsite-catalog> a tu página en la ubicación deseada.
HTML
En el caso de las páginas HTML, el elemento personalizado se puede agregar como cualquier otro elemento HTML:
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
YAML
Para una fila de página de destino con contenido adicional relacionado con el elemento personalizado, usa una fila de un solo artículo con la opción description-100 de las opciones de fila de la página de destino.
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>
También puedes usar un campo custom_html si no necesitas ningún otro campo a nivel del artículo, como heading o description:
rows:
- custom_html: >
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
Markdown
Para los archivos de Markdown, el elemento personalizado debe estar unido a un elemento <div> o <section>:
<div>
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
</div>
Aísla tu conjunto de datos
Determina una consulta de contenido dinámico que aísle el conjunto de datos completo que deseas que esté disponible en tu catálogo y agrégalo al atributo de búsqueda de tu nuevo catálogo.
Por ejemplo, para agregar a tu página un catálogo de todos los productos que se muestran en developers.google.com, agrega el siguiente catálogo.
<devsite-catalog query="type:product"></devsite-catalog>
Agrega filtros
Si desea agregar filtros a su catálogo, siga las instrucciones que aparecen a continuación para cada una de las siguientes opciones:
Un cuadro de entrada de texto Una sección de filtros de casillas de verificación a un lado
Filtro de entrada de texto
Agrega una casilla de entrada que filtre los resultados a medida que el usuario ingresa texto. El cuadro de filtrado hace coincidir el texto del usuario dentro del título, la descripción y las palabras clave de cada resultado.
<devsite-catalog query="type:product">
<input type="text" placeholder="Filter results">
</devsite-catalog>
Filtros de casilla de verificación
En el elemento <devsite-catalog>, agrega un elemento <select> para cada dimensión filtrable, como el tipo de documento, el producto y el lenguaje de programación. El atributo name determina la dimensión del filtrado, que corresponde a un espacio de nombres estructurado de palabras clave o a un nombre de campo de DevSite, como keywords. Especifica una etiqueta de dimensión para tus lectores con el atributo etiqueta. Asegúrate de especificar también el atributo múltiple para cada elemento <select> a fin de garantizar que la IU del filtro generada sea correcta.
Agrega un elemento <option> para cada valor de filtro en la dimensión especificada del elemento <select> superior. Especifica el valor filtrable en el atributo de valor de cada <option>. Agrega etiquetas de filtro legibles entre las etiquetas <option>. que se traducirán si tu página está localizada.
El siguiente código agrega una sección de filtros de tipo de documento y filtros de palabras clave en una IU de filtrado al costado de los resultados:
<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>
Filtros de la casilla de verificación inicial
El atributo initial-checkbox-filters determina los filtros de la casilla de verificación del número que se mostrarán en la carga inicial. La ruta predeterminada es 3.
<devsite-catalog query="project_url:/devsite" initial-checkbox-filters="5">
...
</devsite-catalog>
Selecciona las opciones de renderización
<devsite-catalog> admite todas las opciones de renderización y los atributos de elementos personalizados para el widget de contenido dinámico.
Usa el atributo fields para especificar qué datos quieres mostrar en la tarjeta de tu catálogo. Además de los fields documentados para <devsite-dynamic-content>, puedes especificar cualquiera de los espacios de nombres de palabras clave estructuradas documentados para renderizar las etiquetas aplicadas a cada documento en ese espacio de nombres. Por ejemplo, si especificas product, todas las etiquetas de producto aplicadas a cada página se renderizarán en la tarjeta de esa página. También puedes especificar tags para ver todas las etiquetas Nomenclature aplicadas al documento.
El siguiente código configura el ejemplo anterior para proporcionar un máximo de 1,000 resultados ordenados por fecha más reciente con una IU de paginación numérica que comienza con 9 resultados y 9 resultados adicionales por página. Configura los resultados para que se rendericen como tarjetas con un título, un resumen y un botón con la etiqueta "Más información" así como etiquetas para product y 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 tu equipo cuenta con asistencia de UXE, puedes crear una plantilla personalizada para tus tarjetas de catálogo. Para ello, agrega una plantilla de Soy nueva al
Etiqueta tu contenido
El contenido solo se puede filtrar si está etiquetado según tus filtros. Es posible agregar filtros con las siguientes dimensiones:
palabras clave estructuradas etiquetadas explícitamente Palabras clave (no estructuradas) page_type palabras clave estructuradas inferidas del gráfico de nomenclatura La mayoría de los filtros de casillas de verificación y de estilo de selección filtrarán el contenido de acuerdo con palabras clave estructuradas, donde la dimensión de filtro debe coincidir con un espacio de nombres de palabras clave estructuradas y el valor del filtro debe coincidir con el resto de la palabra clave estructurada. Consulta la documentación de Nomenclatura para obtener más información sobre palabras clave estructuradas y espacios de nombres compatibles.
Para ocultar una página de todos los catálogos, establece la etiqueta de metadatos hidden_from_catalogs como verdadera en esa página.
Ajusta el diseño
Para cambiar el diseño predeterminado de la columna (que consta de dos columnas para los elementos template="activity" o, de lo contrario, tres columnas), agrega un atributo de elementos cruzados con un valor de 1, 2, 3 o 4.
<devsite-catalog items-across="2" query="type:product"></devsite-catalog>
A medida que el viewport se estrecha, el diseño de los elementos se ajusta para garantizar que contenido seguirá disponible. Para valores items-across de 3 o 4, el diseño cambia a dos columnas en tablets y todos los diseños cambian a una sola columna en dispositivos móviles.
Ejemplos
En los siguientes ejemplos, se muestra el aspecto y la funcionalidad de las características básicas del elemento personalizado <devsite-catalog>.
Cloud Architecture Center
El siguiente es un ejemplo del catálogo que se usa para Cloud Architecture Center. Además de title y summary, especifica product y api en el atributo fields para agregar etiquetas para estos espacios de nombres a las tarjetas.
Demostración
<span class="devsite-heading" role="heading" aria-level="4">Source</span>
Catálogo de codelabs
El siguiente es un ejemplo del catálogo de codelabs con palabras clave planas, paginación sin numeración y sin entrada de filtro de texto.
Demostración
Filtros aplicados previamente
El widget de catálogo hace un seguimiento del estado de los filtros que aplica el usuario en la URL de la página, lo que permite que ciertos parámetros de configuración de filtros se agreguen a favoritos o se compartan. Cada dimensión de filtro está representada por un parámetro de URL. Los parámetros de URL se estructuran de la siguiente manera:
En el caso de los controles de filtro que tienen un solo valor, como los filtros de estilo de selección, el valor del parámetro de URL es el valor de filtro normalizado. En el caso de los controles de filtro que admiten varios valores, como las casillas de verificación, el valor del parámetro de URL es una lista separada por comas de los valores de filtro normalizados. El widget de catálogo no afecta los demás parámetros de URL (sin filtro). Por ejemplo, si un usuario ingresó “Macrodatos” en el filtro de texto y se seleccionaron Python y JavaScript en las casillas de verificación Lenguaje, la URL de la página refleja esos filtros con la cadena de consulta "text=Big%20Data&language=python,javascript".
Cuando una página que contiene el widget de catálogo se carga con parámetros de filtro en la URL, este widget prepropaga los controles de filtro correspondientes y filtra los resultados de manera adecuada.
Por ejemplo, la siguiente es la URL de la demostración de Cloud Architecture Center:
https://developers.google.com/devsite/reference/widgets/catalog/architecture
Estos son algunos ejemplos de cadenas de consulta que podrías agregar a esa URL:
?doctype=bestpractices marca la casilla de verificación Prácticas recomendadas en la sección Elige un tipo de contenido, que corresponde a la dimensión del filtro doctype.
?doctype=bestpractices,blueprint marca las casillas de verificación Prácticas recomendadas y Plano en la misma sección.
?text=Cloud%20SQL propaga la entrada del filtro de texto con “Cloud SQL”.
Las dimensiones del parámetro de filtro también se pueden combinar. La siguiente URL contiene los parámetros doctype y text:
Esta URL selecciona las casillas de verificación correspondientes y propaga la entrada de texto, como se muestra en la siguiente demostración.