The <devsite-catalog> custom element provides filterable dynamic content that includes a platform-wide filtering UI. It queries DevSite-owned content to load resources related to a particular topic on a DevSite page. This custom element can load resources from any DevSite tenant as well as external resources that have been added to the DevSite External Content corpus.

Usage

To get started using the <devsite-catalog> custom element, do the following:

1. Add the custom element to your page.
2. Isolate your data set with a Dynamic Content query.
3. Add filters.
4. Select your rendering options.
5. Tag your content.
6. Adjust layout.

Add the custom element

Add the <devsite-catalog> custom element to your page in the desired location.

HTML

For HTML pages, the custom element can be added just like any other HTML element:

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

YAML

For a landing page row with additional content related to the custom element, use a single-item row with the description-100 option from the landing page row options.

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>

You can also use a custom_html field if you don't need any other item-level fields such as heading or description:

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

Markdown

For Markdown files, the custom element must be wrapped in a <div> or <section> element:

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

Isolate your data set

Determine a Dynamic Content query that isolates the full dataset you want available to your catalog and add it to the query attribute on your new catalog.

For example, to add a catalog of all products listed on developers.google.com to your page, add the following catalog to your page.

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

Add filters

To add filters to your catalog, follow the instructions below for each of the following options:

A text input box A section of checkbox filters on the side

Text input filter

Add an input box that filters results as the user enters text. The filtering box matches the user's text within the title, description, and keywords of each result.

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

Checkbox filters

Within your <devsite-catalog> element, add a <select> element for every filterable dimension such as document type, product, and programming language. The name attribute determines the filtering dimension, which corresponds to a structured keyword namespace or a DevSite field name such as keywords. Specify a dimension label for your readers using the label attribute. Be sure to specify the multiple attribute for each <select> element as well to ensure the generated filter UI is correct.

Add an <option> element for each filter value in the specified dimension on the parent <select> element. Specify your filterable value in the value attribute on each <option>. Add readable filter labels in between your <option> tags; these will be translated if your page is localized.

The following code adds a section of document type filters and keyword filters in a filtering UI to the side of the results:

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

Initial checkbox filters

The initial-checkbox-filters attribute determines the number checkbox filters to show at initial load. Default is 3.

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

Select your rendering options

<devsite-catalog> supports all of the rendering options and custom element attributes for the Dynamic Content widget.

Use the fields attribute to specify what data you want to display on your catalog's card. In addition to the fields documented for <devsite-dynamic-content>, you can specify any of the documented structured keyword namespaces to render the tags applied to each document in that namespace. For example, specifying product will result in all product tags applied to each page being rendered on the card for that page. You can also specify tags to see all Nomenclature tags applied to the document.

The following code configures the example above to provide a maximum of 1000 results sorted by recency with a numeric pagination UI beginning with 9 results and 9 additional results per page. It configures results to be rendered as cards with a title, summary, and button labeled "Learn more" as well as tags for product and 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>

If your team has UXE support, you can create a custom template for your catalog cards by adding a new Soy template to the custom element and specifying your new template using the template attribute on your catalog.

Tag your content

Content is only filterable if it is tagged according to your filters. It is possible to add filters using the following dimensions:

explicitly tagged structured keywords (unstructured) keywords page_type structured keywords inferred from the Nomenclature graph Most checkbox and select-style filters will filter content according to structured keywords, where the filter dimension must match a structured keyword namespace and the filter value must match the remainder of the structured keyword. See the Nomenclature documentation for more information on structured keywords and supported namespaces.

To hide a page from all catalogs, set the hide_from_catalogs metadata tag to true on that page.

Adjust layout

To change the default column layout (which is either two columns for template="activity" items or three columns otherwise), add an items-across attribute with a value of 1, 2, 3, or 4.

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

As the viewport gets narrower, the layout of the items adjusts to ensure the items' content remains accessible. For items-across values of 3 or 4, the layout switches to two columns on tablets, and all layouts switch to a single column on mobile devices.

Examples

The following are examples to demonstrate the appearance and functionality of the basic features of the <devsite-catalog> custom element.

Cloud Architecture Center

The following is an example of the catalog used for the Cloud Architecture Center. In addition to title and summary, it specifies product and api in the fields attribute to add tags for these namespaces to the cards.

Demo

Best Practices Blueprint Concept Pattern Reference Architecture Tutorial Best Practices Blueprint Concept Pattern Reference Architecture Tutorial

View full size

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

Codelabs Catalog

The following is an example of the catalog of codelabs using flat keywords, non-numbered pagination, and no text filter input.

Demo

Best Practices Blueprint Concept Pattern Reference Architecture Tutorial Best Practices Blueprint Concept Pattern Reference Architecture Tutorial

View full size

Pre-applied filters

The Catalog widget tracks the state of user-applied filters in the page URL, allowing specific filter configurations to be bookmarked or shared. Each filter dimension is represented by a URL parameter. The URL parameters are structured as follows:

For filter controls that have a single value like select-style filters, the URL parameter value is the normalized filter value. For filter controls that support multiple values like checkboxes, the URL parameter value is a comma-separated list of the normalized filter values. All other (non-filter) URL parameters are not affected by the Catalog widget. For example, if a user has entered "Big Data" into the text filter and selected Python and JavaScript from the Language checkboxes, the page URL reflects those filters with the query string 'text=Big%20Data&language=python,javascript'.

When a page containing the Catalog widget is loaded with filter parameters in the URL, the Catalog widget pre-populates the corresponding filter controls and filters results appropriately.

For example, the following is the URL for the Cloud Architecture Center demo:

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

Here are some examples of query strings that you could append to that URL:

?doctype=bestpractices checks the Best Practices checkbox in the Choose a content type section, which corresponds to the doctype filter dimension. ?doctype=bestpractices,blueprint checks both the Best Practices and Blueprint checkboxes in the same section. ?text=Cloud%20SQL populates the text filter input with "Cloud SQL".

The filter parameter dimensions can also be combined. The following URL contains both the doctype and text parameters:

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

This URL selects the appropriate checkboxes and populates the text input, as shown in the following demo.

Best Practices Blueprint Concept Pattern Reference Architecture Tutorial Best Practices Blueprint Concept Pattern Reference Architecture Tutorial

View full size