検索ウィジェットは、ウェブ アプリケーション用のカスタマイズ可能な検索インターフェースを提供します。ウィジェットでは、少量の HTML と JavaScript のみを使用してファセットやページ分割などの一般的な検索機能を実装し、有効にすることができます。CSS や JavaScript を使用してインターフェースの一部をカスタマイズすることもできます。
ウィジェットで提供される以上の柔軟性が必要な場合は、Query API の使用を検討してください。Query API を使用して検索インターフェースを作成する方法については、Query API を使用した検索インターフェースの作成をご覧ください。
検索インターフェースを作成する
検索インターフェースを作成するには、いくつかの手順が必要です。
- 検索アプリケーションを構成する
- アプリケーションのクライアント ID を生成する
- 検索ボックスと結果用の HTML マークアップを追加する
- ページにウィジェットを読み込む
- ウィジェットを初期化する
検索アプリケーションを構成する
各検索インターフェースには、管理コンソールで定義された検索アプリケーションが必要です。検索アプリケーションは、データソース、ファセット、検索品質設定などのクエリに関する追加情報を提供します。
検索アプリケーションを作成するには、カスタム検索アプリケーションを作成するをご覧ください。
アプリケーションのクライアント ID を生成する
Google Cloud Search API へのアクセスを構成するの手順に加えて、ウェブ アプリケーションのクライアント ID も生成する必要があります。
プロジェクトを構成するには:
- ウェブブラウザのクライアント タイプを選択します。
- アプリの生成元 URI を指定します。
- 作成されたクライアント ID をメモします。次の手順を完了するには、クライアント ID が必要です。ウィジェットにはクライアント シークレットは必要ありません。
詳細については、クライアント側ウェブ アプリケーションの OAuth 2.0 をご覧ください。
HTML マークアップを追加する
ウィジェットが機能するには、少量の HTML が必要です。次の情報を指定する必要があります。
- 検索ボックスの
input
要素。 - 候補ポップアップを固定するための要素。
- 検索結果を格納する要素。
- (省略可)ファセット コントロールを格納する要素を指定します。
次の HTML スニペットは、バインドする要素が id
属性で識別される検索ウィジェットの HTML を示しています。
ウィジェットを読み込む
ウィジェットは、ローダー スクリプトを介して動的に読み込まれます。ローダーを含めるには、次のように <script>
タグを使用します。
スクリプトタグで onload
コールバックを指定する必要があります。この関数は、ローダーの準備ができると呼び出されます。ローダーの準備ができたら、gapi.load()
を呼び出して API クライアント、Google ログイン、Cloud Search の各モジュールを読み込み、ウィジェットの読み込みを続けます。
initializeApp()
関数は、すべてのモジュールが読み込まれた後に呼び出されます。
ウィジェットを初期化する
まず、生成されたクライアント ID と https://www.googleapis.com/auth/cloud_search.query
スコープを使用して gapi.client.init()
または gapi.auth2.init()
を呼び出し、クライアント ライブラリを初期化します。次に、gapi.cloudsearch.widget.resultscontainer.Builder
クラスと gapi.cloudsearch.widget.searchbox.Builder
クラスを使用してウィジェットを構成し、HTML 要素にバインドします。
次の例は、ウィジェットを初期化する方法を示しています。
上記の例では、次のように定義された 2 つの変数を構成のために参照しています。
ログイン エクスペリエンスをカスタマイズする
デフォルトでは、ウィジェットはユーザーがクエリの入力を開始した際に、ログインしてアプリを承認するように求めます。ウェブサイト用の Google ログインを使用すると、ユーザーに合わせてカスタマイズしたログイン方式を提供できます。
ユーザーを直接承認する
Google でログインを使用して、ユーザーのログイン状態をモニタリングし、必要に応じてユーザーのログインやログアウトを行います。たとえば、次の例では、isSignedIn
状態を監視してログイン変更をモニタリングし、GoogleAuth.signIn()
メソッドを使用してボタンのクリックからログインを開始します。
詳細については、「Google でログイン」をご覧ください。
ユーザーを自動的にログインさせる
組織内のユーザーに代わってアプリケーションを事前に承認することで、ログイン方式をさらに簡素化できます。この手法は、Cloud Identity Aware Proxy を使用してアプリケーションを保護する場合にも役立ちます。
詳細については、IT アプリで Google ログインを使用するをご覧ください。
インターフェースをカスタマイズする
検索インターフェースの外観は、複数の手法を組み合わせて変更できます。
- CSS でスタイルをオーバーライドする
- 要素をアダプタで修飾する
- アダプタを使用してカスタム要素を作成する
CSS でスタイルをオーバーライドする
検索ウィジェットには、候補と結果の要素をスタイル設定する独自の CSS と、ページ分割のコントロールが用意されています。これらの要素は必要に応じてスタイルを変更できます。
読み込み中、検索ウィジェットはデフォルトのスタイルシートを動的に読み込みます。これは、アプリケーションのスタイルシートが読み込まれた後に発生し、ルールの優先度が上がります。独自のスタイルをデフォルト スタイルよりも優先させるには、祖先セレクタを使用してデフォルト ルールの特異性を高めます。
たとえば、ドキュメント内の静的 link
または style
タグに読み込まれた場合、次のルールは無効です。
.cloudsearch_suggestion_container {
font-size: 14px;
}
代わりに、ページで宣言されている祖先コンテナの ID またはクラスでルールを修飾します。
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
サポートクラスのリストとウィジェットによって生成される HTML の例については、サポートされる CSS クラス リファレンスをご覧ください。
要素をアダプタで修飾する
レンダリング前に要素を装飾するには、decorateSuggestionElement
や decorateSearchResultElement.
などの装飾メソッドのいずれかを実装するアダプタを作成して登録します。
たとえば、次のアダプタは、候補要素と結果要素にカスタムクラスを追加します。
ウィジェットを初期化するときにアダプタを登録するには、それぞれの Builder
クラスの setAdapter()
メソッドを使用します。
デコレータは、コンテナ要素といずれかの子要素の属性を変更できます。子要素は、装飾中に追加または削除されることがあります。ただし、要素を構造的に変更する場合は、要素を装飾するのではなく直接作成することを検討してください。
アダプタを使用してカスタム要素を作成する
候補、ファセット コンテナ、検索結果のカスタム要素を作成するには、それぞれ createSuggestionElement
、createFacetResultElement
、createSearchResultElement
を実装するアダプタを作成して登録します。
次のアダプタは、HTML の <template>
タグを使用してカスタムの候補要素と検索結果要素を作成することを示しています。
ウィジェットを初期化するときにアダプタを登録するには、それぞれの Builder
クラスの setAdapter()
メソッドを使用します。
createFacetResultElement
でカスタム ファセット要素を作成する場合、いくつかの制約があります。
- ユーザーがクリックしてバケットを切り替える要素に CSS クラス
cloudsearch_facet_bucket_clickable
を添付する必要があります。 - 各バケットを、CSS クラス
cloudsearch_facet_bucket_container
の包含要素でラップする必要があります。 - バケットをレスポンスに表示される順序と異なる順序でレンダリングすることはできません。
たとえば、次のスニペットは、チェックボックスの代わりにリンクを使用してファセットをレンダリングします。
検索動作をカスタマイズする
検索アプリケーションの設定は、検索インターフェースのデフォルト構成を表し、静的です。ユーザーにデータソースの切り替えを許可するような動的なフィルタやファセットを実装する場合、アダプタで検索リクエストをインターセプトすることにより、検索アプリケーションの設定をオーバーライドできます。
interceptSearchRequest
メソッドを使用してアダプタを実装し、実行前に Search API に対するリクエストを変更します。
たとえば、次のアダプタはリクエストをインターセプトして、クエリをユーザーが選択したソースに限定します。
ウィジェットを初期化するときにアダプタを登録するには、ResultsContainer
のビルド時に setAdapter()
メソッドを使用します。
次の HTML は、ソースでフィルタリングするために選択ボックスを表示する目的で使用されます。
次のコードは、変更をリッスンし、選択を設定し、必要に応じてクエリを再実行します。
アダプタに interceptSearchResponse
を実装して、検索レスポンスをインターセプトすることもできます。
API バージョンを固定する
デフォルトでは、ウィジェットは最新の安定バージョンの API を使用します。特定のバージョンに固定するには、ウィジェットを初期化する前に cloudsearch.config/apiVersion
構成パラメータを希望するバージョンに設定します。
API のバージョンは、省略するか無効な値を指定した場合、デフォルトの 1.0 になります。
ウィジェットのバージョンを固定する
検索インターフェースの予期しない変更を避けるには、cloudsearch.config/clientVersion
構成パラメータを次のように設定します。
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
ウィジェットのバージョンは、省略するか無効な値を指定した場合、デフォルトの 1.0 になります。
検索インターフェースを保護する
検索結果には非常に機密性の高い情報が含まれます。おすすめの方法に沿ってウェブ アプリケーションを(特にクリックジャッキング攻撃に対して)保護します。
詳細については、OWASP Guide Project をご覧ください。
デバッグを有効にする
interceptSearchRequest
を使用して、検索ウィジェットのデバッグを有効にします。次に例を示します。
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;