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.

$('#example').DataTable({
    searchBuilder: {
        preDefined: {
            // We are going to be working here
        }
    }
})

It is then possible to build up the top group by adding a searchBuilder.preDefined.criteria property and a searchBuilder.preDefined.logic property.

$('#example').DataTable({
    searchBuilder: {
        preDefined: {
            criteria: [
                // Criteria or sub-group objects go here
            ],
            logic: 'OR' // Use `OR` logic for the group
        }
    }
})

The default for the searchBuilder.preDefined.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 searchBuilder.preDefined.criteria option 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.

$('#example').DataTable({
    searchBuilder: {
        preDefined: {
            criteria: [
                {
                    data: 'Age',
                    condition: '=',
                    value: [50]
                }
            ]
        }
    }
})

The searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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 searchBuilder.preDefined.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.

$('#example').DataTable({
    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 searchBuilder.preDefined.logic property. 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.

$('#example').DataTable({
    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 structure as searchBuilder.preDefined to the searchBuilder.preDefined.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.

$('#example').DataTable({
    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.

$('#example').DataTable({
    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 searchBuilder.preDefined.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.

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.