Skip to content

Commit

Permalink
New: -init select.selectable option which is a callback that can be…
Browse files Browse the repository at this point in the history
… used to determine if a function can be selected or not.

New: `-api select.cumulative()` method which can be used with server-side processing to get all selected rows across multiple pages.
  • Loading branch information
AllanJard committed Sep 10, 2024
1 parent 877c7f4 commit 7d1e3a0
Show file tree
Hide file tree
Showing 5 changed files with 206 additions and 74 deletions.
9 changes: 3 additions & 6 deletions examples/checkbox/serverSide.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<js>
<![CDATA[
$('#example').DataTable({
ajax: '/examples/server_side/scripts/objects.php',
ajax: '/examples/server_side/scripts/ids-objects.php',
columns: [
{data: null, orderable: false, searchable: false, render: DataTable.render.select()},
{data: 'first_name'},
Expand All @@ -26,7 +26,7 @@ $('#example').DataTable({
<js-vanilla>
<![CDATA[
new DataTable('#example', {
ajax: '/examples/server_side/scripts/objects.php',
ajax: '/examples/server_side/scripts/ids-objects.php',
columns: [
{data: null, orderable: false, searchable: false, render: DataTable.render.select()},
{data: 'first_name'},
Expand All @@ -46,10 +46,7 @@ new DataTable('#example', {

<info><![CDATA[
This example demonstrates the use of Select's checkboxes with DataTables' [server-side processing mode](https://datatables.net/manual/server-side). When in this mode DataTables only has the rows that are displayed at the client-side, so row selection cannot happen on pages of data which are not displayed. This results in two important points:
1. Row selection is not preserved across pages. Select a row on page 1, flick to the second page and then back. Your selected row is no longer selected (since it didn't exist when the table was displaying the second page!).
2. Select all will select only the records on the current page.
This example demonstrates the use of Select's checkboxes with DataTables' [server-side processing mode](https://datatables.net/manual/server-side). See [this example](../initialisation/server-side-processing.html) for more details about using Select with server-side processing and the implications.
]]></info>

Expand Down
64 changes: 64 additions & 0 deletions examples/initialisation/select.cumulative().xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<?xml version="1.0" encoding="UTF-8" ?>
<dt-api library="Select">
<name>select.cumulative()</name>
<summary>Get a list of selected row ids across pages (server-side processing)</summary>
<since>2.1.0</since>

<type type="function">
<signature>select.cumulative()</signature>
<returns type="string[]">
A list of IDs for the rows that are selected.
</returns>
<description>
Get a list of IDs for rows that are selected regardless of paging (for use with server-side processing).
</description>
</type>

<description>
When server-side processing is enabled (`-init serverSide`) DataTables only has knowledge of the rows that are currently shown. That might be only a fraction of the total number of rows in the table, since of course the whole point of server-side processing is to speed things up when working with large data sets.

As a result Select can only perform selection on rows that are displayed at the client-side. However, Select (as of v2.1.0) will retain a list of all rows that are selected, both reselecting them when they are displayed again, but also providing the list of selected rows (regardless of paging or filtering) using this method.

For this to work each row needs to be uniquely addressable via a given data point - typically and id / primary key value. Use `-init rowId` to tell DataTables where that value can be found. The values returned by this method will contain these ids.

When operating with these ids, it is important that you validate that the id still exists when performing an action on it. This is because a row might be deleted, but Select might not be aware of this fact and retain it in its list.
</description>

<example title="Get a list of ids on button press"><![CDATA[
new DataTable('#example', {
ajax: '/api/data',
columns: [
{ data: 'first_name' },
{ data: 'last_name' },
{ data: 'position' },
{ data: 'office' },
{ data: 'start_date' },
{ data: 'salary' }
],
layout: {
topStart: {
buttons: [
'pageLength',
{
text: 'View selected ids',
action: function (e, dt) {
alert(
'Information about selected rows: '+
JSON.stringify(dt.select.cumulative())
);
}
},
'selectAll',
'selectNone'
]
}
},
processing: true,
select: true,
serverSide: true
});
]]></example>

<related>-init rowId</related>
<related>-init select.headerCheckbox</related>
</dt-api>
62 changes: 62 additions & 0 deletions examples/initialisation/selectable.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
<?xml version="1.0" encoding="UTF-8" ?>
<dt-example table-type="html" order="11">

<css lib="datatables select">
tr.unselectable {
opacity: 0.5;
}
</css>
<js lib="jquery datatables select">
<![CDATA[
$('#example').DataTable({
rowCallback: function (tr, rowData) {
if (rowData[2] === 'New York') {
$(tr).addClass('unselectable');
}
},
select: {
selectable: function (rowData) {
return rowData[2] !== 'New York';
}
}
});
]]>
</js>

<js-vanilla>
<![CDATA[
new DataTable('#example', {
rowCallback: function (tr, rowData) {
if (rowData[2] === 'New York') {
tr.classList.add('unselectable');
}
},
select: {
selectable: function (rowData) {
return rowData[2] !== 'New York';
}
},
columnDefs: [
{
target: 0,
render: DataTable.render.select()
}
]
});
]]>
</js-vanilla>

<title lib="Select">Disallow selection on specific rows</title>

<info><![CDATA[
This example demonstrates the ability to disable row selection on specific rows using the `-init select.selectable` option. This must be given as a function which will then check the row to see if it should be selectable or not (typically this determination will be based on the data in the row). If not, Select will ignore operations on this row.
In this example all rows which have a location of "New York" are unselectable. To show this visually a little bit of CSS is used to fade those rows out (class added by the `-init rowCallback` handler). This is optional but it gives the end user a visual clue. If you are using a checkbox for row selection, rows which don't match the selectable requirements will not have a checkbox shown.
]]></info>

</dt-example>
8 changes: 4 additions & 4 deletions examples/initialisation/server-side-processing.xml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ new DataTable('#example', {
buttons: [
'pageLength',
{
text: 'View selection info',
text: 'View selected ids',
action: function (e, dt) {
alert(
'Information about selected rows: '+
Expand All @@ -80,11 +80,11 @@ new DataTable('#example', {
Select 2.1 introduced support for server-side processing - there is special consideration here as the row selection is client-side, but not all rows are available at the client-side (only those drawn for the current display). This has an impact on the API as `.rows({selected: true})` will only be able to fetch information about the rows that are currently display.
To address this, Select introduces the `-api select.cumulative()` method which can be used to get the ids of all rows that are selected. Note that the data source _must_ have a unique id per row and you may have to se the `-init rowId` option to tell DataTables what it is called (it looks for `DT_RowId` by default).
To address this, Select introduces the `-api select.cumulative()` method which can be used to get the ids of all rows that are selected, regardless of paging or filtering. Note that the data source _must_ have a unique id per row and you may have to se the `-init rowId` option to tell DataTables what it is called (it looks for `DT_RowId` by default).
`-api select.cumulative()` handles row selection by returning all rows which have been selected _or_ by all rows which have been deselected, which is important for the case when the end user uses the "select all" option of the header checkbox.
Additionally, the `-button selectAll` button and checkbox header (when used with checkbox selection) will only select the currently displayed rows. This is because the client-side can't know what other rows there are that can be selected.
This example lets you experiment with row selection when server-side processing is enabled.
This example let's you experiment with Select when server-side processing is enabled.
]]></info>

Expand Down
Loading

0 comments on commit 7d1e3a0

Please sign in to comment.