Виджеты: Каталог

Пользовательский элемент <devsite-catalog> предоставляет фильтруемый динамический контент, который включает пользовательский интерфейс фильтрации на уровне всей платформы. Он запрашивает контент, принадлежащий DevSite, для загрузки ресурсов, связанных с определенной темой, на странице DevSite. Этот настраиваемый элемент может загружать ресурсы из любого клиента DevSite, а также внешние ресурсы , добавленные в корпус внешнего контента DevSite.

Использование

Чтобы начать использовать пользовательский элемент <devsite-catalog> , выполните следующие действия:

  1. Добавьте пользовательский элемент на свою страницу.
  2. Изолируйте свой набор данных с помощью запроса динамического контента.
  3. Добавьте фильтры.
  4. Выберите параметры рендеринга.
  5. Отмечайте свой контент.
  6. Отрегулируйте макет.

Добавьте пользовательский элемент

Добавьте пользовательский элемент <devsite-catalog> на свою страницу в нужном месте.

HTML

Для страниц HTML пользовательский элемент можно добавить так же, как и любой другой элемент HTML:

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

ЯМЛ

Для строки целевой страницы с дополнительным содержимым, связанным с настраиваемым элементом, используйте строку из одного элемента с опциейdescription-100 из параметров строки целевой страницы.

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>

Вы также можете использовать поле custom_html , если вам не нужны другие поля уровня элемента, такие как heading или description :

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

Уценка

Для файлов Markdown пользовательский элемент должен быть заключен в элемент <div> или <section> :

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

Изолируйте свой набор данных

Определите запрос динамического контента , который изолирует полный набор данных, который вы хотите сделать доступным для вашего каталога, и добавьте его в атрибут запроса в новом каталоге.

Например, чтобы добавить на свою страницу каталог всех продуктов, перечисленных на сайте Developers.google.com, добавьте на свою страницу следующий каталог.

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

Добавить фильтры

Чтобы добавить фильтры в свой каталог, следуйте инструкциям ниже для каждого из следующих вариантов:

Поле ввода текста . Секция фильтров флажков сбоку.

Фильтр ввода текста

Добавьте поле ввода, которое фильтрует результаты по мере ввода пользователем текста. Поле фильтрации сопоставляет текст пользователя в заголовке, описании и ключевых словах каждого результата.

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

Фильтры-флажки

В элементе <devsite-catalog> добавьте элемент <select> для каждого фильтруемого измерения, такого как тип документа, продукт и язык программирования. Атрибут name определяет измерение фильтрации, которое соответствует структурированному пространству имен ключевых слов или имени поля DevSite, например keywords . Укажите метку измерения для ваших читателей, используя атрибут label. Обязательно укажите атрибут Multiple для каждого элемента <select> , чтобы убедиться в правильности сгенерированного пользовательского интерфейса фильтра.

Добавьте элемент <option> для каждого значения фильтра в указанном измерении в родительском элементе <select> . Укажите фильтруемое значение в атрибуте value каждого <option> . Добавьте читаемые метки фильтров между тегами <option> ; они будут переведены, если ваша страница локализована.

Следующий код добавляет раздел фильтров типов документов и фильтров ключевых слов в пользовательском интерфейсе фильтрации рядом с результатами:

<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 определяет количество фильтров флажков, отображаемых при начальной загрузке. По умолчанию — 3 .

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

Выберите параметры рендеринга

<devsite-catalog> поддерживает все параметры рендеринга и атрибуты настраиваемых элементов для виджета динамического контента.

Используйте атрибут fields , чтобы указать, какие данные вы хотите отображать на карточке вашего каталога. В дополнение к fields , задокументированным для <devsite-dynamic-content> , вы можете указать любое из документированных структурированных пространств имен ключевых слов для отображения тегов, применяемых к каждому документу в этом пространстве имен. Например, указание product приведет к тому, что все теги продукта будут применены к каждой странице, отображаемой на карточке для этой страницы. Вы также можете указать tags , чтобы просмотреть все теги номенклатуры , примененные к документу.

Следующий код настраивает приведенный выше пример для предоставления максимум 1000 результатов, отсортированных по давности, с числовым пользовательским интерфейсом с разбивкой на страницы, начиная с 9 результатов и 9 дополнительных результатов на страницу. Он настраивает отображение результатов в виде карточек с заголовком, сводкой и кнопкой с надписью «Подробнее», а также тегами для product и 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>

Если ваша команда поддерживает UXE, вы можете создать собственный шаблон для карточек каталога, добавив новый шаблон Soy в пользовательский элемент и указать новый шаблон, используя атрибут шаблона в вашем каталоге.

Отмечайте свой контент

Содержимое можно фильтровать только в том случае, если оно помечено в соответствии с вашими фильтрами. Можно добавить фильтры, используя следующие параметры:

структурированные ключевые слова с явной маркировкой (неструктурированные) ключевые слова page_type структурированные ключевые слова, выведенные из графа номенклатуры. Большинство фильтров с флажками и стилями выбора фильтруют контент в соответствии со структурированными ключевыми словами, при этом измерение фильтра должно соответствовать пространству имен структурированных ключевых слов, а значение фильтра должно соответствовать остальной части структурированное ключевое слово. Дополнительную информацию о структурированных ключевых словах и поддерживаемых пространствах имен см. в документации по номенклатуре.

Чтобы скрыть страницу из всех каталогов, установите для тега метаданных Hide_from_catalogs значение true на этой странице.

Настроить макет

Чтобы изменить макет столбца по умолчанию (два столбца для элементов template="activity" или три столбца в противном случае), добавьте атрибут items-across со значением 1 , 2 , 3 или 4 . 

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

По мере сужения области просмотра расположение элементов корректируется, чтобы обеспечить доступность содержимого элементов. Для значений items-across 3 или 4 макет переключается на два столбца на планшетах, а все макеты переключаются на один столбец на мобильных устройствах.

Примеры

Ниже приведены примеры, демонстрирующие внешний вид и функциональность основных функций пользовательского элемента <devsite-catalog> .

Центр облачной архитектуры

Ниже приведен пример каталога, используемого для Центра облачной архитектуры. Помимо title и summary , в атрибуте fields указываются product и api , чтобы добавить на карточки теги для этих пространств имен.

Демо

Посмотреть в полном размере 

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

Каталог Codelabs

Ниже приведен пример каталога кодовых лабораторий с использованием плоских ключевых слов, ненумерованной нумерации страниц и без ввода текстового фильтра.

Демо

Посмотреть в полном размере

Предварительно примененные фильтры

Виджет «Каталог» отслеживает состояние примененных пользователем фильтров в URL-адресе страницы, позволяя добавлять в закладки или делиться определенными конфигурациями фильтров. Каждое измерение фильтра представлено параметром URL. Параметры URL структурированы следующим образом:

Для элементов управления фильтрами, которые имеют одно значение, например фильтры в стиле выбора, значение параметра URL-адреса является нормализованным значением фильтра. Для элементов управления фильтрами, которые поддерживают несколько значений, например флажков, значение параметра URL представляет собой разделенный запятыми список нормализованных значений фильтра. Виджет «Каталог» не влияет на все остальные параметры URL-адреса (не фильтруемые). Например, если пользователь ввел «Большие данные» в текстовый фильтр и выбрал Python и JavaScript в флажках «Язык», URL-адрес страницы отражает эти фильтры с помощью строки запроса «text=Big%20Data&language=python,javascript».

Когда страница, содержащая виджет «Каталог», загружается с параметрами фильтра в URL-адресе, виджет «Каталог» предварительно заполняет соответствующие элементы управления фильтром и соответствующим образом фильтрует результаты.

Например, ниже приведен URL-адрес демо-версии Cloud Architecture Center :

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

Вот несколько примеров строк запроса, которые вы можете добавить к этому URL-адресу:

?doctype=bestpractices устанавливает флажок «Рекомендации» в разделе «Выберите тип контента» , который соответствует параметру фильтра doctype . ?doctype=bestpractices,blueprint устанавливает флажки Best Practices и Blueprint в одном разделе. ?text=Cloud%20SQL заполняет входные данные текстового фильтра «Cloud SQL».

Размеры параметров фильтра также можно комбинировать. Следующий URL-адрес содержит параметры типа документа и текста:

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

Этот URL-адрес устанавливает соответствующие флажки и заполняет текстовое поле, как показано в следующей демонстрации.

Посмотреть в полном размере