このページは Cloud Translation API によって翻訳されました。

ウィジェット: カタログ

<devsite-catalog> カスタム要素は、プラットフォーム全体のフィルタリング UI を含むフィルタリング可能な動的コンテンツを提供します。DevSite が所有するコンテンツをクエリして、DevSite ページ上の特定のトピックに関連するリソースを読み込みます。このカスタム要素では、任意の DevSite テナントからリソースを読み込めるだけでなく、DevSite 外部コンテンツコーパスに追加されている外部リソースも読み込むことができます。

用途

<devsite-catalog> カスタム要素の使用を開始する手順は次のとおりです。

カスタム要素を追加する

カスタム要素 <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>

データセットの分離

カタログで使用したいデータセット全体を分離する動的コンテンツクエリを決定し、それを新しいカタログのクエリ属性に追加します。

たとえば、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 属性を使用して、読者に表示するディメンションラベルを指定します。生成されたフィルタ UI が正しく動作するように、各 <select> 要素に複数の属性を指定してください。

親 <select> 要素の指定されたディメンションの各フィルタ値に <option> 要素を追加します。各 <option> の value 属性にフィルタ可能な値を指定します。<option> タグの間に読み取り可能なフィルタラベルを追加します。ページがローカライズされている場合は、これらのテキストが翻訳されます。

次のコードは、結果の横にドキュメントタイプフィルタとキーワードフィルタのセクションをフィルタリング UI に追加します。

<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 属性を使用して、カタログのカードに表示するデータを指定します。<devsite-dynamic-content> のドキュメントに記載されている fields に加えて、ドキュメントに記載された構造化キーワードの名前空間のいずれかを指定して、その名前空間内の各ドキュメントに適用されるタグをレンダリングできます。たとえば、product を指定すると、各ページに適用されているすべての商品タグが、そのページのカードにレンダリングされます。tags を指定して、ドキュメントに適用されたすべての Nomenclature タグを表示することもできます。

次のコードでは、最大 1,000 件の結果を新しい順に並べ、各ページにつき 9 件の結果と 9 件の追加結果を表示する数値ページネーション UI を使用するように、上記の例を設定しています。検索結果は、タイトル、概要、[詳細] ボタンが付いたカードとしてレンダリングされるように構成します。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 のサポートを担当するチームでは、カタログカードのカスタムテンプレートを作成できます。そのためには、カスタム要素に新しい大豆テンプレートを追加し、カタログのテンプレート属性を使用して新しいテンプレートを指定します。

コンテンツにタグを付ける

コンテンツにフィルタを適用できるのは、指定したフィルタに従ってタグ付けされている場合だけです。フィルタを追加するには、次のディメンションを使用します。

明示的にタグ付けした構造化キーワード（非構造化）キーワード page_type 命名グラフから推定される構造化キーワードほとんどのチェックボックスフィルタや選択スタイルのフィルタは、構造化キーワードに従ってコンテンツをフィルタします。フィルタのディメンションは構造化キーワードの名前空間と一致し、フィルタ値は構造化キーワードの残りの部分と一致している必要があります。構造化キーワードとサポートされている名前空間の詳細については、命名法のドキュメントをご覧ください。

特定のページをすべてのカタログで非表示にするには、そのページで hide_from_catalogs メタデータタグを true に設定します。

レイアウトを調整する

デフォルトの列レイアウト（template="activity" アイテムの場合は 2 列、それ以外の場合は 3 列）を変更するには、1、2、3、または 4 の値を持つ items-cross 属性を追加します。

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

ビューポートが狭くなると、アイテムのレイアウトが調整され、コンテンツに引き続きアクセスできます。items-across の値が 3 または 4 の場合、タブレットではレイアウトが 2 列に切り替わり、モバイルデバイスではすべてのレイアウトが 1 列に切り替わります。

例

次の例は、<devsite-catalog> カスタム要素の基本機能の外観と機能を示しています。

Cloud アーキテクチャセンター

Cloud アーキテクチャセンターに使用するカタログの例を次に示します。title と summary に加え、fields 属性に product と api を指定して、これらの名前空間のタグをカードに追加します。

デモ

フルサイズで表示

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

Codelabs カタログ

以下に、フラットキーワード、番号なしのページ分割、テキストフィルタ入力を使用しない Codelab のカタログの例を示します。

デモ

フルサイズで表示

事前適用フィルタ

カタログウィジェットは、ユーザーがページ URL に適用したフィルタの状態を追跡します。これにより、特定のフィルタ構成をブックマークしたり、共有したりできます。各フィルタディメンションは URL パラメータで表されます。URL パラメータの構造は次のとおりです。

選択スタイルのフィルタのように単一の値を持つフィルタオプションの場合、URL パラメータ値は正規化されたフィルタ値です。チェックボックスのように複数の値をサポートするフィルタオプションの場合、URL パラメータ値は正規化されたフィルタ値のカンマ区切りのリストです。その他の（フィルタされていない）URL パラメータはすべて、カタログウィジェットの影響を受けません。たとえば、ユーザーが「Big Data」と入力し、にテキストフィルタを入力し、[言語] チェックボックスで [Python] と [JavaScript] を選択した場合、ページ URL にはクエリ文字列「text=Big%20Data&language=python,javascript」のフィルタが反映されます。

Catalog ウィジェットを含むページが URL にフィルタパラメータとともに読み込まれると、Catalog ウィジェットでは対応するフィルタオプションが事前入力され、結果が適切にフィルタされます。

たとえば、Cloud アーキテクチャセンターのデモの URL は次のとおりです。

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

この URL に追加できるクエリ文字列の例を次に示します。

?doctype=bestpractices は、doctype フィルタディメンションに対応する [コンテンツタイプを選択する] セクションの [ベストプラクティス] チェックボックスをオンにします。 ?doctype=bestpractices,blueprint は、同じセクションの [Best Practices] と [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 で適切なチェックボックスが選択され、テキスト入力が行われます。

フルサイズで表示

ウィジェット: カタログ

用途

カスタム要素を追加する

HTML

YAML

マークダウン

データセットの分離

フィルタの追加

テキスト入力フィルタ

チェックボックス フィルタ

初期チェックボックス フィルタ

レンダリング オプションを選択する

コンテンツにタグを付ける

レイアウトを調整する

例

Cloud アーキテクチャ センター

デモ

Codelabs カタログ

デモ

事前適用フィルタ

チェックボックスフィルタ

初期チェックボックスフィルタ

レンダリングオプションを選択する

Cloud アーキテクチャセンター