1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
|
<?xml version="1.0" encoding="UTF-8" ?>
<dt-api group="core">
<name>search()</name>
<summary>Search for data in the table.</summary>
<since>1.10</since>
<type type="function">
<signature>search()</signature>
<description>Get the currently applied global search. If there is more than one table in the API's context, the search term of the first table will be returned. Use `dt-api table()` if you require the search term of a different table in the API's context.</description>
<returns type="string">The currently applied global search. This may be an empty string if no search is applied.</returns>
</type>
<type type="function">
<signature>search( input [, regex[ , smart[ , caseInsen ]]] )</signature>
<description>Set the global search to use on the table. Note this doesn't actually perform the search, but rather queues it up - use `dt-api draw()` to perform the search and display the result.</description>
<parameter type="string" name="input">
Search string to apply to the table.
</parameter>
<parameter type="boolean" name="regex" default="false">
Treat as a regular expression (`true`) or not (default, `false`).
</parameter>
<parameter type="boolean" name="smart" default="true">
Perform smart search (default, `true`) or not (`false`). See below for a description of smart searching.
Note that to perform a smart search, DataTables uses regular expressions, so if enable regular expressions using the second parameter to this method, you will likely want to disable smart searching as the two regular expressions might otherwise conflict and cause unexpected results.
</parameter>
<parameter type="boolean" name="caseInsen" default="true">
Do case-insensitive matching (default, `true`) or not (`false`).
</parameter>
<returns type="DataTables.Api">DataTables API instance</returns>
</type>
<description>
The ability to search a table for data is core to the concept of DataTables, as it allows data to be easily accessed by users. This method provides the ability to control the global search of a table through the API. The global search is performed across all searchable columns (see `dt-init columns.searchable` to disable searching for certain columns). If data is found matching in any column, then the whole row is matched and shown in the result set. Searching on individual columns can be performed using the `dt-api columns().search()` and `dt-api column().search()` methods.
DataTables has a built in search algorithm referred to as "smart" searching and is designed to make searching the table data, easy to use for the end user. A smart search in DataTables provides the following abilities:
* Match words out of order. For example if you search for `-string Allan Fife` it would match a row containing the words `-string Allan` and `-string Fife`, regardless of the order or position that they appear in the table.
* Partial word matching. As DataTables provides on-the-fly filtering with immediate feedback to the user, parts of words can be matched in the result set. For example `-string All` will match `-string Allan`.
* Preserved text. DataTables 1.10 adds the ability to search for an exact phrase by enclosing the search text in double quotes. For example `-string "Allan Fife"` will match only text which contains the phrase `-string Allan Fife`. It will not match `-string Allan is in Fife`.
The smart search ability of DataTables is performed using a regular expression and can be enabled or disabled using the third parameter of this method. If you wish to use a custom regular expression, for example to perform whole word exact matching, you would need to enable the regular expression option (second parameter) and disable the smart search option (third parameter) to ensure that the two do not conflict. DataTables provides a utility method (`dt-api $.fn.dataTable.util.escapeRegex()`) to escape regular expression special characters, which can be useful if you mix user input with regular expressions.
Note that this search ability in DataTables is actually technically a filter since it is subtractive. However, we term is a search to avoid naming conflict with the `dt-api filter` helper method.
Please be aware that this method sets the search to apply to the table only - it does not actually perform the search. In order to have the search performed and the result shown, use the `dt-api draw()` method, which can be called simply as a chained method of the `dt-api search()` method's returned object - for example `table.search( 'Fred' ).draw();`. This is to provide the ability to queue multiple changes before performing a draw.
</description>
<example title="Search the table using a custom input"><![CDATA[
var table = $('#example').DataTable();
// #myInput is a <input type="text"> element
$('#myInput').on( 'keyup', function () {
table.search( this.value ).draw();
} );
]]></example>
<related type="option">searching</related>
<related type="option">columns.searchable</related>
<related type="api">columns().search()</related>
<related type="api">column().search()</related>
<related type="api">$.fn.dataTable.util.escapeRegex()</related>
</dt-api>
|
