ווידג'טים: קטלוג

הרכיב המותאם אישית <devsite-catalog> מספק תוכן דינמי שניתן לסנן, שכולל ממשק משתמש לסינון ברמת הפלטפורמה. המערכת שולחת שאילתה לתוכן בבעלות DevSite כדי לטעון משאבים שקשורים לנושא מסוים בדף DevSite. הרכיב המותאם אישית הזה יכול לטעון משאבים מכל דייר (tenant) של DevSite, וגם ממשאבים חיצוניים שנוספו למאגר התוכן החיצוני של DevSite.

שימוש

כדי להתחיל להשתמש ברכיב המותאם אישית <devsite-catalog>, צריך לבצע את הפעולות הבאות:

  1. מוסיפים את הרכיב המותאם אישית לדף.
  2. בודד את קבוצת הנתונים באמצעות שאילתת תוכן דינמי.
  3. הוספת פילטרים.
  4. בוחרים את אפשרויות הרינדור.
  5. מתייגים את התוכן.
  6. שינוי הפריסה.

הוספת הרכיב המותאם אישית

מוסיפים את הרכיב המותאם אישית <devsite-catalog> לדף במיקום הרצוי.

HTML

בדפי HTML, אפשר להוסיף את הרכיב המותאם אישית כמו כל רכיב HTML אחר:

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

YAML

בשורה של דף נחיתה עם תוכן נוסף שקשור לאלמנט המותאם אישית, צריך להשתמש בשורה של פריט יחיד עם האפשרות תיאור 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

בקובצי Markdown, הרכיב המותאם אישית חייב להיות מוקף ברכיב <div> או <section>:

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

בידוד קבוצת הנתונים

יוצרים שאילתה של תוכן דינמי שמבודדת את מערך הנתונים המלא שרוצים שיהיה זמין בקטלוג, ומוסיפים אותו למאפיין השאילתה בקטלוג החדש.

לדוגמה, כדי להוסיף לדף שלכם קטלוג של כל המוצרים שמופיעים ב-developer.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. מציינים לקוראים תווית של מאפיין באמצעות מאפיין התווית. חשוב גם לציין את כל המאפיינים לכל רכיב <select> כדי לוודא שממשק המשתמש של המסנן שנוצר תקין.

צריך להוסיף רכיב <option> לכל ערך מסנן במאפיין שצוין ברכיב ההורה <select>. מציינים את הערך שניתן לסנן במאפיין הערך בכל <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 כדי לראות את כל התגים של נונקלאטור שהוחלו על המסמך.

הקוד הבא מגדיר את הדוגמה שלמעלה כך שיספק עד 1,000 תוצאות, שממוינות לפי עדכניות, עם ממשק משתמש מספרי של חלוקה לדפים, שמתחיל עם 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>

אם לצוות שלכם יש תמיכה בחוויית המשתמש, תוכלו ליצור תבנית מותאמת אישית לכרטיסי הקטלוג. כדי לעשות את זה, מוסיפים תבנית Soy חדשה לאלמנט המותאם אישית ומציינים את התבנית החדשה באמצעות מאפיין התבנית בקטלוג.

תיוג התוכן

ניתן לסנן תוכן רק אם הוא מתויג בהתאם למסננים שלך. אפשר להוסיף מסננים באמצעות המאפיינים הבאים:

מילות מפתח מובנות שתויגו במפורש מילות מפתח (לא מובנות) page_type מילות מפתח מובנות שנלקחו מתרשים המינוח רוב המסננים של תיבת סימון וסגנון בחירה יסוננו תוכן לפי מילות מפתח מובנות, כשמאפיין המסנן חייב להתאים למרחב שמות מובנה של מילות מפתח וערך המסנן חייב להתאים לשאר מילת המפתח המובנית. מידע נוסף על מילות מפתח מובנות ומרחבי שמות נתמכים זמין במסמכי התיעוד של Nomenclature.

כדי להסתיר דף מכל הקטלוגים, צריך להגדיר את תג המטא-נתונים consent_from_catalogs כ-true בדף הזה.

שינוי הפריסה

כדי לשנות את פריסת ברירת המחדל של העמודות (שהיא שתי עמודות בשביל template="activity" פריטים או שלוש עמודות אחרת), צריך להוסיף מאפיין לכל הפריטים עם הערך 1, 2, 3 או 4.

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

ככל שאזור התצוגה צר יותר, פריסת הפריטים משתנה כדי לוודא שהם מוצגים התוכן ימשיך להיות נגיש. לערכים של items-across של 3 או 4, הפריסה עוברת לשתי עמודות בטאבלטים, וכל הפריסות עוברות לעמודה אחת במכשירים ניידים.

דוגמאות

הדוגמאות הבאות ממחישות את המראה והפונקציונליות של התכונות הבסיסיות של הרכיב המותאם אישית <devsite-catalog>.

מרכז הארכיטקטורה של Cloud

הדוגמה הבאה היא של הקטלוג שמשמש את Cloud Architecture Center. בנוסף ל-title ול-summary, המאפיינים product ו-api במאפיין fields מוסיפים לכרטיסים תגים למרחבי השמות האלה.

הדגמה (דמו)

הצגה בגודל מלא

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

קטלוג Codelabs

הדוגמה הבאה היא של קטלוג של Codelabs עם מילות מפתח שטוחות, חלוקה לדפים לא ממוספרת ובלי קלט של מסנן טקסט.

הדגמה (דמו)

הצגה בגודל מלא

מסננים שהוחלו מראש

הווידג'ט של הקטלוג עוקב אחר מצב המסננים שהוחלו על ידי משתמשים בכתובת ה-URL של הדף. כך ניתן להוסיף הגדרות ספציפיות של מסננים לסימניות או לשתף אותן. כל מאפיין מסנן מיוצג על ידי פרמטר של כתובת אתר. המבנה של הפרמטרים של כתובת ה-URL הוא:

אם מדובר בפקדי סינון שיש להם ערך יחיד, כמו מסננים בסגנון בחירה, ערך הפרמטר של כתובת האתר הוא ערך המסנן המנורמל. בבקרות סינון שתומכים במספר ערכים, כמו תיבות סימון, ערך הפרמטר של כתובת האתר הוא רשימה של ערכי מסננים מנורמלים שמופרדים בפסיקים. כל שאר הפרמטרים של כתובות אתרים (שאינם מסננים) לא מושפעים מהווידג'ט של הקטלוג. לדוגמה, אם המשתמש הזין את הערך 'Big Data'. במסנן הטקסט ובחרתם באפשרויות 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 בודק את תיבות הסימון שיטות מומלצות וקטלוג תוכנית באותו קטע. השדה ?text=Cloud%20SQL מאכלס את הקלט של מסנן הטקסט ב-'Cloud SQL'.

אפשר גם לשלב את המאפיינים של הפרמטרים של המסנן. כתובת האתר הבאה מכילה גם את הפרמטרים doctype וגם את הפרמטרים text:

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

כתובת ה-URL הזו בוחרת את תיבות הסימון המתאימות ומאכלסת את קלט הטקסט, כמו בהדגמה הבאה.

הצגה בגודל מלא