Redesigning the Country Selector

FAQ

Do I have to use your country list? Which list is it?

It's based on the ISO 3166, and no, you don't have to use it. In fact, the idea is that you add this plugin to your existing country list – not replace your country list itself. We simply added the ISO 3166 country list as an example.

Is it limited to countries?

No. The code simply replace ordinary drop-downs (or 'select' tags), and is therefore not limited to country selectors. Any drop-down on your site can be used. For example, we've used it as an auto-complete to look up DSLR camera models at LensHawk.com.

Does it work in IE6, IE7, ..?

Yes and no. In IE6 and IE7 nothing happens and the normal drop-down is displayed. In other words, it doesn't break your site in IE6 and IE7, but the drop-down won't be turned into an advanced auto-complete field either. IE8+ works along with Firefox, Chrome, Opera and Safari.

Does it require back-end integration?

No. Everything happens front-end and the auto-complete options are simply taken from the original drop-down so there's no requests to your server (plus searching happens instantly).

Is it yet another auto-complete plugin?

No. In fact, the auto-complete plugin is completely separate from this plugin. We include the jQuery UI Autocomplete by default but you can use any auto-complete plugin (see next question).

Can I use my own auto-complete plugin?

Yes. We've deliberately not built the auto-complete part. Instead, there's adapters that allow you to use the plugin with any auto-complete plugin. Currently, there's only a jQuery UI Autocomplete adapter but more may be added if the interest is there.

MIT License

The plugin is released under the MIT License:

Copyright (C) 2011 by Jamie Holst, Baymard Institute (baymard.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Note: the included jQuery plugins are (obviously) under their noted licenses.

Documentation

Dependencies

1. jQuery – This is a jQuery plugin so you'll (obviously) need jQuery included.
2. Auto-complete – You'll need some kind of an auto-complete plugin. There's an adapter written for the jQuery UI Autocomplete plugin but you can also use your own.

Installation

Be sure to include the dependencies and then the selectToAutocomplete plugin.

Now you simply need to call the '.selectToAutocomplete' function on a jQuery selection once the DOM is ready. For example, to turn all select elements with a class of turn-to-ac, you'd simply need to call:

          
            jQuery(function(){

              jQuery('select.turn-to-ac').selectToAutocomplete();

            });
          
        

If you just want to use the default configuration and the jQuery UI Autocomplete plugin then this is it. Otherwise, check below too see how you can customize the auto-complete and write an adaptor for your own auto-complete plugin.

Customization

There's a whole host of options you can pass to the plugin (as first and only parameter), some of which give you access to the internals of the plugin. Here I'll cover a few of the most common customizations:

• relevancy-sorting – should be 'true' if the auto-complete should sort the results based on their relevancy to the search terms (this slows down live filtering, but makes the results much more relevant) | default: true
• relevancy-sorting-partial-match-value – the score added for each partial match | default: 1
• relevancy-sorting-partial-match-value – the score added if there's one or more strict matches | default: 5
• relevancy-sorting-booster-attr – if the defined attribute is present on an 'option' tag, it will be multiplied by the value of this attribute | default: 'data-relevancy-booster'
• sort – should be 'true' if the auto-complete should sort (as in: prioritize) the results on initialization (note: this sorting is overwritten by relevancy sorting) | default: false
• sort-attr – the attribute that should be sorted by if 'sort' is enabled | default: 'data-priority'
• sort-desc – if the sorting direction should be descending (otherwise it'll be ascending) | default: false
• alternative-spellings – should be 'true' if the auto-complete should accept alternative spellings | default: true
• alternative-spellings-attr – the attribute that contains the alternatives if 'alternative-spellings' is enabled | default: 'data-alternative-spellings'
• remove-valueless-options – if options without value (or simply a blank value) should be ignored in the auto-complete results | default: true
• copy-attributes-to-text-field – if the attributes of the original 'select' tag should be copied over to the new auto-complete enabled text field | default: true

For example, if you don't want the attributes of the 'select' tag to be copied over to the new auto-complete text field, then you'd do something like this:

          
            $('.turn-to-ac').selectToAutocomplete({

              'copy-attributes-to-text-field': false

            });
          
        

Auto-Complete Adapters

The selectToAutocomplete plugin allows you to use your own auto-complete plugin. By default we include the jQuery UI Autocomplete and there's a pre-written adapter for it, but if you want to (re)use your own auto-complete plugin then it's actually quite easy to write an adapter.

Just pass in an 'autocomplete-plugin' function as part of the options hash. This is your adapter function.

The function should accept one parameter which is a hash containing 4 keys:

1. $select_field – the original (and now hidden) select field in a jQuery selection.
2. $text_field – the new text field in a jQuery selection.
3. options – an array of the hashes representing each of the select tag's original options. The individual hash can have up to 6 keys:
   1. real-value – the option's value attribute.
   2. label – the option's actual text written between the opening and closing option tags.
   3. matches – the string you should search in your auto-complete plugin. This contains the label, and if alternative spellings is enabled it contains all those.
   4. relevancy-score – only included if relevancy sorting is enabled. It contains the current relevancy score of the option.
   5. relevancy-score-booster – only included if relevancy sorting is enabled. It contains the relevancy booster value of the option (used to promote certain options over others). Default is 1.
   6. weight – only included if sorting is enabled. It contains the option's value of the defined sort-attr. Please note: the options array is already sorted.
4. settings – a hash of all the options for the plugin (defaults merged with customizations).