Predefined Searches
SearchBuilder allows you to set predefined searches using the searchBuilder.preDefined option so that the page loads with a search applied. This is done by declaring criteria and sub groups.
Creating a simple predefined search
To create a predefined search with only one criteria, you take the normal SearchBuilder initialisation as shown below and add the searchBuilder.preDefined object, which defined search conditions in the object format given by SearchBuilder.Criteria.
new DataTable('#myTable', {
layout: {
top: {
searchBuilder: {
preDefined: {
// We are going to be working here
}
}
}
}
});
It is then possible to build up the top group by adding a using the properties of SearchBuilder.Criteria to define the initial search condition:
new DataTable('#myTable', {
layout: {
top: {
searchBuilder: {
preDefined: {
criteria: [
// Criteria or sub-group objects go here
],
logic: 'OR' // Use `OR` logic for the group
}
}
}
}
});
The default for the logic property is AND meaning that if this property is not set, SearchBuilder will default to AND logic for the group. The only other value that this property can take is OR as shown above. To keep things simple, we won't set a logic property and use the default.
The criteria parameter of SearchBuilder.Criteria takes two different types of objects. These can either be for a sub-group, in which case the structure is the same as the top level or a criteria. There is more detail on this lower down in the page, for now let's just add a single criteria object. The following configuration will declare a predefined search where the Age column must equal 50.
searchBuilder: {
preDefined: {
criteria: [
{
data: 'Age',
condition: '=',
value: [50]
}
]
}
}
The criteria.data property is used to specify the column that the filtering should be applied to. If you don't define anything here, the criteria will appear blank. Equally if the string provided does not match the column title, it will not be selected and the criteria will remain blank.
The criteria.condition property is used to specify which condition should be selected and used when filtering the dataset. If it is not set then no condition or values will be applied, however if the data property is provided then it will still be preset in the data select. This will also apply if the string provided does not match any of the conditions available for that column type.
The criteria.value property is used to specify the values that should be used when filtering the dataset. This is an array as it is possible for some of the conditions, such as "Between" to require two inputs. The values will be applied to the inputs in the same order as they exist in the array. It is still possible for the data and condition select elements to have selections made even if this property is undefined.
Since SearchBuilder version 1.2.0 serverSide processing is supported. When this is the case the criteria.value property is mutated in a couple of different ways. First, if the column is a number type then the values returned here are stripped of non-numerical characters so that only numbers and decimal places remain. This is to allow the server-side integrations to easily implement it's conditions. The second mutation that occurs here is to remove the criteria.value property, replacing it with 2 new properties searchBuilder.preDefined.criteria.value1 and searchBuilder.preDefined.criteria.value2. These are the first and second values within the criteria.value array. This is done to make the interface with the .NET library smoother. SearchBuilder will do this automatically when implementing preDefined searches.
Another change in version 1.2.0 is the addition of the criteria.type property. This is only required in the searchBuilder.preDefined object when using server-side processing. This means that the server can tell the type of the field that the search is being applied to. In some cases this is required as the behaviour of some conditions are slightly different between column types.
The final change that was made to support server-side processing was to add the criteria.origData property. This should be set to the value of the original field name so that the server-side script knows which field to apply the condition to. Both this and the criteria.data are required as the two are not necessarly equal when it comes to displaying the DataTable.
Taking all of this into account, preDefined criteria should look more look like this.
searchBuilder: {
preDefined: {
criteria: [
{
condition: '=',
data: 'Age',
origData: 'age',
type: 'num',
value: [50]
}
]
}
}
Predefined search with multiple criteria
It is possible to create more complex searches by adding more criteria to the group by adding to the criteria array in the same fashion as discussed above. The following config will result in a predefined search where Age must be greater than 50 and the Office must equal Edinburgh.
searchBuilder: {
preDefined: {
criteria: [
{
data: 'Age',
condition: '>',
value: [50]
},
{
data: 'Office',
condition: '=',
value: ['Edinburgh']
}
]
}
}
Changing the logic operator of a group
The initial logic operator that is applied to a group can be easily changed by setting the logic property of the SearchBuilder.Criteria object. The previous example has been edited so that the predefined search will now mean that only records where the Age is greater than 50 or the Office is equal to Edinburgh are included.
searchBuilder: {
preDefined: {
criteria: [
{
data: 'Age',
condition: '>',
value: [50]
},
{
data: 'Office',
condition: '=',
value: ['Edinburgh']
}
],
logic: 'OR'
}
}
Declaring sub-groups
It is also possible to declare sub-groups which are capable of holding their own criteria and setting their own logic. This is done by adding an object with the same SearchBuilder.Criteria structure as searchBuilder.preDefined to the criteria array alongside any other criteria. The example below is an edit of the previous example. Now the Edinburgh filter will appear in a sub group.
searchBuilder: {
preDefined: {
criteria: [
{
data: 'Age',
condition: '>',
value: [50]
},
{
criteria:[
{
data: 'Office',
condition: '=',
value: ['Edinburgh']
}
],
logic: 'AND'
}
],
logic: 'OR'
}
}
Whilst this will have exactly the same behaviour as before, we can now add another criteria to the sub-group. The new predefined search will return records where the Age is greater than 50, or the records Office column is equal to Edinburgh and the 'Name' is equal to Dai Rios.
searchBuilder: {
preDefined: {
criteria: [
{
data: 'Age',
condition: '>',
value: [50]
},
{
criteria:[
{
data: 'Office',
condition: '=',
value: ['Edinburgh']
},
{
data: 'Name',
condition: '=',
value: ['Dai Rios']
}
],
logic: 'AND'
}
],
logic: 'OR'
}
}
The recursive structure of the criteria array means that sub-groups can be created as deep as you desire.
API
SearchBuilder has 2 API methods that are related to predefined searching.
searchBuilder.getDetails()- returns an object of the same structure as would be used forsearchBuilder.preDefinedsearchBuilder.rebuild()- Takes an argument which is an object of the same structure assearchBuilder.preDefinedand applies it to SearchBuilder.
The two go very well together, as it allows you to save a specific point and then reload it later. You can also make use of these to implement SearchBuilder in the background without actually displaying it to the end user. This allows devs to implement their own advanced searches without displaying the SearchBuilder UI. You may have your own UI in mind, or you could implement set searches using buttons.
searchBuilder.getDetails() returns an object of the same structure as has been discussed above that represents the SearchBuilder structure that is currently displayed. If you are planning on constructing a large preDefined search a good way to automatically generate it is to create it in SearchBuilder manually and then run this method.
searchBuilder.rebuild() takes an argument which is the same as the output of searchBuilder.getDetails() hence why the two go hand in hand. This method can apply a search at any point to SearchBuilder. A good use could be to create a reset button when using preDefined searches and pass the same object into it. If no argument is provided then SearchBuilder is cleared completely.