Widget: Katalog

Elemen kustom <devsite-catalog> menyediakan konten dinamis yang dapat difilter yang menyertakan UI pemfilteran tingkat platform. Alat ini mengkueri konten milik DevSite untuk memuat resource yang terkait dengan topik tertentu di halaman DevSite. Elemen kustom ini dapat memuat resource dari tenant DevSite mana pun serta resource eksternal yang telah ditambahkan ke korpus Konten Eksternal DevSite.

Penggunaan

Untuk mulai menggunakan elemen kustom <devsite-catalog>, lakukan hal berikut:

  1. Tambahkan elemen kustom ke halaman Anda.
  2. Pisahkan set data Anda dengan kueri Konten Dinamis.
  3. Tambahkan filter.
  4. Pilih opsi rendering Anda.
  5. Memberi tag pada konten Anda.
  6. Sesuaikan tata letak.

Menambahkan elemen kustom

Tambahkan elemen kustom <devsite-catalog> ke halaman Anda di lokasi yang diinginkan.

HTML

Untuk halaman HTML, elemen kustom dapat ditambahkan seperti elemen HTML lainnya:

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

YAML

Untuk baris halaman landing dengan konten tambahan yang terkait dengan elemen kustom, gunakan baris satu item dengan opsi deskripsi-100 dari opsi baris halaman landing.

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>

Anda juga dapat menggunakan kolom custom_html jika tidak memerlukan kolom tingkat item lain seperti heading atau description:

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

Markdown

Untuk file Markdown, elemen kustom harus digabungkan dalam elemen <div> atau <section>:

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

Pisahkan set data Anda

Tentukan kueri Konten Dinamis yang mengisolasi set data lengkap yang ingin Anda sediakan untuk katalog Anda dan menambahkannya ke atribut kueri di katalog baru Anda.

Misalnya, untuk menambahkan katalog semua produk yang tercantum di Developers.google.com ke halaman Anda, tambahkan katalog berikut ke halaman Anda.

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

Tambahkan filter

Untuk menambahkan filter ke katalog Anda, ikuti petunjuk di bawah untuk setiap opsi berikut:

Kotak input teks Bagian filter kotak centang di samping

Filter input teks

Tambahkan kotak input yang memfilter hasil saat pengguna memasukkan teks. Kotak pemfilteran akan mencocokkan teks pengguna di dalam judul, deskripsi, dan kata kunci dari setiap hasil.

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

Filter kotak centang

Dalam elemen <devsite-catalog>, tambahkan elemen <select> untuk setiap dimensi yang dapat difilter seperti jenis dokumen, produk, dan bahasa pemrograman. Atribut name menentukan dimensi pemfilteran, yang sesuai dengan namespace kata kunci terstruktur atau nama kolom DevSite seperti keywords. Tentukan label dimensi untuk pembaca Anda menggunakan atribut label. Pastikan untuk menentukan beberapa atribut untuk setiap elemen <select> juga guna memastikan UI filter yang dihasilkan sudah benar.

Tambahkan elemen <option> untuk setiap nilai filter dalam dimensi yang ditentukan pada elemen <select> induk. Tentukan nilai yang dapat difilter dalam atribut nilai di setiap <option>. Menambahkan label filter yang dapat dibaca di antara tag <option>; terjemahan ini akan diterjemahkan jika laman Anda dilokalkan.

Kode berikut menambahkan bagian filter jenis dokumen dan filter kata kunci dalam UI pemfilteran ke samping hasil:

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

Filter kotak centang awal

Atribut initial-checkbox-filters menentukan filter kotak centang angka untuk ditampilkan pada pemuatan awal. Default-nya adalah 3.

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

Memilih opsi rendering

<devsite-catalog> mendukung semua opsi rendering dan atribut elemen khusus untuk widget Konten Dinamis.

Gunakan atribut fields untuk menentukan data yang ingin Anda tampilkan di kartu katalog Anda. Selain fields yang didokumentasikan untuk <devsite-dynamic-content>, Anda dapat menentukan namespace kata kunci terstruktur apa pun yang didokumentasikan untuk merender tag yang diterapkan ke setiap dokumen di namespace tersebut. Misalnya, menentukan product akan menyebabkan semua tag produk diterapkan ke setiap halaman dirender pada kartu untuk halaman tersebut. Anda juga dapat menentukan tags untuk melihat semua tag Nomenklatur yang diterapkan pada dokumen.

Kode berikut mengonfigurasi contoh di atas untuk memberikan maksimum 1000 hasil yang diurutkan berdasarkan keterkinian dengan UI penomoran halaman numerik yang dimulai dengan 9 hasil dan 9 hasil tambahan per halaman. Fitur ini mengonfigurasi hasil untuk dirender sebagai kartu dengan judul, ringkasan, dan tombol berlabel "Pelajari lebih lanjut" serta tag untuk product dan 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>

Jika tim Anda memiliki dukungan UXE, Anda dapat membuat template kustom untuk kartu katalog dengan menambahkan template Soy baru ke elemen kustom dan menentukan template baru menggunakan atribut template di katalog Anda.

Berikan tag pada konten Anda

Konten hanya dapat difilter jika diberi tag sesuai dengan filter Anda. Anda dapat menambahkan filter menggunakan dimensi berikut:

kata kunci terstruktur yang diberi tag secara eksplisit kata kunci (tidak terstruktur) page_type kata kunci terstruktur yang disimpulkan dari grafik Nomenklatur Sebagian besar filter kotak centang dan gaya pilih akan memfilter konten sesuai dengan kata kunci terstruktur, dengan dimensi filter harus cocok dengan namespace kata kunci terstruktur dan nilai filter harus cocok dengan kata kunci terstruktur lainnya. Lihat dokumentasi Nomenklatur untuk informasi selengkapnya tentang kata kunci terstruktur dan namespace yang didukung.

Untuk menyembunyikan halaman dari semua katalog, tetapkan tag metadata hide_from_catalogs ke benar (true) di halaman tersebut.

Sesuaikan tata letak

Untuk mengubah tata letak kolom default (yaitu dua kolom untuk item template="activity" atau tiga kolom), tambahkan atribut item di seluruh dengan nilai 1, 2, 3, atau 4.

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

Saat area pandang semakin sempit, tata letak item akan disesuaikan untuk memastikan tetap dapat diakses. Untuk nilai items-across dari 3 atau 4, tata letak beralih ke dua kolom di tablet, dan semua tata letak beralih ke satu kolom di perangkat seluler.

Contoh

Berikut adalah contoh untuk menunjukkan tampilan dan fungsi fitur dasar dari elemen kustom <devsite-catalog>.

Cloud Architecture Center

Berikut adalah contoh katalog yang digunakan untuk Pusat Arsitektur Cloud. Selain title dan summary, parameter ini juga menentukan product dan api di atribut fields guna menambahkan tag untuk namespace ini ke kartu.

Demo

Lihat ukuran penuh

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

Katalog Codelabs

Berikut adalah contoh katalog codelab yang menggunakan kata kunci datar, penomoran halaman tanpa nomor, dan tanpa input filter teks.

Demo

Lihat ukuran penuh

Filter yang telah diterapkan sebelumnya

Widget Katalog melacak status filter yang diterapkan pengguna di URL halaman, sehingga konfigurasi filter tertentu dapat di-bookmark atau dibagikan. Setiap dimensi filter ditunjukkan oleh parameter URL. Struktur parameter URL adalah sebagai berikut:

Untuk kontrol filter yang memiliki satu nilai seperti filter gaya tertentu, nilai parameter URL adalah nilai filter yang dinormalkan. Untuk kontrol filter yang mendukung beberapa nilai seperti kotak centang, nilai parameter URL adalah daftar yang dipisahkan koma dari nilai filter yang dinormalkan. Semua parameter URL (non-filter) lainnya tidak terpengaruh oleh widget Katalog. Misalnya, jika pengguna telah memasukkan "Big Data" ke dalam filter teks dan memilih Python dan JavaScript dari kotak centang Language, URL halaman mencerminkan filter tersebut dengan string kueri 'text=Big%20Data&language=python,javascript'.

Saat halaman yang berisi widget Katalog dimuat dengan parameter filter dalam URL, widget Katalog akan mengisi otomatis kontrol filter yang sesuai dan hasil filter yang sesuai.

Misalnya, berikut adalah URL untuk demo Pusat Arsitektur Cloud:

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

Berikut adalah beberapa contoh string kueri yang dapat Anda tambahkan ke URL tersebut:

?doctype=bestpractices mencentang kotak Praktik Terbaik di bagian Pilih jenis konten, yang sesuai dengan dimensi filter doctype. ?doctype=bestpractices,blueprint mencentang kotak Praktik Terbaik dan Blueprint di bagian yang sama. ?text=Cloud%20SQL mengisi input filter teks dengan "Cloud SQL".

Dimensi parameter filter juga dapat digabungkan. URL berikut berisi parameter doctype dan teks:

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

URL ini memilih kotak centang yang sesuai dan mengisi input teks, seperti yang ditunjukkan pada demo berikut.

Lihat ukuran penuh