ابزارک: کاتالوگ

عنصر سفارشی <devsite-catalog> محتوای پویا قابل فیلتر را ارائه می دهد که شامل یک رابط کاربری فیلترینگ در سطح پلت فرم است. محتوای متعلق به DevSite را برای بارگیری منابع مربوط به یک موضوع خاص در صفحه DevSite جستجو می کند. این عنصر سفارشی می تواند منابع را از هر مستأجر DevSite و همچنین منابع خارجی که به مجموعه محتوای خارجی DevSite اضافه شده است بارگیری کند.

استفاده

برای شروع استفاده از عنصر سفارشی <devsite-catalog> ، موارد زیر را انجام دهید:

  1. عنصر سفارشی را به صفحه خود اضافه کنید.
  2. مجموعه داده های خود را با پرس و جوی محتوای پویا جدا کنید.
  3. فیلترها را اضافه کنید.
  4. گزینه های رندر خود را انتخاب کنید.
  5. مطالب خود را تگ کنید.
  6. چیدمان را تنظیم کنید.

عنصر سفارشی را اضافه کنید

عنصر سفارشی <devsite-catalog> را در محل مورد نظر به صفحه خود اضافه کنید.

HTML

برای صفحات HTML، عنصر سفارشی را می توان مانند هر عنصر HTML دیگر اضافه کرد:

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

YAML

برای یک ردیف صفحه فرود با محتوای اضافی مرتبط با عنصر سفارشی، از یک ردیف تک موردی با گزینه description-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>

همچنین اگر به فیلدهای سطح مورد دیگری مانند heading یا description نیاز ندارید، می توانید از یک فیلد custom_html استفاده کنید:

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

مارک داون

برای فایل‌های Markdown، عنصر سفارشی باید در یک عنصر <div> یا <section> پیچیده شود:

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

مجموعه داده های خود را ایزوله کنید

یک جستار محتوای پویا را تعیین کنید که مجموعه داده کاملی را که می‌خواهید در کاتالوگ شما در دسترس باشد جدا کند و آن را به ویژگی query در کاتالوگ جدید خود اضافه کنید.

به عنوان مثال، برای افزودن کاتالوگ تمام محصولات فهرست شده در developers.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 است. با استفاده از ویژگی label یک برچسب بعد برای خوانندگان خود مشخص کنید. مطمئن شوید که برای هر عنصر <select> ویژگی چندگانه را مشخص کرده اید تا اطمینان حاصل کنید که رابط کاربری فیلتر ایجاد شده درست است.

یک عنصر <option> برای هر مقدار فیلتر در بعد مشخص شده در عنصر والد <select> اضافه کنید. مقدار قابل فیلتر خود را در ویژگی value در هر <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 را برای مشاهده تمام برچسب‌های نام‌گذاری اعمال شده بر روی سند مشخص کنید.

کد زیر مثال بالا را به گونه ای پیکربندی می کند که حداکثر 1000 نتیجه مرتب شده بر اساس تازگی با یک UI صفحه بندی عددی که با 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>

اگر تیم شما از UXE پشتیبانی می کند، می توانید با افزودن یک الگوی جدید سویا به کارت های کاتالوگ خود یک الگوی سفارشی ایجاد کنید. عنصر سفارشی و تعیین الگوی جدید خود با استفاده از ویژگی template در کاتالوگ خود.

مطالب خود را تگ کنید

محتوا فقط در صورتی قابل فیلتر است که بر اساس فیلترهای شما برچسب گذاری شده باشد. امکان افزودن فیلترها با استفاده از ابعاد زیر وجود دارد:

کلمات کلیدی ساختاریافته با برچسب صریح (بدون ساختار) کلمات کلیدی page_type کلمات کلیدی ساختار یافته استنتاج شده از نمودار نامگذاری اکثر چک باکس و فیلترهای سبک انتخابی محتوا را بر اساس کلمات کلیدی ساختاریافته فیلتر می کنند، جایی که بعد فیلتر باید با فضای نام کلمه کلیدی ساختاریافته مطابقت داشته باشد و مقدار فیلتر باید با باقیمانده آن مطابقت داشته باشد. کلمه کلیدی ساختار یافته برای اطلاعات بیشتر در مورد کلمات کلیدی ساختاریافته و فضاهای نام پشتیبانی شده به مستندات نامگذاری مراجعه کنید.

برای مخفی کردن یک صفحه از همه کاتالوگ ها، تگ metadata hide_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> آورده شده است.

مرکز معماری ابر

نمونه زیر نمونه ای از کاتالوگ مورد استفاده برای مرکز معماری ابری است. علاوه بر title و summary ، product و api را در ویژگی fields مشخص می‌کند تا تگ‌هایی برای این فضاهای نام به کارت‌ها اضافه شود.

نسخه ی نمایشی

مشاهده در اندازه کامل 

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

کاتالوگ Codelabs

در زیر نمونه ای از کاتالوگ کدهای با استفاده از کلمات کلیدی مسطح، صفحه بندی بدون شماره و بدون ورودی فیلتر متن است.

نسخه ی نمایشی

مشاهده در اندازه کامل

فیلترهای از پیش اعمال شده

ویجت کاتالوگ وضعیت فیلترهای اعمال شده توسط کاربر را در URL صفحه ردیابی می کند و به پیکربندی های خاص فیلتر امکان نشانک گذاری یا اشتراک گذاری را می دهد. هر بعد فیلتر با یک پارامتر URL نشان داده می شود. ساختار پارامترهای URL به صورت زیر است:

برای کنترل‌های فیلتر که دارای یک مقدار واحد مانند فیلترهای انتخاب سبک هستند، مقدار پارامتر URL مقدار فیلتر نرمال شده است. برای کنترل‌های فیلتر که از چندین مقدار مانند چک باکس‌ها پشتیبانی می‌کنند، مقدار پارامتر URL فهرستی از مقادیر فیلتر نرمال شده با کاما است. همه پارامترهای URL دیگر (غیر فیلتر) تحت تأثیر ویجت کاتالوگ قرار نمی گیرند. به عنوان مثال، اگر کاربری "Big Data" را در فیلتر متن وارد کرده باشد و پایتون و جاوا اسکریپت را از چک باکس های زبان انتخاب کرده باشد، URL صفحه آن فیلترها را با رشته پرس و جو 'text=Big%20Data&language=python,javascript' منعکس می کند.

هنگامی که صفحه ای حاوی ویجت کاتالوگ با پارامترهای فیلتر در URL بارگذاری می شود، ویجت کاتالوگ کنترل های فیلتر مربوطه را از قبل پر می کند و نتایج را به طور مناسب فیلتر می کند.

به عنوان مثال، آدرس زیر برای نسخه نمایشی Cloud Architecture Center است:

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

در اینجا چند نمونه از رشته های پرس و جو وجود دارد که می توانید به آن URL اضافه کنید:

?doctype=bestpractices چک باکس Best Practices را در بخش Choose a content type ، که با بعد فیلتر doctype مطابقت دارد، بررسی می کند. ?doctype=bestpractices,blueprint چک باکس های بهترین روش ها و طرح طرح را در همان بخش بررسی می کند. ?text=Cloud%20SQL ورودی فیلتر متن را با "Cloud SQL" پر می کند.

ابعاد پارامتر فیلتر نیز می تواند ترکیب شود. URL زیر حاوی پارامترهای doctype و text است:

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

این URL چک باکس های مناسب را انتخاب می کند و ورودی متن را پر می کند، همانطور که در نسخه نمایشی زیر نشان داده شده است.

مشاهده در اندازه کامل