Widgety: Katalog

Vlastní prvek <devsite-catalog> poskytuje filtrovatelný dynamický obsah, který zahrnuje uživatelské rozhraní filtrování pro celou platformu. Dotazuje se na obsah vlastněný DevSite, aby načetl zdroje související s konkrétním tématem na stránce DevSite. Tento vlastní prvek může načítat prostředky od libovolného tenanta DevSite i externí prostředky , které byly přidány do korpusu externího obsahu DevSite.

Používání

Chcete-li začít používat vlastní prvek <devsite-catalog> , postupujte takto:

  1. Přidejte na stránku vlastní prvek.
  2. Izolujte svou datovou sadu pomocí dotazu na dynamický obsah.
  3. Přidejte filtry.
  4. Vyberte možnosti vykreslování.
  5. Označte svůj obsah.
  6. Upravit rozložení.

Přidejte vlastní prvek

Přidejte vlastní prvek <devsite-catalog> na svou stránku v požadovaném umístění.

HTML

U stránek HTML lze vlastní prvek přidat stejně jako jakýkoli jiný prvek HTML:

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

YAML

Pro řádek vstupní stránky s dalším obsahem souvisejícím s vlastním prvkem použijte řádek s jednou položkou s možností description-100 z možností řádku vstupní stránky .

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>

Můžete také použít pole custom_html , pokud nepotřebujete žádná další pole na úrovni položky, jako je heading nebo description :

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

Snížení

U souborů Markdown musí být vlastní prvek zabalen do prvku <div> nebo <section> :

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

Izolujte svou datovou sadu

Určete dotaz na dynamický obsah , který izoluje celou datovou sadu, kterou chcete mít k dispozici pro váš katalog, a přidejte ji do atributu dotazu ve vašem novém katalogu.

Chcete-li například na svou stránku přidat katalog všech produktů uvedených na developers.google.com, přidejte na svou stránku následující katalog.

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

Přidejte filtry

Chcete-li do katalogu přidat filtry, postupujte podle pokynů níže pro každou z následujících možností:

Pole pro zadávání textu Část filtrů zaškrtávacích polí na straně

Textový vstupní filtr

Přidejte vstupní pole, které filtruje výsledky, když uživatel zadává text. Pole filtrování odpovídá textu uživatele v názvu, popisu a klíčových slovech každého výsledku.

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

Filtry zaškrtávacích políček

V rámci prvku <devsite-catalog> přidejte prvek <select> pro každou filtrovatelnou dimenzi, jako je typ dokumentu, produkt a programovací jazyk. Atribut name určuje dimenzi filtrování, která odpovídá jmennému prostoru strukturovaného klíčového slova nebo názvu pole DevSite, jako jsou keywords . Zadejte štítek rozměru pro vaše čtečky pomocí atributu štítku. Nezapomeňte také zadat atribut multiple pro každý prvek <select> , abyste zajistili správnost vygenerovaného uživatelského rozhraní filtru.

Přidejte prvek <option> pro každou hodnotu filtru v zadané dimenzi nadřazeného prvku <select> . Zadejte filtrovatelnou hodnotu v atributu value na každé <option> . Přidejte čitelné štítky filtrů mezi značky <option> ; tyto budou přeloženy, pokud je vaše stránka lokalizovaná.

Následující kód přidá část filtrů typu dokumentu a filtrů klíčových slov v uživatelském rozhraní filtrování na stranu výsledků:

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

Počáteční filtry zaškrtávacích políček

Atribut initial-checkbox-filters určuje počet filtrů zaškrtávacích polí, které se zobrazí při počátečním načtení. Výchozí hodnota je 3 .

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

Vyberte možnosti vykreslování

<devsite-catalog> podporuje všechny možnosti vykreslování a vlastní atributy prvků pro widget Dynamický obsah.

Pomocí atributu fields určete, jaká data chcete zobrazit na kartě katalogu. Kromě fields zdokumentovaných pro <devsite-dynamic-content> můžete zadat libovolný z dokumentovaných strukturovaných oborů názvů klíčových slov pro vykreslení značek použitých na každý dokument v daném oboru názvů. Například zadání product povede k tomu, že se na kartě pro danou stránku vykreslí všechny značky produktu použité na každou stránku. Můžete také určit tags , abyste viděli všechny nomenklaturní tagy použité v dokumentu.

Následující kód konfiguruje výše uvedený příklad tak, aby poskytoval maximálně 1000 výsledků seřazených podle aktuálnosti s numerickým stránkovacím uživatelským rozhraním začínajícím 9 výsledky a 9 dalšími výsledky na stránku. Konfiguruje výsledky tak, aby byly vykresleny jako karty s názvem, shrnutím a tlačítkem označeným „Další informace“ a také značkami pro product a 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>

Pokud má váš tým podporu UXE, můžete si vytvořit vlastní šablonu pro své katalogové karty přidáním nové Soy šablony do vlastní prvek a zadáním vaší nové šablony pomocí atributu šablony ve vašem katalogu.

Označte svůj obsah

Obsah lze filtrovat pouze v případě, že je označen podle vašich filtrů. Je možné přidat filtry pomocí následujících rozměrů:

explicitně označená strukturovaná klíčová slova (nestrukturovaná) klíčová slova page_type strukturovaná klíčová slova odvozená z grafu nomenklatury Většina zaškrtávacích políček a filtrů se stylem výběru bude filtrovat obsah podle strukturovaných klíčových slov, kde dimenze filtru musí odpovídat jmennému prostoru strukturovaného klíčového slova a hodnota filtru musí odpovídat zbytku strukturované klíčové slovo. Další informace o strukturovaných klíčových slovech a podporovaných jmenných prostorech najdete v dokumentaci Nomenklatury.

Chcete-li skrýt stránku ze všech katalogů, nastavte značku metadat hide_from_catalogs na této stránce na hodnotu true.

Upravit rozložení

Chcete-li změnit výchozí rozvržení sloupců (což jsou buď dva sloupce pro položky template="activity" nebo jinak tři sloupce), přidejte atribut items-across s hodnotou 1 , 2 , 3 nebo 4 .

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

Jak se výřez zužuje, rozvržení položek se přizpůsobuje tak, aby obsah položek zůstal přístupný. U items-across s hodnotami 3 nebo 4 se rozvržení na tabletech přepne na dva sloupce a na mobilních zařízeních se všechna rozvržení přepne na jeden sloupec.

Příklady

Následující příklady demonstrují vzhled a funkčnost základních funkcí vlastního prvku <devsite-catalog> .

Centrum cloudové architektury

Následuje příklad katalogu používaného pro Cloud Architecture Center. Kromě title a summary , specifikuje product a api v atributu fields pro přidání tagů pro tyto jmenné prostory na karty.

Demo

Zobrazit plnou velikost

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

Katalog kódových laboratoří

Následuje příklad katalogu kódových laboratoří používajících plochá klíčová slova, nečíslované stránkování a žádný vstup textového filtru.

Demo

Zobrazit plnou velikost

Předem aplikované filtry

Widget Katalog sleduje stav filtrů aplikovaných uživatelem v adrese URL stránky, což umožňuje přidání konkrétních konfigurací filtrů do záložek nebo sdílení. Každá dimenze filtru je reprezentována parametrem adresy URL. Parametry adresy URL mají následující strukturu:

U ovládacích prvků filtru, které mají jednu hodnotu, jako jsou filtry ve stylu výběru, je hodnotou parametru adresy URL normalizovaná hodnota filtru. U ovládacích prvků filtru, které podporují více hodnot, jako jsou zaškrtávací políčka, je hodnota parametru adresy URL seznam normalizovaných hodnot filtru oddělený čárkami. Všechny ostatní (nefiltrované) parametry URL nejsou widgetem Katalog ovlivněny. Pokud například uživatel zadal do textového filtru „Big Data“ a v zaškrtávacích políčkách Jazyk vybral Python a JavaScript , adresa URL stránky odráží tyto filtry s řetězcem dotazu 'text=Big%20Data&language=python,javascript'.

Když je stránka obsahující widget Katalog načtena s parametry filtru v adrese URL, widget Katalog předem vyplní odpovídající ovládací prvky filtru a odpovídajícím způsobem filtruje výsledky.

Zde je například adresa URL ukázky Cloud Architecture Center :

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

Zde je několik příkladů řetězců dotazů, které můžete připojit k této adrese URL:

?doctype=bestpractices zaškrtne políčko Nejlepší postupy v části Zvolte typ obsahu , které odpovídá dimenzi filtru doctype . ?doctype=bestpractices,blueprint zaškrtne políčka Best Practices a Blueprint ve stejné sekci. ?text=Cloud%20SQL naplní vstup textového filtru "Cloud SQL".

Rozměry parametrů filtru lze také kombinovat. Následující adresa URL obsahuje parametry doctype i text:

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

Tato adresa URL zaškrtne příslušná zaškrtávací políčka a vyplní textový vstup, jak je znázorněno v následující ukázce.

Zobrazit plnou velikost