Widgets: Katalog

Det tilpassede element <devsite-catalog> giver filtrerbart dynamisk indhold, der inkluderer en platformsdækkende filtrerings-UI. Det forespørger DevSite-ejet indhold for at indlæse ressourcer relateret til et bestemt emne på en DevSite-side. Dette brugerdefinerede element kan indlæse ressourcer fra enhver DevSite-lejer såvel som eksterne ressourcer , der er blevet tilføjet til DevSite External Content-korpus.

Brug

For at komme i gang med at bruge det tilpassede element <devsite-catalog> skal du gøre følgende:

  1. Tilføj det tilpassede element til din side.
  2. Isoler dit datasæt med en Dynamic Content-forespørgsel.
  3. Tilføj filtre.
  4. Vælg dine gengivelsesmuligheder.
  5. Tag dit indhold.
  6. Juster layout.

Tilføj det brugerdefinerede element

Tilføj det tilpassede element <devsite-catalog> til din side på den ønskede placering.

HTML

For HTML-sider kan det tilpassede element tilføjes ligesom ethvert andet HTML-element:

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

YAML

For en destinationssiderække med yderligere indhold relateret til det tilpassede element, skal du bruge en enkelt-element-række med beskrivelse-100-indstillingen fra indstillingerne for landingssiderækken.

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 også bruge et custom_html- felt, hvis du ikke har brug for andre felter på vareniveau, såsom heading eller description :

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

Markdown

For Markdown-filer skal det tilpassede element være pakket ind i et <div> eller <section> -element:

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

Isoler dit datasæt

Bestem en dynamisk indholdsforespørgsel , der isolerer det fulde datasæt, du ønsker tilgængeligt for dit katalog, og føj det til forespørgselsattributten på dit nye katalog.

Hvis du f.eks. vil tilføje et katalog over alle produkter, der er angivet på developers.google.com, til din side, skal du tilføje følgende katalog til din side.

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

Tilføj filtre

For at tilføje filtre til dit katalog skal du følge instruktionerne nedenfor for hver af følgende muligheder:

Et tekstindtastningsfelt En sektion af afkrydsningsfeltfiltre på siden

Tekstinputfilter

Tilføj et inputfelt, der filtrerer resultater, efterhånden som brugeren indtaster tekst. Filtreringsfeltet matcher brugerens tekst i titlen, beskrivelsen og nøgleordene for hvert resultat.

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

Afkrydsningsfeltfiltre

Inden for dit <devsite-catalog> -element skal du tilføje et <select> -element for hver filtrerbar dimension, såsom dokumenttype, produkt og programmeringssprog. name attributten bestemmer filtreringsdimensionen, som svarer til et struktureret nøgleordsnavneområde eller et DevSite-feltnavn såsom keywords . Angiv en dimensionsetiket til dine læsere ved hjælp af label-attributten. Sørg også for at angive multiple-attributten for hvert <select> -element for at sikre, at den genererede filter-UI er korrekt.

Tilføj et <option> -element for hver filterværdi i den angivne dimension på det overordnede <select> -element. Angiv din filtrerbare værdi i værdiattributten på hver <option> . Tilføj læsbare filteretiketter mellem dine <option> -tags; disse vil blive oversat, hvis din side er lokaliseret.

Følgende kode tilføjer en sektion af dokumenttypefiltre og nøgleordsfiltre i en filtrerings-UI til siden af ​​resultaterne:

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

Indledende afkrydsningsfeltfiltre

Attributten initial-checkbox-filters bestemmer antallet af checkbox-filtre, der skal vises ved første indlæsning. Standard er 3 .

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

Vælg dine gengivelsesmuligheder

<devsite-catalog> understøtter alle gengivelsesmuligheder og brugerdefinerede elementattributter for Dynamic Content-widgetten.

Brug fields attributten til at angive, hvilke data du vil have vist på dit katalogs kort. Ud over de fields , der er dokumenteret for <devsite-dynamic-content> , kan du angive et hvilket som helst af de dokumenterede strukturerede nøgleordsnavneområder for at gengive de tags, der er anvendt på hvert dokument i det pågældende navneområde. For eksempel vil angivelse af product resultere i, at alle produkttags, der er anvendt på hver side, gengives på kortet for den pågældende side. Du kan også angive tags for at se alle nomenklatur- tags, der er anvendt på dokumentet.

Følgende kode konfigurerer eksemplet ovenfor til at give maksimalt 1000 resultater sorteret efter seneste med en numerisk sideinddeling, der begynder med 9 resultater og 9 yderligere resultater pr. side. Den konfigurerer resultater til at blive gengivet som kort med en titel, et resumé og en knap mærket "Få flere oplysninger" samt tags for product og 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>

Hvis dit team har UXE-understøttelse, kan du oprette en brugerdefineret skabelon til dine katalogkort ved at tilføje en ny sojaskabelon til brugerdefineret element og specificering af din nye skabelon ved hjælp af skabelonattributten på dit katalog.

Tag dit indhold

Indhold kan kun filtreres, hvis det er tagget i henhold til dine filtre. Det er muligt at tilføje filtre ved hjælp af følgende dimensioner:

eksplicit taggede strukturerede søgeord (ustrukturerede) søgeord page_type strukturerede søgeord udledt af nomenklaturgrafen De fleste afkrydsningsfelter og filtre i udvalgsstil filtrerer indhold efter strukturerede søgeord, hvor filterdimensionen skal matche et struktureret søgeordsnavneområde, og filterværdien skal matche resten af det strukturerede søgeord. Se Nomenklaturdokumentationen for at få flere oplysninger om strukturerede nøgleord og understøttede navnerum.

For at skjule en side fra alle kataloger skal du indstille metadatatagget hide_from_catalogs til sand på den side.

Juster layout

For at ændre standardkolonnelayoutet (som enten er to kolonner for template="activity" -elementer eller tre kolonner på anden måde), skal du tilføje en items-across-attribut med værdien 1 , 2 , 3 eller 4 . 

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

Efterhånden som visningsporten bliver smallere, justeres elementernes layout for at sikre, at elementernes indhold forbliver tilgængeligt. For items-across værdier på 3 eller 4 skifter layoutet til to kolonner på tablets, og alle layouts skifter til en enkelt kolonne på mobilenheder.

Eksempler

Følgende er eksempler for at demonstrere udseendet og funktionaliteten af ​​de grundlæggende funktioner i det tilpassede element <devsite-catalog> .

Cloud Architecture Center

Følgende er et eksempel på det katalog, der bruges til Cloud Architecture Center. Ud over title og summary specificerer den product og api i fields for at tilføje tags for disse navneområder til kortene.

Demo

Se fuld størrelse 

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

Codelabs katalog

Det følgende er et eksempel på kataloget over codelabs, der bruger flade nøgleord, ikke-nummereret paginering og ingen tekstfilterinput.

Demo

Se fuld størrelse

Forudanvendte filtre

Katalog-widgetten sporer tilstanden af ​​brugeranvendte filtre i sidens URL, hvilket tillader, at specifikke filterkonfigurationer bogmærkes eller deles. Hver filterdimension er repræsenteret af en URL-parameter. URL-parametrene er struktureret som følger:

For filterkontrolelementer, der har en enkelt værdi, som f.eks. udvalgte filtre, er URL-parameterværdien den normaliserede filterværdi. For filterkontrolelementer, der understøtter flere værdier som afkrydsningsfelter, er URL-parameterværdien en kommasepareret liste over de normaliserede filterværdier. Alle andre URL-parametre (ikke-filter) påvirkes ikke af Catalog-widgetten. For eksempel, hvis en bruger har indtastet "Big Data" i tekstfilteret og valgt Python og JavaScript fra afkrydsningsfelterne Sprog, afspejler sidens URL disse filtre med forespørgselsstrengen 'text=Big%20Data&language=python,javascript'.

Når en side, der indeholder Katalog-widgetten, er indlæst med filterparametre i URL'en, udfylder Katalog-widgetten de tilsvarende filterkontroller og filtrerer resultaterne korrekt.

Følgende er f.eks. URL'en til Cloud Architecture Center-demoen :

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

Her er nogle eksempler på forespørgselsstrenge, som du kan føje til den pågældende URL:

?doctype=bestpractices markerer afkrydsningsfeltet Best Practices i sektionen Vælg en indholdstype , som svarer til doctype -filterdimensionen. ?doctype=bestpractices,blueprint markerer både Best Practices og Blueprint afkrydsningsfelterne i samme sektion. ?text=Cloud%20SQL udfylder tekstfilterinputtet med "Cloud SQL".

Filterparameterdimensionerne kan også kombineres. Følgende URL indeholder både doctype- og tekstparametrene:

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

Denne URL markerer de relevante afkrydsningsfelter og udfylder tekstinputtet, som vist i følgende demo.

Se fuld størrelse