This plugin/library was created by me out of necessity, and released to help others that may need it. I don't have time to actively maintain the code to keep up with DataTables updates or bugs in my code. If you run into an issue, feel free to attribute your own changes. ๐
Store the DataTable conditions within the URL hash every time a condition is changed, such as the page, length, search or a column order, making it possible to copy/paste the URL. Once said URL is loaded, the conditions will be retrieved from the URL hash and implemented to the table on DT initialization.
The Keep Conditions plugin has the capability of keeping the conditions for the following:
Setting/Extension | Name | Key | Links |
---|---|---|---|
Table Search String | search |
f |
|
Column Ordering/Sorting | order |
o |
|
Pagination | page |
p |
|
Table Length | length |
l |
|
Column Visibility | colvis |
v |
ColVis (A buttons extension) |
Scroll Position | scroller |
s |
Scroller |
Column Reordering | colorder |
c |
ColOrder |
Note: The only condition that I decided to not implement, would be the row order (for the RowReorder extension). There are several reasons I decided not to, but primarily, because it would be difficult to know which rows were in what order, unless the RowId option was used, which is mostly only for JSON or AJAX sourced tables, which I found its a pain to get rowReorder to work for those data sources anyways.
Parameter | Type | Default | Description |
---|---|---|---|
keepConditions |
boolean/object/string/array | true |
Main setting object, or array of conditions to enable, or string of condition keys) |
keepConditions.conditions |
string/array | None | Conditions to enable (Array of names, or string of keys) |
keepConditions.attachEvents |
boolean | true |
Enable auto-updating of the URL hash whenever the events associated to the conditions are triggered |
Method | Parameters |
---|---|
keepConditions.detachEvents |
[conditions Null (all events/conditions), Array (Specific events/conditions)] |
keepConditions.attachEvents |
[conditions Null (all events/conditions), Array (Specific events/conditions)] |
keepConditions.structureHash |
[returnHash Null/false (Updates URL hash), true (Returns URL Hash as string)] |
keepConditions.enableCondition |
[condition String (Condition name/key to enable)], [updateHash true (Updates hash after condition enables)] |
keepConditions.disableCondition |
[condition String (Condition name/key to disable)], [updateHash true (Updates hash after condition disables)] |
Keep Conditions plugin comes with a button! As long as you properly setup the buttons extension, you can include the button copyConditions
, which will display a button, when clicked, the URL will either be copied to the viewers clipboard (with the table conditions), or display an input with selected text, making it easy to copy and share the URL. An example if this is below.
KeepConditions can be initiated 2 different ways:
- Setting the
keepConditions
item within the DataTables initial settings to eithertrue
, or define an object with configuration settings. - Manually initializing a new KeepConditions object via the new keyword, specifying the DataTable by passing one of three different items as the only parameter
- The DataTable instance:
var table = $('#table').DataTable(); new KeepConditions(table);
- The DataTable API instance:
var api = new $.fn.dataTable.Api(table); new KeepConditions(api);
- A CSS selector for the table:
new KeepConditions($('#table'));
Basic Initialization (Enabling all available and initialized options)
$('#example').DataTable({
keepConditions: true
});
Advanced Initialization (Select what conditions to keep)
$('#example').DataTable({
dom: 'lfrtip',
keepConditions: {
conditions: ['page','length','search','order','scroller','colvis','colorder']
// Or by keys..
conditions: 'plfosvc'
}
});
Same result as the above, specifying
$('#example').DataTable({
dom: 'lfrtip',
keepConditions: ['page','length','search','order','scroller','colvis','colorder']
// Or by keys..
keepConditions: 'plfosvc'
});
Basic Initialization (With button)
$('#example').DataTable({
keepConditions: true,
dom: 'Blfrtip',
buttons: [
'copyConditions'
]
});
Multiple Tables, Basic & Advanced w/ Button
$('#example-1').DataTable({
dom: 'Blftipr',
keepConditions: true,
buttons: [
'copyConditions'
]
});
$('.example-2').DataTable({ // Using Class
dom: 'lftipr',
pageLength: 25,
keepConditions: ['search','order','page','length']
});
Customizing the button settings, as well as changing the text for the button and related alerts (Usful for when custom languages are needed)
$('#example').DataTable({
language: {
// Customize the text for the button
keepConditions: {
// Title to show if text was successfully copied
btnCopyTitle: 'URL Copied',
// Body for above
btnCopyBody: 'The URL was copied to your clipboard! Have a nice day',
// Title to show if text was NOT copied, and an input is
// shown with the content selected, and viewer must copy
btnSelectTitle: 'Copy URL',
// Body for above
btnSelectBody: 'Copy the content of the input by either right clicking ' +
'and selecting "copy", or press Ctrl + "c" on your keyboard'
}
},
// Initialize KeepConditions for all available settings/extensions/plugins
keepConditions: true,
dom: 'Blftipr',
buttons: [
// Initialize button with customizations
{
extend: 'copyConditions',
// Text for the button itself
text: 'Copy Table Conditions',
// Timeout for the dialog if content was successfully copied
selectTimeout: 1500,
// Timeout for dialog if viewer needs to manually copy content
copyTimeout: 4000
}
]
});
Initiation with the ColVis button, as well as the ColReorder and Scroller extensions, on an AJAX sourced table, as well as disabling un-necessary conditions.
$('#example').DataTable({
ajax: "dataSrc.txt",
deferRender: true,
scrollY: 200,
scrollCollapse: true,
scroller: true,
dom: 'Bfrtip',
colReorder: true,
buttons: [
'colvis'
],
keepConditions: 'fovs'
});
Update the URL Hash manually
table.keepConditions.structureHash();
Retrieve the potential URL hash as a string (without updating)
var hashStr = table.keepConditions.structureHash(true);
Enable all conditions by attaching the update function to all associated events
table.keepConditions.attachEvents();
Disable specific conditions by detaching the update function from the events associated with the conditions
table.keepConditions.detachEvents(['search','order']);