Search Autocomplete
Drupalサイト上の任意のフォーム入力フィールドにオートコンプリート機能を提供します。Viewsやカスタムコールバックからの候補ソースに対応しています。
search_autocomplete
インストール
composer require 'drupal/search_autocomplete:^4.0'
composer require 'drupal/search_autocomplete:^3.0'
composer require 'drupal/search_autocomplete:^2.0'
概要
Search Autocompleteは、Drupalサイト上のほぼすべての入力フィールドにオートコンプリート機能を追加する強力なモジュールです。ユーザーの入力中に、フォーム送信前に候補のドロップダウンリストを表示するようフィールドが展開されます。
候補は、サイトで利用可能な任意のエンティティタイプを使用したViewsから、またはカスタムPHPコールバックや外部APIから取得できます。このモジュールは、Drupalコアの検索モジュールおよびSearch Blockとの深い統合をすぐに使える状態で提供します。
主な機能には、設定可能な最小文字数トリガー、最大候補数の制限、自動送信と自動リダイレクト機能、カスタマイズ可能な「結果なし」および「すべての結果を表示」メッセージ、候補ドロップダウンのスタイリング用の複数のCSSテーマがあります。DOMPurify統合によりXSS防止のセキュリティが確保されています。
基本的なシナリオは、Viewsの露出フィルターのオートコンプリートなど、UIを通じて完全に設定できます。上級ユーザーは、Twitter、Google Places、または任意のAPIなどの外部データソースを統合するカスタムコードで複雑なシナリオを作成できます。
Features
- CSSセレクターを使用して任意の入力フィールドにオートコンプリート候補を追加
- カスタム表示、スタイル、行プラグインを使用してViewsを候補データソースとして使用
- カスタムコールバックURL（内部Drupalパスまたは外部API）のサポート
- 候補選択時にフォームを自動送信
- 候補選択時に候補リンクへ自動リダイレクト
- オートコンプリートがトリガーされる前の最小文字数を設定可能
- 表示される候補の最大数を設定可能
- ラベル、値、リダイレクトリンクを設定可能なカスタム「結果なし」メッセージ
- ラベル、値、リダイレクトリンクを設定可能なカスタム「すべての結果を表示」メッセージ
- カスタムテーマをサポートする複数のCSSテーマ（basic、minimal）
- 入力フィールドにマウスを合わせるとCSSセレクターを検出する管理ヘルパーツール
- DOMPurifyライブラリ統合によるXSS保護
- Drupalコアの検索ブロックと検索フォームの事前設定済みオートコンプリート
- カンマ区切りの複数値フィールドのサポート
- Viewsでのカテゴリ別候補グループ化
- メッセージでのTokenサポート：[search-phrase]と[search-count]
- 設定の編集や削除から保護するアクセス制御フラグ
Use Cases
検索ブロックのオートコンプリート
コアDrupal検索ブロックでオートコンプリートを有効にして、ユーザーの入力に応じて一致するコンテンツタイトルを候補として表示します。デフォルト設定は公開済みノードを検索し、最大10件の候補を表示します。候補を選択するとその値で検索フォームが送信されます。
Viewsの露出フィルターのオートコンプリート
任意のViewsの露出フィルター入力フィールドにオートコンプリートを追加します。新しい設定を作成し、管理ヘルパーツールを使用してフィルターのCSSセレクターを特定し、候補ソースとしてView表示を指定します。ユーザーはオートコンプリートの支援を受けてコンテンツをフィルタリングできます。
オートコンプリート付きユーザー検索
ユーザー検索フォームでオートコンプリートを有効にして、一致するユーザー名を候補として表示します。このモジュールには、ユーザーViewコールバックをクエリする検索フォームユーザータブ用のデフォルト設定が含まれています。
外部API統合
Google Placesやカスタムウェブサービスなどの外部APIからオートコンプリート候補を作成します。外部APIのURLでソースフィールドを設定します。APIはラベル、値、およびオプションのリンクフィールドを含む期待される形式でJSONを返す必要があります。
複雑な候補用のカスタムコールバック
複雑なクエリや集約データソースからJSON候補を返すカスタムDrupalコントローラーを構築します。コントローラーのパスをソースURLとして指定し、期待される形式でデータを返します。
カテゴリ別のグループ化された候補
Viewsのグループ化を使用して、コンテンツタイプ、タクソノミーターム、またはその他の基準で候補を整理します。スタイルプラグインはドロップダウン内のグループ間の視覚的な区切りでグループ化をサポートします。
1ページに複数のオートコンプリートフィールド
異なるCSSセレクターで複数のオートコンプリート設定を構成して、複数のフィールドで同時にオートコンプリートを有効にします。それぞれが独自のソース、テーマ、動作設定を持つことができます。
Tips
- 管理ヘルパーツールを使用して、入力フィールドにマウスを合わせることでCSSセレクターを簡単に特定できます
- css/themes/にある既存のファイルをコピーして修正することでカスタムCSSテーマを作成できます
- 「結果なし」および「すべての結果を表示」メッセージで[search-phrase] Tokenを使用して、ユーザーが検索した内容を表示できます
- サーバー負荷を軽減しながら有用な候補を提供するために、最小文字数を2〜3に設定してください
- Viewのグループ化を使用して候補を視覚的に分類できます（例：コンテンツタイプ別）
- 露出フィルターのオートコンプリートでは、Viewの露出フィルター識別子が自動的にコールバックに渡されます
- Viewプレビューでオートコンプリートの動作をテストできます - JSON出力は読みやすくフォーマットされています
Technical Details
Admin Pages 4
/admin/config/search/search_autocomplete
すべてのオートコンプリート設定のリストを表示するメイン管理ページ。個別の設定の有効化/無効化と管理ヘルパーツールの切り替えが可能です。各エントリの設定名、有効状態、CSSセレクターを表示します。
/admin/config/search/search_autocomplete/add
新しいオートコンプリート設定を作成するためのフォーム。人間が読める名前、マシン名、対象入力フィールドのCSSセレクターが必要です。
/admin/config/search/search_autocomplete/manage/{autocompletion_configuration}
表示動作、データソース、テーマを含むオートコンプリート設定のすべての側面を構成するための包括的なフォーム。
/admin/config/search/search_autocomplete/manage/{autocompletion_configuration}/delete
オートコンプリート設定を削除するための確認フォーム。一部のデフォルト設定は削除が無効になっている場合があります。
権限 2
Hooks 5
hook_element_info_alter
カスタムオートコンプリート処理を追加するためにフォーム要素を変更します。processAutocompleteを持つ要素を識別し、process_search_autocompleteハンドラーを追加します。
hook_library_info_build
css/themesディレクトリにあるCSSテーマファイルのライブラリ定義を動的に作成します。
hook_library_info_alter
core/drupal.autocompleteライブラリを変更して、カスタムJavaScriptを注入し、利用可能な場合はDOMPurify依存関係を追加します。
hook_page_attachments
オートコンプリート設定をページに添付します。CSSセレクターを持つすべての有効な設定の設定を読み込み、有効な場合は管理ヘルパーライブラリを添付します。
hook_form_alter
Drupalコアの検索フォーム（search_block_formとsearch_form）にデフォルトのオートコンプリート設定を適用します。
Troubleshooting 5
ブラウザの開発者ツールを使用してCSSセレクターが正しいことを確認してください。ユーザーが「use search autocomplete」権限を持っていることを確認してください。設定変更後にすべてのキャッシュをクリアしてください。設定が有効になっていることを確認してください。
DOMPurifyをhttps://github.com/cure53/DOMPurifyからダウンロードし、libraries/dompurify/に配置して、パスlibraries/dompurify/dist/purify.min.jsが存在するようにしてください。または、Composerで自動的にダウンロードするよう設定することもできます。
ブラウザコンソールでJavaScriptエラーを確認してください。ソースURLまたはView表示が存在しアクセス可能であることを確認してください。Viewにオートコンプリートコールバック表示が適切に設定されていることを確認してください。
メイン設定ページで管理ヘルパーチェックボックスを有効にしてください。「administer search autocomplete」権限を持っていることを確認してください。このツールはテキストおよび検索入力フィールドにのみ表示されます。
一部のデフォルト設定は保護のためにeditableまたはdeletableフラグがFALSEに設定されています。これらの設定は設定に保存されており、UIを通じて変更することはできません。
Security Notes 5
- このモジュールはXSS保護のためにDOMPurifyライブラリが必要です - なしで使用しないでください
- 候補出力はドロップダウンでレンダリングされる前にDOMPurifyでサニタイズされます
- 「use search autocomplete」権限がオートコンプリート機能を表示するユーザーを制御します
- 外部コールバックURLはデータ漏洩を防ぐために慎重に検証する必要があります
- 設定エンティティには、重要な設定の誤った変更を防ぐためのeditable/deletableフラグがあります