PhoenixFormAwesomplete is a Phoenix form helper that utilizes Lea Verou's autocomplete / autosuggest / typeahead / inputsearch Awesomplete widget.
It comes with an AwesompleteUtil javascript library which adds the following features:
- Dynamic remote data loading; based on what is typed-in it performs an ajax lookup.
- Allow HTML markup in the shown items. Show value with description. Optionally search in the description text.
- Show when there is an exact match.
- Show when there isn't a match.
- When there is an exact match show related data (supplied in the remote data) in other parts of the page.
- Select the highlighted item when the tab key is used.
Examples
The EEx template below creates an input field, and it will show suggestions from the Github API. This REST API also returns avatar url's. When there is an exact match, the avatar url will be set in the IMG tag to show the avatar picture.
EEx
<%= copy_to_id(:user, :name1, "avatar_url", "#awe-avatar-img") %>
<%= awesomplete(
:user,
:name1,
[ # input_text options
class: "form-control",
autocomplete: "off"
],
%{
url: "https://api.github.com/search/users?q=",
urlEnd: " in:login type:user&per_page=30",
minChars: 3,
maxItems: 10,
limit: 30,
value: "login",
filter: "AwesompleteUtil.filterStartsWith",
item: "AwesompleteUtil.itemStartsWith"
}
) %>maxItems parameter indicates that maximum 10 suggestions must be shown in the dropdown.
The per_page parameter in the url tells the server to return maximum 30 suggestions per call.
The limit parameter informs the AwesompleteUtil component that normally 30 results can be expected. If there are less than 30 results, any additional characters in the search phrase won't need a new server call, because all the matching suggestions are already retrieved.
The client-side suggestions filter must be made consistent with the search functionality of the REST API. In this case, the server will only return usernames that start with the entered text, and the client-side filter should work in the same way.
The item parameter is configured to highlight only matching text at the beginning of the suggestions, to clearly indicate why these suggestions are shown.
The standard supplied 'starts-with' and 'contains' filters don't exactly match with how iTunes searches.
iTunes searches words, you can search for 'Michael Jackson' or 'Jackson Michael' and get the same results.
Thats why a filter called 'filterWords' is used that filters on the words entered. To highlight the
words in the list of suggestions a function called 'itemWords' is used.
A limit of -1 is specified to force it to requery if more characters are typed.
The service search for whole words, so when a part of the word is entered and doesn't result in any hits,
this doesn't mean that there wouldn't be more results if more characters are typed.
For example: search for 'jackso' results in 1 hit, but 'jackson' gives a lot more results.
The iTunes service doesn't support wildcards but others (like Elasticsearch) do. Assuming that the user
is completing the last word while typing, you could add a * wildcard at the end of the search url with the
urlEnd: '*' configuration to search the last word starting with the typed letters.
EEx
<%= awesomplete(
:user,
:artist1,
[ # input_text options
class: "form-control"
],
%{
url: "https://itunes.apple.com/search?entity=musicArtist&attribute=artistTerm&media=music&limit=15&country=gb&sort=artistTerm&term=",
limit: -1,
debounce: 300,
filter: "AwesompleteUtil.filterWords", # javascript functions must be double quoted
item: "AwesompleteUtil.itemWords",
value: "artistName"
}
) %>
The creation of the Awesomplete object below is almost the same as in the 'iTunes artist search' example.
EEx
<%= copy_to_id(:user, :track1, "collectionName", "#awe-track-album") %>
<%= copy_to_id(:user, :track1, "artistName", "#awe-track-artists") %>
<%= copy_to_id(:user, :track1, "artworkUrl100", "#awe-track-album-img") %>
<%= awesomplete(
:user,
:track1,
[ # input_text options
class: "form-control",
autocomplete: "off"
],
%{
url: "https://itunes.apple.com/search?entity=song&attribute=songTerm&media=music&limit=10&country=gb&sort=songTerm&term=",
limit: -1,
debounce: 300,
maxItems: 10,
minChars: 4,
value: "trackName",
descr: "collectionName",
filter: "AwesompleteUtil.filterWords",
item: "AwesompleteUtil.itemWords"
}
) %>
Add a combobox button after the awesomplete control:
HTML
<span class="input-group-btn">
<button class="dropdown-btn" id="awe_btn_user_combocountry" type="button" tabindex="-1">
<span class="caron">▼</span>
</button>
</span>
The combobox is useful when there are only a few items in the list,
or to give the user some examples of expected input.
Here we use maxItems:8, so when the combobox is opened, only the first 8 countries are shown.
The shortest country names are shown first.
EEx
<%= awesomplete(
:user,
:combocountry,
[ # input_text options
class: "form-control"
],
%{
url: "https://restcountries.com/v2/all",
loadall: true,
prepop: true,
minChars: 1,
maxItems: 8,
value: "name",
combobox: true
}
) %>EEx
<%= awesomplete(
:user,
:host1,
[
class: "form-control"
],
%{
url: "/js/host.json",
loadall: true,
filter: "Awesomplete.FILTER_STARTSWITH",
value: "value",
descr: "label",
data: "function (data, input) { var before = (input.slice(0, input.indexOf('@')) + '@').trim(); return {label: before + data.label, value: before + data.value}; }"
}
) %>
The remote service returns a HTTP status 404 if the searched value is not found. The default ajax
function only processes responses with HTTP OK status 200.
The ajax404 function below replaces the onload function to set the empty list if a 404 is received.
Javascript
This is actually not an autocomplete, but it does verify the input.
EEx
<%= awesomplete(
:user,
:country_iso,
[
class: "form-control",
autocomplete: "off"
],
%{
url: "https://restcountries.com/v2/alpha/",
value: "alpha3Code",
limit: 0,
minChars: 3,
maxItems: 0,
filter: "Awesomplete.FILTER_STARTSWITH",
ajax: ajax404
}
) %>
Input control:
EEx
<%= text_input(:user, :color, [value: "purple" class: "form-control"]) %>
<div><span id="awe-color-result"></span> ↲</div>
<%= copy_to_id(:user, :color, "label", "#awe-color-result") %>
<%= awesomplete_script(
:user,
:color,
%{
minChars: 1,
filter: "AwesompleteUtil.filterContains",
list: "[
{ label: \"<b style='color:black'>black</b>\", value: 'black' },
{ label: \"<b style='color:blue'>blue</b>\", value: 'blue' },
{ label: \"<b style='color:brown'>brown</b>\", value: 'brown' },
{ label: \"<b style='color:green'>green</b>\", value: 'green' },
{ label: \"<b style='color:orange'>orange</b>\", value: 'orange'},
{ label: \"<b style='color:pink'>pink</b>\", value: 'pink' },
{ label: \"<b style='color:purple'>purple</b>\", value: 'purple'},
{ label: \"<b style='color:red'>red</b>\", value: 'red' },
{ label: \"<b style='color:yellow'>yellow</b>\", value: 'yellow'}
]"
}
) %>If you use remote data loading and combine prepop:true with loadall:true the remote call will happen during page load. If prepop:false, the loadall will be done lazely, e.g. if the user makes changes and the input size >= minChars.
EEx
<%= copy_to_field(:user, :country, "capital", :user, :capital) %>
<%= copy_to_field(:user, :capital, "name", :user, :country) %>
<%= label(:user, :country, "Country", class: "control-label col-sm-2") %>
<div class="col-sm-4">
<%= awesomplete(:user, :country,
[class: "form-control"
],
[
assign: true,
minChars: 1,
maxItems: 7,
value: "name"
]) %>
</div>
<%= label(:user, :capital, "Capital", class: "control-label col-sm-2") %>
<div class="col-sm-4">
<%= awesomplete(:user, :capital,
[class: "form-control"
],
[
assign: true,
minChars: 1,
maxItems: 7,
value: "capital"
]) %>
</div>
The script below loads all countries and fills both Awesomplete objects with the result.
Javascript
Notice that you can enter multiple toppings, seperated by , or ;
EEx
<%= awesomplete(
:user,
:seafood,
[
class: "form-control",
"data-list": "Anchovies, Cajun Prawn, Crayfish, Lobster, Oysters, Prawns, Salmon, Shrimps, Smoked Salmon, Squid, Tuna, Whitebait"
],
%{
minChars: 1,
multiple: ",;"
}
) %>
Below the Awesomplete object and input control created
EEx
<%= awesomplete(
:user,
:multimail,
[
class: "form-control"
],
%{
url: "https://raw.githubusercontent.com/kentcdodds/starwars-names/main/src/starwars-names.json",
convertResponse: "names2contacts",
loadall : true,
minChars: 1,
maxItems: 7,
multiple: ";,",
value: "value",
label: "name",
descr: "email",
item: "AwesompleteUtil.itemMarkAll"
}
) %>
This example uses Star Wars names from a github repository.
The names2contacts function below constructs email addresses and a value that contains both name and email address.
Javascript
Your text could be placed here.
EEx
<%= awesomplete(
:user,
:seafood2,
[
class: "form-control",
"data-list": "Anchovies, Cajun Prawn, Crayfish, Lobster, Oysters, Prawns, Salmon, Shrimps, Smoked Salmon, Squid, Tuna, Whitebait"
],
%{
minChars: 1"
}
) %>Javascript