SearchBuilder Plug-ins
SearchBuilder is already very useful with the default methods of filtering that it supplies, but what if you want to add your own or alter an already existing condition? That is done by creating a plug-in.
Required parameters
When you create a plug-in for SearchBuilder you add an object to the searchBuilder.conditions object, based on the data type (columns.type) for when the plug-in should be applied. The following properties must all be defined in your custom plug-in objects:
searchBuilder.conditions[type].conditionName- Define the name of the condition that is displayed in the condition select.searchBuilder.conditions[type].init- This function is used to initialise any jQuery elements that are required for your plug-in, for example select2 elements.searchBuilder.conditions[type].inputValue- This is used to extract the values that are to be used in the comparison from the jQuery elements that were initialised ininitsearchBuilder.conditions[type].isInputValid- This is used to decide whether the criteria is to be included in the search query. For example as default, before a value is selected the criteria should not be included.searchBuilder.conditions[type].search- This function is used to decide whether the row from the table should be included once the filter is applied.
Define during initialisation
As an example, let's assume that you need to create a condition for the num type that checks if the num is divisible by a value that is input by the user. We're going to call this condition Multiple of. First of all we have to add to the num condition in the SearchBuilder config as follows.
$('#myTable').DataTable( {
searchBuilder:{
conditions:{
num:{
multipleOf: {
...
}
}
}
}
})
We want our condition to appear in the dropdown as Multiple Of so we will set the searchBuilder.conditions[type].conditionName property to 'Multiple Of' as follows (note only the plug-in object is shown here for brevity):
multipleOf: {
conditionName: 'Multiple Of',
...
}
Next, we want the user to be able to input any value that they want so we are going to the searchBuilder.conditions[type].init function to initialise an input element. An in depth description of how to do this is provided here
We do this in the searchBuilder.conditions[type].init function as follows.
multipleOf: {
conditionName: 'Multiple Of',
init: function (that, fn, preDefined = null) {
var el = $('<input/>').on('input', function() { fn(that, this) });
if (preDefined !== null) {
$(el).val(preDefined[0]);
}
return el;
},
...
}
The next property that needs to be added is searchBuilder.conditions[type].inputValue. This function extracts the values from the jQuery element that we just created, and returns it to be used in the search. An in depth description of how to do this is provided here
multipleOf: {
conditionName: 'Multiple Of',
init: function (that, fn, preDefined = null) {
var el = $('<input/>').on('input', function() { fn(that, this) });
if (preDefined !== null) {
$(el).val(preDefined[0]);
}
return el;
},
inputValue: function (el) {
return $(el[0]).val();
}
...
}
Next is the searchBuilder.conditions[type].isInputValid function. This function returns a boolean indicating whether the criteria should be included in the search or not. We want the criteria only to be included if there is a value within the input element. An in depth description of how to do this is provided here
multipleOf: {
conditionName: 'Multiple Of',
init: function (that, fn, preDefined = null) {
var el = $('<input/>').on('input', function() { fn(that, this) });
if (preDefined !== null) {
$(el).val(preDefined[0]);
}
return el;
},
inputValue: function (el) {
return $(el[0]).val();
},
isInputValid: function (el, that) {
return $(element[0]).val().length !== 0;
},
...
}
Lastly, we need to provide the search function that will determine whether the row should be included in the results of the filter or not, if the searchBuilder.conditions[type].isInputValid has allowed the criteria. An in depth description of how to do this is provided here
$('#myTable').DataTable( {
dom: 'Qlfrtip',
searchBuilder:{
conditions:{
num:{
multipleOf: {
conditionName: 'Multiple Of',
init: function (that, fn, preDefined = null) {
var el = $('<input/>').on('input', function() { fn(that, this) });
if (preDefined !== null) {
$(el).val(preDefined[0]);
}
return el;
},
inputValue: function (el) {
return $(el[0]).val();
},
isInputValid: function (el, that) {
return $(el[0]).val().length !== 0;
},
search: function (value, comparison) {
return value % comparison === 0;
}
}
}
}
}
})
And that's it, a very simple plug-in completed! You can see this in action in this example
Custom column Type
It is also possible to add conditions for any custom column.type that you have active on the table. Say you had a column type of multipleNum you wanted to add the above condition to, you would initialise as follows.
$('#myTable').DataTable( {
dom: 'Qlfrtip',
searchBuilder:{
conditions:{
multipleNum:{
multipleOf: {
conditionName: 'Multiple Of',
init: function (that, fn, preDefined = null) {
var el = $('<input/>').on('input', function() { fn(that, this) });
if (preDefined !== null) {
$(el).val(preDefined[0]);
}
return el;
},
inputValue: function (el) {
return $(el[0]).val();
},
isInputValid: function (el, that) {
return $(el[0]).val().length !== 0;
},
search: function (value, comparison) {
return value%comparison === 0;
}
}
}
}
}
})
Static define
Defining a plug-in during initialisation is useful for single tables, but limits core reuse options if you want to use it on multiple tables. For this, you can extend or modify SearchBuilder's conditions object:
$.fn.dataTable.ext.searchBuilder.conditions.num.multipleOf = {
conditionName: 'Multiple Of',
init: function (that, fn, preDefined = null) {
var el = $('<input/>').on('input', function() { fn(that, this) });
if (preDefined !== null) {
$(el).val(preDefined[0]);
}
return el;
},
inputValue: function (el) {
return $(el[0]).val();
},
isInputValid: function (el, that) {
return $(el[0]).val().length !== 0;
},
search: function (value, comparison) {
return value%comparison === 0;
}
};
$('#myTable').DataTable({
dom: 'Qfrtip'
});
Notice that all of the properties within the object are exactly the same as above.
If you create a plug-in condition that uses this method and you would like to share with the DataTables community, we would be delighted to hear from you!