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.preDefined
searchBuilder.rebuild()
- Takes an argument which is an object of the same structure assearchBuilder.preDefined
and 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.