Implement grouping. Resolve devbridge#83

Author: Tomas Kirda

content/styles.css

@@ -5,6 +5,8 @@
 .autocomplete-suggestion { padding: 2px 5px; white-space: nowrap; overflow: hidden; }
 .autocomplete-no-suggestion { padding: 2px 5px;}
 .autocomplete-selected { background: #F0F0F0; }
-.autocomplete-suggestions strong { font-weight: normal; color: #3399FF; }
+.autocomplete-suggestions strong { font-weight: bold; color: #000; }
+.autocomplete-group { padding: 2px 5px; }
+.autocomplete-group strong { font-weight: bold; font-size: 16px; color: #000; display: block; border-bottom: 1px solid #000; }
 
 input { font-size: 28px; padding: 10px; border: 1px solid #CCC; display: block; margin: 20px 0; }

index.htm

@@ -16,8 +16,8 @@ <h2>Ajax Lookup</h2>
         </div>
         <div id="selction-ajax"></div>
 
-        <h2>Local Lookup</h2>
-        <p>Type country name in english:</p>
+        <h2>Local Lookup and Grouping</h2>
+        <p>Type NHL or NBA team name:</p>
         <div>
             <input type="text" name="country" id="autocomplete"/>
         </div>

readme.md

@@ -51,6 +51,7 @@ The standard jquery.autocomplete.js file is around 2.7KB when minified via Closu
            Set this option to force auto positioning in other cases.
         * `orientation`: Default `bottom`. Vertical orientation of the displayed suggestions, available values are `auto`, `top`, `bottom`.
           If set to `auto`, the suggestions will be orientated it the way that place them closer to middle of the view port.
+        * `groupBy`: property name of the suggestion `data` object, by which results should be grouped.
 
 Autocomplete instance has following methods:
 
@@ -108,6 +109,7 @@ Local lookup (no ajax):
 Generated HTML markup for suggestions is displayed bellow. You may style it any way you'd like.
 
     <div class="autocomplete-suggestions">
+        <div class="autocomplete-group"><strong>NHL</strong></div>
         <div class="autocomplete-suggestion autocomplete-selected">...</div>
         <div class="autocomplete-suggestion">...</div>
         <div class="autocomplete-suggestion">...</div>
@@ -119,6 +121,9 @@ Style sample:
     .autocomplete-suggestion { padding: 2px 5px; white-space: nowrap; overflow: hidden; }
     .autocomplete-selected { background: #F0F0F0; }
     .autocomplete-suggestions strong { font-weight: normal; color: #3399FF; }
+    .autocomplete-group { padding: 2px 5px; }
+    .autocomplete-group strong { display: block; border-bottom: 1px solid #000; }
+
 
 ##Response Format
 
@@ -159,6 +164,17 @@ you can supply the "paramName" and "transformResult" options:
         }
     })
 
+## Grouping Results
+
+Specify `groupBy` option of you data property if you wish results to be displayed in groups. For example, set `groupBy: 'category'` if your suggestion data format is:
+
+    [
+        { value: 'Chicago Blackhawks', data: { category: 'NHL' } },
+        { value: 'Chicago Bulls', data: { category: 'NBA' } }
+    ]
+
+Results will be formatted into two groups **NHL** and **NBA**.
+
 ##Known Issues
 
 If you use it with jQuery UI library it also has plugin named `autocomplete`. In this case you can use plugin alias `devbridgeAutocomplete`:

scripts/demo.js

@@ -46,15 +46,22 @@ $(function () {
         }
     });
 
+    var nhlTeams = ['Anaheim Ducks', 'Atlanta Thrashers', 'Boston Bruins', 'Buffalo Sabres', 'Calgary Flames', 'Carolina Hurricanes', 'Chicago Blackhawks', 'Colorado Avalanche', 'Columbus Blue Jackets', 'Dallas Stars', 'Detroit Red Wings', 'Edmonton OIlers', 'Florida Panthers', 'Los Angeles Kings', 'Minnesota Wild', 'Montreal Canadiens', 'Nashville Predators', 'New Jersey Devils', 'New Rork Islanders', 'New York Rangers', 'Ottawa Senators', 'Philadelphia Flyers', 'Phoenix Coyotes', 'Pittsburgh Penguins', 'Saint Louis Blues', 'San Jose Sharks', 'Tampa Bay Lightning', 'Toronto Maple Leafs', 'Vancouver Canucks', 'Washington Capitals'];
+    var nbaTeams = ['Atlanta Hawks', 'Boston Celtics', 'Charlotte Bobcats', 'Chicago Bulls', 'Cleveland Cavaliers', 'Dallas Mavericks', 'Denver Nuggets', 'Detroit Pistons', 'Golden State Warriors', 'Houston Rockets', 'Indiana Pacers', 'LA Clippers', 'LA Lakers', 'Memphis Grizzlies', 'Miami Heat', 'Milwaukee Bucks', 'Minnesota Timberwolves', 'New Jersey Nets', 'New Orleans Hornets', 'New York Knicks', 'Oklahoma City Thunder', 'Orlando Magic', 'Philadelphia Sixers', 'Phoenix Suns', 'Portland Trail Blazers', 'Sacramento Kings', 'San Antonio Spurs', 'Toronto Raptors', 'Utah Jazz', 'Washington Wizards'];
+    var nhl = $.map(nhlTeams, function (team) { return { value: team, data: { category: 'NHL' }}; });
+    var nba = $.map(nbaTeams, function (team) { return { value: team, data: { category: 'NBA' } }; });
+    var teams = nhl.concat(nba);
+
     // Initialize autocomplete with local lookup:
     $('#autocomplete').devbridgeAutocomplete({
-        lookup: countriesArray,
-        minChars: 0,
+        lookup: teams,
+        minChars: 1,
         onSelect: function (suggestion) {
-            $('#selection').html('You selected: ' + suggestion.value + ', ' + suggestion.data);
+            $('#selection').html('You selected: ' + suggestion.value + ', ' + suggestion.data.category);
         },
         showNoSuggestionNotice: true,
         noSuggestionNotice: 'Sorry, no matching results',
+        groupBy: 'category'
     });
 
     // Initialize autocomplete with custom appendTo:

src/jquery.autocomplete.js

@@ -613,6 +613,7 @@
 
             var that = this,
                 options = that.options,
+                groupBy = options.groupBy,
                 formatResult = options.formatResult,
                 value = that.getQuery(that.currentValue),
                 className = that.classes.suggestion,
@@ -621,6 +622,18 @@
                 noSuggestionsContainer = $(that.noSuggestionsContainer),
                 beforeRender = options.beforeRender,
                 html = '',
+                category,
+                formatGroup = function (suggestion, index) {
+                        var currentCategory = suggestion.data[groupBy];
+
+                        if (category === currentCategory){
+                            return '';
+                        }
+
+                        category = currentCategory;
+
+                        return '<div class="autocomplete-group"><strong>' + category + '</strong></div>';
+                    },
                 index;
 
             if (options.triggerSelectOnValidInput) {
@@ -633,6 +646,10 @@
 
             // Build suggestions inner HTML:
             $.each(that.suggestions, function (i, suggestion) {
+                if (groupBy){
+                    html += formatGroup(suggestion, value, i);
+                }
+
                 html += '<div class="' + className + '" data-index="' + i + '">' + formatResult(suggestion, value) + '</div>';
             });