O elemento personalizado <devsite-catalog> fornece conteúdo dinâmico filtrável, que inclui uma IU de filtragem para toda a plataforma. Ele consulta o conteúdo do DevSite para carregar recursos relacionados a um tópico específico em uma página do DevSite. Este elemento personalizado pode carregar recursos de qualquer locatário do DevSite, bem como recursos externos que foram adicionados ao corpus de conteúdo externo do DevSite.
Uso
Para começar a usar o elemento personalizado <devsite-catalog>, faça o seguinte:
- Adicione o elemento personalizado à sua página.
- Isole seu conjunto de dados com uma consulta de conteúdo dinâmico.
- Adicione filtros.
- Selecione as opções de renderização.
- Inclua tags no seu conteúdo.
- Ajuste o layout.
Adicionar o elemento personalizado
Adicione o elemento personalizado <devsite-catalog> à sua página no local desejado.
HTML
Para páginas HTML, o elemento personalizado pode ser adicionado exatamente como qualquer outro elemento HTML:
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
YAML
Para uma linha da página de destino com conteúdo adicional relacionado ao elemento personalizado, use uma linha de um único item com a opção description-100 das opções de linha da 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>
Você também pode usar um campo custom_html se não precisar de outros campos no nível do item, como heading ou description:
rows:
- custom_html: >
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
Markdown
Para arquivos Markdown, o elemento personalizado precisa ser unido a um elemento <div> ou <section>:
<div>
<devsite-catalog query="project_url:/devsite"></devsite-catalog>
</div>
Isolar o conjunto de dados
Determine uma consulta de conteúdo dinâmico que isole o conjunto de dados completo que você quer disponibilizar no catálogo e adicione-o ao atributo de consulta no novo catálogo.
Por exemplo, para adicionar um catálogo de todos os produtos listados em developers.google.com à sua página, adicione o catálogo a seguir a ela.
<devsite-catalog query="type:product"></devsite-catalog>
Adicionar filtros
Para adicionar filtros ao catálogo, siga as instruções abaixo para cada uma das opções a seguir:
Uma caixa de entrada de texto Uma seção de filtros de caixa de seleção na lateral
Filtro de entrada de texto
Adicione uma caixa de entrada que filtre os resultados conforme o usuário digita o texto. A caixa de filtro corresponde ao texto do usuário no título, na descrição e nas palavras-chave de cada resultado.
<devsite-catalog query="type:product">
<input type="text" placeholder="Filter results">
</devsite-catalog>
Filtros de caixa de seleção
No elemento <devsite-catalog>, adicione um <select> para cada dimensão filtrável, como tipo de documento, produto e linguagem de programação. O atributo name determina a dimensão de filtragem, que corresponde a um namespace de palavra-chave estruturado ou a um nome de campo do DevSite, como keywords. Especifique um marcador de dimensão para seus leitores usando o atributo "label". Especifique vários atributos para cada elemento <select> também para garantir que a interface do filtro gerado esteja correta.
Adicione um elemento <option> para cada valor de filtro na dimensão especificada no elemento <select> pai. Especifique seu valor filtrável no atributo de valor em cada <option>. Adicione rótulos de filtro legíveis entre as tags <option>. Eles serão traduzidos se a página for localizada.
O código a seguir adiciona uma seção de filtros de tipo de documento e de palavra-chave em uma interface de filtragem ao lado dos 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 caixa de seleção iniciais
O atributo initial-checkbox-filters determina o número de filtros de caixas de seleção que serão exibidos no carregamento inicial. O padrão é 3.
<devsite-catalog query="project_url:/devsite" initial-checkbox-filters="5">
...
</devsite-catalog>
Selecionar as opções de renderização
<devsite-catalog> é compatível com todas as opções de renderização e atributos de elementos personalizados do widget de conteúdo dinâmico.
Use o atributo fields para especificar quais dados você quer mostrar no card do seu catálogo. Além do fields documentado para <devsite-dynamic-content>, é possível especificar qualquer um dos namespaces de palavras-chave estruturadas documentados para renderizar as tags aplicadas a cada documento nesse namespace. Por exemplo, especificar product resultará na renderização de todas as tags de produto aplicadas a cada página no card dela. Também é possível especificar tags para ver todas as tags de Nomenclature aplicadas ao documento.
O código a seguir configura o exemplo acima para fornecer um máximo de mil resultados classificados por tempo para retorno com uma interface de paginação numérica começando com nove resultados e nove resultados adicionais por página. Ela configura os resultados para serem renderizados como cards com um título, resumo e um botão "Saiba mais" além de tags para 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 sua equipe oferece suporte à UXE, é possível criar um modelo personalizado para os cards do catálogo adicionando um novo modelo Soy ao
Inclua tags no seu conteúdo
O conteúdo só pode ser filtrado se estiver marcado de acordo com seus filtros. É possível adicionar filtros usando as seguintes dimensões:
palavras-chave estruturadas explicitamente codificadas palavras-chave (não estruturadas) page_type palavras-chave estruturadas inferidas do gráfico de nomenclatura A maioria dos filtros de estilo de seleção e caixa de seleção filtra o conteúdo de acordo com palavras-chave estruturadas, em que a dimensão do filtro precisa corresponder a um namespace de palavra-chave estruturada e o valor do filtro precisa corresponder ao restante da palavra-chave estruturada. Consulte a documentação de nomenclatura para mais informações sobre palavras-chave estruturadas e namespaces compatíveis.
Para ocultar uma página de todos os catálogos, defina a tag de metadados hide_from_catalogs como true nessa página.
Ajustar layout
Para mudar o layout padrão das colunas (que é duas colunas para itens template="activity" ou três colunas), adicione um atributo de itens com um valor de 1, 2, 3 ou 4.
<devsite-catalog items-across="2" query="type:product"></devsite-catalog>
À medida que a janela de visualização fica mais estreita, o layout dos itens é ajustado para garantir o conteúdo permaneça acessível. Para valores de items-across de 3 ou 4, o layout muda para duas colunas em tablets, e todos os layouts mudam para uma única coluna em dispositivos móveis.
Exemplos
Os exemplos a seguir demonstram a aparência e a funcionalidade dos recursos básicos do elemento personalizado <devsite-catalog>.
Centro de arquitetura do Cloud
Confira a seguir um exemplo do catálogo usado no Centro de arquitetura do Cloud. Além de title e summary, ele especifica product e api no atributo fields para adicionar tags desses namespaces aos cards.
Demonstração
<span class="devsite-heading" role="heading" aria-level="4">Source</span>
Catálogo de codelabs
Confira a seguir um exemplo do catálogo de codelabs que usa palavras-chave simples, paginação sem numeração e nenhuma entrada de filtro de texto.
Demonstração
Filtros pré-aplicados
O widget Catálogo rastreia o estado dos filtros aplicados pelo usuário no URL da página, permitindo que configurações de filtro específicas sejam adicionadas aos favoritos ou compartilhadas. Cada dimensão de filtro é representada por um parâmetro de URL. Os parâmetros de URL são estruturados da seguinte forma:
Para controles de filtros que têm um único valor, como filtros de seleção de estilo, o valor do parâmetro de URL é o valor do filtro normalizado. No caso de controles de filtros compatíveis com vários valores, como caixas de seleção, o valor de parâmetro de URL é uma lista separada por vírgulas dos valores de filtro normalizados. Todos os outros parâmetros de URL (sem filtro) não são afetados pelo widget "Catálogo". Por exemplo, se um usuário inseriu “Big Data” no filtro de texto e selecionado Python e JavaScript nas caixas de seleção "Idioma", o URL da página reflete esses filtros com a string de consulta "text=Big%20Data&language=python,javascript".
Quando uma página com o widget Catálogo é carregada com parâmetros de filtro no URL, o widget Catálogo preenche previamente os controles de filtro correspondentes e filtra os resultados adequadamente.
Por exemplo, este é o URL da demonstração do Centro de arquitetura do Cloud:
https://developers.google.com/devsite/reference/widgets/catalog/architecture
Veja alguns exemplos de strings de consulta que podem ser anexadas a esse URL:
?doctype=bestpractices marca a caixa de seleção Práticas recomendadas na seção Escolha um tipo de conteúdo, que corresponde à dimensão de filtro doctype.
?doctype=bestpractices,blueprint marca as caixas de seleção Práticas recomendadas e Blueprint na mesma seção.
?text=Cloud%20SQL preenche a entrada do filtro de texto com "Cloud SQL".
As dimensões do parâmetro de filtro também podem ser combinadas. O URL a seguir contém os parâmetros doctype e text:
Esse URL marca as caixas de seleção apropriadas e preenche a entrada de texto, como mostra a demonstração a seguir.