Tuesday 15th September, 2020
By Sandy Galloway

Introducing SearchBuilder

SearchBuilder is a new extension for DataTables that allows the end user to apply advanced filtering to your tables. In a step up in complexity from SearchPanes, SearchBuilder allows for filtering on columns using a wide variety of conditions, rather than just exact matches. Conditions can be grouped together to create complex filters that are seamlessly applied to the table. SearchBuilder is therefore a very effective way of narrowing down results using complex conditions across multiple columns at a time.

You can see an example below - click the Add Condition button to get started building your own filter:

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

Download

The SearchBuilder extension is available on the DataTables CDN using our download builder and direct access from our CDN (links below). If you prefer to use a package manager You can also install it from NPM, NuGET and Composer.

CSS
JS

Features

The arrival of SearchBuilder brings a completely new way of applying complex filtering to DataTables. At its core, it is an interface that will allow users to quickly filter tables based on criteria that they set. On initialisation SearchBuilder analyses the DataTable and extracts the columns along with their data type. Once a column has been selected, the condition select is populated with all of the available conditions for that column, these change depending on the data type. The default is for SearchBuilder to allow for filtering on all of the columns, but this is of course configurable using the searchBuilder.columns option. Once a column has been selected, the relevant conditions are made available within the condition select element. Another selection here displays the relevant input method for collecting the value to filter against for this condition, be that a select or an input. For the likes of the empty condition, no extra value is required, so no input method is made available.

Each "Criteria" is able to be placed in a group. Groupings allow for the logic type to be set. For example you may want the filtered rows to satisfy conditions X and Y, or just condition Z. Groups and sub groups make this possible. There is no limit on the number of conditions, groups, sub groups or depth in SearchBuilder. This means that you really can create search criteria that are as complex as you desire.

SearchBuilder has been constructed with customisation in mind. We're very aware that many of you will want to add your own conditions, or modify the existing ones to be tailored to your needs. Full documentation for how to add your own conditions is available in the docs.

Usage

Beyond the core set of features and the custom conditions configuration options, there are a handful of config options for SearchBuilder. These include setting depth limits, default logic for groups and pre-defined criteria. There is also a quick option to greyscale the colours in SearchBuilder if you are looking for a more subtle styling approach. As always though, it is possible to add your own styling to SearchBuilder.

Layout

SearchBuilder is inserted into the page using the searchBuilder feature with the layout option as shown below:

$('#myTable').DataTable({
    layout: {
        top1: 'searchBuilder'
    }
    dom: 'Qlfrtip'
});

If you are using a legacy version of DataTables 1.x, the insert point is done with the dom option of DataTables. The Q option tells DataTables where to show SearchBuilder - e.g.:

$('#myTable').DataTable({
    dom: 'Qlfrtip'
});

For styling libraries such as Bootstrap and Semnatic UI, you might find it easier to use the searchBuilder.container() method to get the SearchBuilder DOM element, and insert it directly into the document - e.g.:

var table = $('#example').DataTable({
    searchBuilder: true
});
table.searchBuilder.container().prependTo(table.table().container());

SearchBuilder is set to responsively adjust its layout based on the width of the screen, removing the need for extra work by developers.

Future Work

As was the case with SearchPanes' initial release, server-side processing is not available in this 1.0.0 release either. We are going to be looking at adding this ability in future, also noting that SearchBuilder's speed is already a lot faster than SearchPanes' when handling large datasets on the client-side.

While this is only a 1.0.0 release, there has been a large amount of work and testing over the last few months to ensure that SearchBuilder is a strong extension which is ready for use in production environments.

I hope that SearchBuilder can bring some improvement to your projects and as always we would encourage you to provide any feedback that you may have on this initial release of SearchBuilder in the forums, as well as any other features that you think would benefit the extension in the future!