suggestrapでフォーム入力時のサジェスト機能を実装する

suggestrapでフォーム入力時のサジェスト機能を実装する:

suggestrapはユーザがフォームに値を入力した時に、その入力された値を元にサジェストを自動表示してくれるライブラリです。サジェストはまたの名をオートコンプリートと言いますが、ここでは「サジェスト」で統一します。

準備

• suggestrap
• JSONサーバ
• index.html
• index.js

使い方

ユーザがフォームに値を入力すると、suggestrapはその入力された値をリクエストパラメータにして、別途用意したJSONサーバにJSONファイルをリクエストし、返ってきたJSONファイルをパースしてサジェストを表示します。その為、自身で別途JSONサーバを用意する必要があります。JSONサーバなしで動かしたい場合はJSONサーバなしで使う方法を参照してください。

ここでは記事冒頭のgifアニメのような、検索フォームにユーザ名を入力すると、その入力された値にマッチするユーザ名を検索候補として表示するケースを想定して使い方を説明します。

suggestrap

GitHub: mrhorin/suggestrap

npmでインストールする場合はnpm install suggestrap

JSONサーバ

JSONサーバの構築方法は何でも構いませんが、ここではRuby on Railsを例にJSONサーバを構築していきます。Railsのインストール方法やモデルとコントローラの作成方法やルーティング方法についてはここでは割愛します。

users_controller.rb

class UsersController < ApplicationController 
 
  def suggestion 
    @users = User.where('name LIKE ?', "%#{params[:query]}%").limit(5) 
    render json: @users 
  end 
 
end 

Userモデルでnameキーがリクエストパラメータparams[:query]の値で部分一致するレコードを最大５件取得しています。ここで注意すべき点は、JSONサーバのレスポンスが遅いと、そのぶんsuggestrapがサジェストを表示するのも遅くなってしまうことです。登録されているレコードの件数が多い時はindexを追加するなどしてレスポンスが遅くならないようにして下さい。

users.json

[ 
  {"id":1, "age":32, "name":"Jack"}, 
  {"id":2, "age":41, "name":"Jackie"}, 
  {"id":3, "age":41, "name":"Jake"}, 
  {"id":4, "age":20, "name":"James"}, 
  {"id":5, "age":28, "name":"Jane"} 
] 

返ってくるJSONのフォーマットは上記の例のような、オブジェクトを持つ深さ1の配列でなければいけません。

index.html

index.html

<input id="target" type="text"> 
 
<script src="./suggestrap/lib/suggestrap.js"></script> 
<script src="./index.js"></script> 

サジェストを表示したいテキストフォームにidを指定して下さい。

index.js

index.js

var req = { 
    target: "target", 
    url: "https://example.com/json/users/%QUERY", 
    key: "name" 
  }; 
  var suggestrap = new Suggestrap(req); 

ユーザがindex.htmlの<input id="target" type="text">に値を入力すると、suggestrapはコンストラクタの第一引数のurlキーで指定したJSONリクエスト用URLのhttps://example.com/json/users/%QUERYの%QUERYの部分をユーザが入力した値に置き換えます。例えばユーザが入力した値がjaだった場合はhttps://example.com/json/users/jaというURLが生成されます。その後suggestrapはそのURLでJSONをリクエストし、返ってきたJSONオブジェクト内のキーの中で、suggestrapのコンストラクタの第一引数のkeyキーで指定したJSONオブジェクトの"name"キーの値をサジェストとして表示します。

index.js

import Suggestrap from 'suggestrap' 
 
const req = { 
  target: "target", 
  url: "https://example.com/json/users/%USERNAME", 
  key: "name" 
} 
const option = { 
  minlength: 3, 
  wildcard: "%USERNAME", 
  delay: 200 
} 
 
let suggestion = new Suggestrap(req, option) 

こちらはES6の例です。こちらの例では第二引数でいくつかのオプション項目も指定しています。

コンストラクタ

第一引数は必須です。下記のキーを持つハッシュを渡して下さい。

• 
  target: ターゲットとなるサジェストを表示したいフォームのIDを指定します。
• 
  url: JSONサーバにサジェスト用のJSONをリクエストするURLを指定します。このURLは前述の例のようなワイルドカードを含んでいる必要があります。suggestrapは、このURLのワイルドカード部分を、ターゲットのフォームに入力された値に置き換えた後に、JSONサーバへJSONをリクエストします。また、このワイルドカードの文字列のデフォルト値は%QUERYですが、これはオプション項目を指定する第二引数のwildcardキーで任意の文字列に変更することができます。
• 
  key: サジェストで表示したいJSONオブジェクトのキーを指定します。
• 
  values: このキーの指定は任意です。もしJSONサーバなしで、フロントサイドのみでサジェストを表示したい場合は、このキーにサジェスト候補の文字列の一覧を持つ配列を指定します。その場合、urlキーは指定する必要はありません。もしurlキーとvaluesキーを同時に指定した場合はvaluesキーの値が優先されます。加えて、このvaluesキーにはJSONリクエスト用のURLを指定することもできます。その場合の挙動は、urlキーでURLを指定した場合と全く同じです。このキーの具体的な使い方については、後述のJSONサーバなしで使う方法を参照して下さい。

第二引数は任意のオプションです。指定したいキーを持つハッシュを渡して下さい。デフォルト値のままで良いキーは指定する必要はありません。

• 
  minlength: ターゲットのフォームに入力された値の文字数が指定した値に達すると、suggestrapはサジェストを表示します。初期値は2です。
• 
  wildcard: JSONリクエストURLのワイルドカードを指定します。 初期値は'%QUERY'です。
• 
  delay: サジェストを表示するまでの遅延時間をミリ秒単位で指定します。ターゲットのフォームに入力された値の文字数がminlengthに達した時、指定したミリ秒後にサジェストが表示されます。 初期値は400です。
• 
  count: 表示するサジェストの件数を指定します。初期値は5です。
• 
  id: suggestrapが生成するサジェストのエレメントIDを指定します。もし指定したエレメントIDと同名のIDが既に存在していた場合はsuggestrap_2のように、アンダースコアと数字の組み合わせの接尾辞を末尾に付与します。初期値は'suggestrap'です。

JSONサーバなしで使う方法

JSONサーバなしでサジェストを表示したい場合は、suggestrapのコンストラクタの第一引数のvaluesキーに、下記の例のようなサジェスト候補のハッシュの一覧を持つ配列を指定します。ユーザがテキストフォームに値を入力すると、suggestrapはその値と部分一致するオブジェクトを抽出してサジェストを表示します。また、valuesキーを指定する場合はurlキーは指定する必要はありません。もしurlキーとvaluesキーを同時に指定した場合はvaluesキーの値が優先されます。

この例はES6で記述されています。

index.js

import Suggestrap from 'suggestrap' 
 
const req = { 
  target: "target", 
  key: "name", 
  values: [ 
    { name: "Andy" }, 
    { name: "Billy" }, 
    { name: "Catherine" }, 
    { name: "David" }, 
    { name: "Emily"}, 
    { name: "Henry"}, 
    { name: "Jack"}, 
    { name: "Kevin"}, 
    { name: "Mike"} 
  ] 
} 
 
let suggestion = new Suggestrap(req) 

カスタマイズ

CSSをカスタマイズしたい時は自身でCSSをオーバーライドして下さい。suggestrapによって生成されるサジェストのエレメントのIDは、コンストラクタの第二引数のidキーで指定します。デフォルトの場合のidはsuggestrapです。

style.css

/* Example */ 
ul#suggestrap { 
  background: #fff; 
  border-radius: 3px; 
  box-shadow: -2px 2px 7px rgba(0,0,0,0.3); 
} 
ul#suggestrap li { 
  color: #333; 
  padding: 1px 6px; 
} 
ul#suggestrap li.suggestrap-active, 
ul#suggestrap li:hover { 
  background: #4b89bf; 
  color: #fff; 
}