Widgets: Katalog

Det anpassade elementet <devsite-catalog> tillhandahåller filtrerbart dynamiskt innehåll som inkluderar ett plattformsomfattande filtreringsgränssnitt. Den frågar DevSite-ägt innehåll för att ladda resurser relaterade till ett visst ämne på en DevSite-sida. Det här anpassade elementet kan ladda resurser från alla DevSite-hyresgäster såväl som externa resurser som har lagts till i DevSite External Content-korpusen.

Användande

För att komma igång med det anpassade elementet <devsite-catalog> gör du följande:

  1. Lägg till det anpassade elementet på din sida.
  2. Isolera din datamängd med en Dynamic Content-fråga.
  3. Lägg till filter.
  4. Välj dina renderingsalternativ.
  5. Tagga ditt innehåll.
  6. Justera layouten.

Lägg till det anpassade elementet

Lägg till det anpassade elementet <devsite-catalog> på din sida på önskad plats.

HTML

För HTML-sidor kan det anpassade elementet läggas till precis som alla andra HTML-element:

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

YAML

För en målsidesrad med ytterligare innehåll relaterat till det anpassade elementet, använd en rad med en enda artikel med alternativet description-100 från alternativen för målsidesraden .

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>

Du kan också använda ett custom_html- fält om du inte behöver några andra fält på objektnivå som heading eller description :

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

Prissänkning

För Markdown-filer måste det anpassade elementet vara inpackat i ett <div> eller <section> -element:

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

Isolera din datamängd

Bestäm en dynamiskt innehållsfråga som isolerar hela datauppsättningen du vill ha tillgänglig för din katalog och lägg till den i frågeattributet i din nya katalog.

Om du till exempel vill lägga till en katalog över alla produkter som finns listade på developers.google.com på din sida lägger du till följande katalog på din sida.

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

Lägg till filter

För att lägga till filter i din katalog, följ instruktionerna nedan för vart och ett av följande alternativ:

En textinmatningsruta En del av kryssrutefilter på sidan

Textinmatningsfilter

Lägg till en inmatningsruta som filtrerar resultat när användaren skriver in text. Filtreringsrutan matchar användarens text i titeln, beskrivningen och nyckelorden för varje resultat.

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

Kryssrutafilter

Inom ditt <devsite-catalog> -element lägger du till ett <select> -element för varje filtrerbar dimension som dokumenttyp, produkt och programmeringsspråk. Attributet name bestämmer filtreringsdimensionen, som motsvarar ett strukturerat nyckelordsnamnområde eller ett DevSite-fältnamn som keywords . Ange en dimensionsetikett för dina läsare med hjälp av etikettattributet. Var noga med att specificera flera attribut för varje <select> -element för att säkerställa att det genererade filtergränssnittet är korrekt.

Lägg till ett <option> -element för varje filtervärde i den angivna dimensionen på det överordnade <select> -elementet. Ange ditt filtrerbara värde i värdeattributet på varje <option> . Lägg till läsbara filteretiketter mellan dina <option> -taggar; dessa kommer att översättas om din sida är lokaliserad.

Följande kod lägger till ett avsnitt med dokumenttypsfilter och nyckelordsfilter i ett filtreringsgränssnitt vid sidan av resultaten:

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

Inledande kryssrutefilter

Attributet initial-checkbox-filters bestämmer antalet checkbox-filter som ska visas vid initial laddning. Standard är 3 .

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

Välj dina renderingsalternativ

<devsite-catalog> stöder alla renderingsalternativ och anpassade elementattribut för widgeten Dynamic Content.

Använd fields attributet för att ange vilken data du vill visa på din katalogs kort. Utöver de fields som dokumenterats för <devsite-dynamic-content> kan du ange vilket som helst av de dokumenterade strukturerade nyckelordsnamnrymden för att återge taggarna som tillämpas på varje dokument i det namnutrymmet. Om du till exempel specificerar product kommer alla produkttaggar som appliceras på varje sida att renderas på kortet för den sidan. Du kan också ange tags för att se alla nomenklaturtaggar som tillämpas på dokumentet.

Följande kod konfigurerar exemplet ovan för att ge maximalt 1 000 resultat sorterade efter senaste uppdatering med ett numerisk sidnumreringsgränssnitt som börjar med 9 resultat och 9 ytterligare resultat per sida. Den konfigurerar resultat för att renderas som kort med en titel, sammanfattning och knapp märkt "Läs mer" samt taggar för product och 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>

Om ditt team har UXE-stöd kan du skapa en anpassad mall för dina katalogkort genom att lägga till en ny sojamall till anpassat element och ange din nya mall med malattributet i din katalog.

Tagga ditt innehåll

Innehåll kan bara filtreras om det är taggat enligt dina filter. Det är möjligt att lägga till filter med följande dimensioner:

explicit taggade strukturerade sökord (ostrukturerade) sökord page_type strukturerade sökord härledda från nomenklaturdiagrammet De flesta kryssruta- och urvalsfilter filtrerar innehåll enligt strukturerade sökord, där filterdimensionen måste matcha ett strukturerat sökordsnamnområde och filtervärdet måste matcha resten av det strukturerade nyckelordet. Se Nomenklaturdokumentationen för mer information om strukturerade nyckelord och namnrymder som stöds.

För att dölja en sida från alla kataloger, ställ in metadatataggen hide_from_catalogs till true på den sidan.

Justera layouten

För att ändra standardkolumnlayouten (som antingen är två kolumner för template="activity" -objekt eller tre kolumner annars), lägg till ett objekt-över-attribut med värdet 1 , 2 , 3 eller 4 . 

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

När visningsporten blir smalare justeras objektens layout för att säkerställa att objektens innehåll förblir tillgängligt. För items-across värden på 3 eller 4 växlar layouten till två kolumner på surfplattor och alla layouter växlar till en enda kolumn på mobila enheter.

Exempel

Följande är exempel för att demonstrera utseendet och funktionen hos de grundläggande funktionerna i det anpassade elementet <devsite-catalog> .

Cloud Architecture Center

Följande är ett exempel på katalogen som används för Cloud Architecture Center. Förutom title och summary anger den product och api i fields för att lägga till taggar för dessa namnområden på korten.

Demo

Visa full storlek 

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

Codelabs katalog

Följande är ett exempel på katalogen med codelabs som använder platta nyckelord, icke-numrerad sidnumrering och ingen textfilterinmatning.

Demo

Visa full storlek

Föranvända filter

Katalogwidgeten spårar tillståndet för användartillämpade filter i sidans URL, vilket gör att specifika filterkonfigurationer kan bokmärkas eller delas. Varje filterdimension representeras av en URL-parameter. URL-parametrarna är strukturerade enligt följande:

För filterkontroller som har ett enstaka värde som filter i urvalsstil är URL-parametervärdet det normaliserade filtervärdet. För filterkontroller som stöder flera värden som kryssrutor är URL-parametervärdet en kommaseparerad lista över de normaliserade filtervärdena. Alla andra (icke-filter) URL-parametrar påverkas inte av Catalog-widgeten. Om en användare till exempel har angett "Big Data" i textfiltret och valt Python och JavaScript från kryssrutorna Språk, återspeglar sidans URL dessa filter med frågesträngen 'text=Big%20Data&language=python,javascript'.

När en sida som innehåller katalogwidgeten laddas med filterparametrar i webbadressen, fyller katalogwidgeten i förväg motsvarande filterkontroller och filtrerar resultaten på lämpligt sätt.

Följande är till exempel URL:en för Cloud Architecture Center-demon :

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

Här är några exempel på frågesträngar som du kan lägga till den webbadressen:

?doctype=bestpractices markerar kryssrutan Bästa metoder i avsnittet Välj en innehållstyp , som motsvarar filterdimensionen doctype . ?doctype=bestpractices,blueprint markerar både Bästa praxis och Blueprint kryssrutorna i samma avsnitt. ?text=Cloud%20SQL fyller textfiltret med "Cloud SQL".

Filterparameterdimensionerna kan också kombineras. Följande URL innehåller både doctype- och textparametrarna:

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

Denna URL markerar lämpliga kryssrutor och fyller i textinmatningen, som visas i följande demo.

Visa full storlek