Tuesday 2nd September, 2014

Alphabet input search - Part II

Continuing a three part series of posts exploring the DataTables custom search options, API and feature plug-ins, this second post extends the alphabet search control introduced in part I of this series to give quick visual feedback to the end user for search terms. This visual information will indicate how many records are in the table for each search option. This is done through use of the DataTables API and displaying an information element using jQuery.

The alphabet search

Before exploring the code in this post, the following example shows what we will be building here.

NamePositionOfficeAgeStart dateSalary
Tiger NixonSystem ArchitectEdinburgh612011-04-25$320,800
Garrett WintersAccountantTokyo632011-07-25$170,750
Ashton CoxJunior Technical AuthorSan Francisco662009-01-12$86,000
Cedric KellySenior Javascript DeveloperEdinburgh222012-03-29$433,060
Airi SatouAccountantTokyo332008-11-28$162,700
Brielle WilliamsonIntegration SpecialistNew York612012-12-02$372,000
Herrod ChandlerSales AssistantSan Francisco592012-08-06$137,500
Rhona DavidsonIntegration SpecialistTokyo552010-10-14$327,900
Colleen HurstJavascript DeveloperSan Francisco392009-09-15$205,500
Sonya FrostSoftware EngineerEdinburgh232008-12-13$103,600
Jena GainesOffice ManagerLondon302008-12-19$90,560
Quinn FlynnSupport LeadEdinburgh222013-03-03$342,000
Charde MarshallRegional DirectorSan Francisco362008-10-16$470,600
Haley KennedySenior Marketing DesignerLondon432012-12-18$313,500
Tatyana FitzpatrickRegional DirectorLondon192010-03-17$385,750
Michael SilvaMarketing DesignerLondon662012-11-27$198,500
Paul ByrdChief Financial Officer (CFO)New York642010-06-09$725,000
Gloria LittleSystems AdministratorNew York592009-04-10$237,500
Bradley GreerSoftware EngineerLondon412012-10-13$132,000
Dai RiosPersonnel LeadEdinburgh352012-09-26$217,500
Jenette CaldwellDevelopment LeadNew York302011-09-03$345,000
Yuri BerryChief Marketing Officer (CMO)New York402009-06-25$675,000
Caesar VancePre-Sales SupportNew York212011-12-12$106,450
Doris WilderSales AssistantSydney232010-09-20$85,600
Angelica RamosChief Executive Officer (CEO)London472009-10-09$1,200,000
Gavin JoyceDeveloperEdinburgh422010-12-22$92,575
Jennifer ChangRegional DirectorSingapore282010-11-14$357,650
Brenden WagnerSoftware EngineerSan Francisco282011-06-07$206,850
Fiona GreenChief Operating Officer (COO)San Francisco482010-03-11$850,000
Shou ItouRegional MarketingTokyo202011-08-14$163,000
Michelle HouseIntegration SpecialistSydney372011-06-02$95,400
Suki BurksDeveloperLondon532009-10-22$114,500
Prescott BartlettTechnical AuthorLondon272011-05-07$145,000
Gavin CortezTeam LeaderSan Francisco222008-10-26$235,500
Martena MccrayPost-Sales supportEdinburgh462011-03-09$324,050
Unity ButlerMarketing DesignerSan Francisco472009-12-09$85,675
Howard HatfieldOffice ManagerSan Francisco512008-12-16$164,500
Hope FuentesSecretarySan Francisco412010-02-12$109,850
Vivian HarrellFinancial ControllerSan Francisco622009-02-14$452,500
Timothy MooneyOffice ManagerLondon372008-12-11$136,200
Jackson BradshawDirectorNew York652008-09-26$645,750
Olivia LiangSupport EngineerSingapore642011-02-03$234,500
Bruno NashSoftware EngineerLondon382011-05-03$163,500
Sakura YamamotoSupport EngineerTokyo372009-08-19$139,575
Thor WaltonDeveloperNew York612013-08-11$98,540
Finn CamachoSupport EngineerSan Francisco472009-07-07$87,500
Serge BaldwinData CoordinatorSingapore642012-04-09$138,575
Zenaida FrankSoftware EngineerNew York632010-01-04$125,250
Zorita SerranoSoftware EngineerSan Francisco562012-06-01$115,000
Jennifer AcostaJunior Javascript DeveloperEdinburgh432013-02-01$75,650
Cara StevensSales AssistantNew York462011-12-06$145,600
Hermione ButlerRegional DirectorLondon472011-03-21$356,250
Lael GreerSystems AdministratorLondon212009-02-27$103,500
Jonas AlexanderDeveloperSan Francisco302010-07-14$86,500
Shad DeckerRegional DirectorEdinburgh512008-11-13$183,000
Michael BruceJavascript DeveloperSingapore292011-06-27$183,000
Donna SniderCustomer SupportNew York272011-01-25$112,000
NamePositionOfficeAgeStart dateSalary

Mouse control

First consider how we wish to display the additional search information to the end user. As you will be able to see from the example above, a simple box with a number is shown below each letter in the alphabet as the user moves their mouse over the characters. The number indicates how many records are available for that search term (how that number is calculated is discussed below).

This is primarily simple Javascript and jQuery rather than being DataTables specific, so I won't delve into much detail here, but basically what we do is attach the element for the number box (info below) to the alphabet container (alphabet from the code developed in part I). As the mouse enters a search term element (a span tag) the information element is made visible with its content and position being updated to be suitable for the search term. As the mouse is removed, the information element is also removed.

var info = $('<div class="alphabetInfo"></div>')
    .appendTo( alphabet );

alphabet
    .on( 'mouseenter', 'span', function () {
        info
            .css( {
                opacity: 1,
                left: $(this).position().left,
                width: $(this).width()
            } )
            .html( $(this).data('match-count') )
    } )
    .on( 'mouseleave', 'span', function () {
        info.css('opacity', 0);
    } );

Data attributes

In the code above, the search count for each letter is read from the data attribute match-count - for example, you could consider the HTML to look like:

<div class="alphabet">
    <span data-match-count="57">None</span>
    <span data-match-count="3">A</span>
    <span data-match-count="4">B</span>
    <span data-match-count="5">C</span>
    ...
</div>

Our task now is simply to add those data attributes to the alphabet elements as they are created.

To get the data that is available in the first column we can use the DataTables column().data() method. Passing in an index of 0 to the column() method will retrieve the data for the first column, which can than be iterated over to count the number of times each character appears as the first letter in the data set.

For this we can write a simple function to bin the data, producing an object which has a count for each letter (the absence of a letter in the object represents a zero count):


function bin ( data ) { var letter, bins = {}; for ( var i=0, ien=data.length ; i<ien ; i++ ) { letter = data[i].charAt(0).toUpperCase(); if ( bins[letter] ) { bins[letter]++; } else { bins[letter] = 1; } } return bins; }

The resulting object might look like:

{
    "A": 3,
    "B": 4,
    "C": 5,
    ...
}

Finally we call that function with the data from column().data() and then use the binned data when creating the alphabet (refer to part I):

var columnData = table.column(0).data();
var bins = bin( columnData );

$('<span class="clear active"/>')
    .data( 'letter', '' )
    .data( 'match-count', columnData.length )
    .html( 'None' )
    .appendTo( alphabet );

for ( var i=0 ; i<26 ; i++ ) {
    var letter = String.fromCharCode( 65 + i );

    $('<span/>')
        .data( 'letter', letter )
        .data( 'match-count', bins[letter] || 0 )
        .addClass( ! bins[letter] ? 'empty' : '' )
        .html( letter )
        .appendTo( alphabet );
}

Part II completed code

The complete code that is used for the example at the top of this page, including the code that was developed in part I of this series is shown below:

Javascript

var _alphabetSearch = '';

$.fn.dataTable.ext.search.push( function ( settings, searchData ) {
    if ( ! _alphabetSearch ) {
        return true;
    }

    if ( searchData[0].charAt(0) === _alphabetSearch ) {
        return true;
    }

    return false;
} );


function bin ( data ) {
    var letter, bins = {};

    for ( var i=0, ien=data.length ; i<ien ; i++ ) {
        letter = data[i].charAt(0).toUpperCase();

        if ( bins[letter] ) {
            bins[letter]++;
        }
        else {
            bins[letter] = 1;
        }
    }

    return bins;
}


$(document).ready(function() {
    var table = $('#example').DataTable();

    var alphabet = $('<div class="alphabet"/>').append( 'Search: ' );
    var columnData = table.column(0).data();
    var bins = bin( columnData );

    $('<span class="clear active"/>')
        .data( 'letter', '' )
        .data( 'match-count', columnData.length )
        .html( 'None' )
        .appendTo( alphabet );

    for ( var i=0 ; i<26 ; i++ ) {
        var letter = String.fromCharCode( 65 + i );

        $('<span/>')
            .data( 'letter', letter )
            .data( 'match-count', bins[letter] || 0 )
            .addClass( ! bins[letter] ? 'empty' : '' )
            .html( letter )
            .appendTo( alphabet );
    }

    alphabet.insertBefore( table.table().container() );

    alphabet.on( 'click', 'span', function () {
        alphabet.find( '.active' ).removeClass( 'active' );
        $(this).addClass( 'active' );

        _alphabetSearch = $(this).data('letter');
        table.draw();
    } );

    var info = $('<div class="alphabetInfo"></div>')
        .appendTo( alphabet );

    alphabet
        .on( 'mouseenter', 'span', function () {
            info
                .css( {
                    opacity: 1,
                    left: $(this).position().left,
                    width: $(this).width()
                } )
                .html( $(this).data('match-count') )
        } )
        .on( 'mouseleave', 'span', function () {
            info.css('opacity', 0);
        } );
} );

CSS

div.alphabet {
    position: relative;
    display: table;
    width: 100%;
    margin-bottom: 1em;
}

div.alphabet span {
    display: table-cell;
    color: #3174c7;
    cursor: pointer;
    text-align: center;
    width: 3.5%
}

div.alphabet span:hover {
    text-decoration: underline;
}

div.alphabet span.active {
    color: black;
}

div.alphabet span.empty {
    color: red;
}

div.alphabetInfo {
    display: block;
    position: absolute;
    background-color: #111;
    border-radius: 3px;
    color: white;
    top: 2em;
    height: 1.8em;
    padding-top: 0.4em;
    text-align: center;
    z-index: 1;
}

Next

In the concluding part of this series, next week we will take the alphabet control that has been developed here and create a reusable DataTables feature plug-in allowing this input control to be used by any DataTable with a single line of code.