DOM 選項

Anderson

dom

Since: DataTables 1.10

Define the table control elements to appear on the page and in what order.

Description

DataTables will add a number of elements around the table to both control the table and show additional information about it. The position of these elements on screen are controlled by a combination of their order in the document (DOM) and the CSS applied to the elements. This parameter is used to control their ordering and additional mark-up surrounding them in the DOM.

Each table control element in DataTables has a single letter associated with it, and that letter it used in this dom configuration option to indicate where that element will appear in the document order.

Options

The built-in table control elements in DataTables are:

• l - length changing input control
• f - filtering input
• t - The table!
• i - Table information summary
• p - pagination control
• r - processing display element

Each option can be specified multiple times (with the exception of the table itself), which can be used to have table controls both above and below the table. DataTables will automatically synchronise these multiple controls.

In addition to the above control options, there are two constants DataTables understands (note that these two options are deprecated in 1.10 and will be removed in 1.11 along side the separation of the jQueryUI option into its own theme file):

• H - jQueryUI theme "header" classes (fg-toolbar ui-widget-header ui-corner-tl ui-corner-tr ui-helper-clearfix)
• F - jQueryUI theme "footer" classes (fg-toolbar ui-widget-header ui-corner-bl ui-corner-br ui-helper-clearfix)

Markup

Further to these options, you can also specify additional div elements to be inserted into the document, which can be used for styling / nesting of the control elements. To add tags, the following syntax is expected:

• < and > - div element
• <"class" and > - div with a class
• <"#id" and > - div with an ID
• <"#id.class" and > - div with an ID and a class

Styling

The styling libraries that DataTables supports will override the default value of the dom parameter and replace it with a value that is suitable for their layout system. For example the Bootstrap integration makes use of Bootstrap's grid layout.

The defaults for the styling integrations are:

Bootstrap 3:

Javascript
1
2
3
"<'row'<'col-sm-6'l><'col-sm-6'f>>" +
"<'row'<'col-sm-12'tr>>" +
"<'row'<'col-sm-5'i><'col-sm-7'p>>",

Bootstrap 4:

Javascript
1
2
3
"<'row'<'col-sm-12 col-md-6'l><'col-sm-12 col-md-6'f>>" +
"<'row'<'col-sm-12'tr>>" +
"<'row'<'col-sm-12 col-md-5'i><'col-sm-12 col-md-7'p>>",

Foundation:

Javascript
1
2
3
"<'row'<'small-6 columns'l><'small-6 columns'f>r>"+
"t"+
"<'row'<'small-6 columns'i><'small-6 columns'p>>",

jQuery UI:

Javascript
1
2
3
'<"fg-toolbar ui-toolbar ui-widget-header ui-helper-clearfix ui-corner-tl ui-corner-tr"lfr>'+
't'+
'<"fg-toolbar ui-toolbar ui-widget-header ui-helper-clearfix ui-corner-bl ui-corner-br"ip>',

Semantic UI:

Javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
"<'ui stackable grid'"+
    "<'row'"+
        "<'eight wide column'l>"+
        "<'right aligned eight wide column'f>"+
    ">"+
    "<'row dt-table'"+
        "<'sixteen wide column'tr>"+
    ">"+
    "<'row'"+
        "<'seven wide column'i>"+
        "<'right aligned nine wide column'p>"+
    ">"+
">"

Plug-ins

DataTables feature plug-ins can be developed to add additional features to DataTables and often will make use of this option, adding new letters to the DataTables core features. For example Buttons adds the B option to dom to specify where table control buttons should be inserted into the table.

The following extensions can be initialised through the dom option:

• B - Buttons
• R - ColReorder
• S - Scroller
• P - SearchPanes
• Q - SearchBuilder

Future development

Note, I am aware that this is the most complex option in DataTables and it takes a fair amount of understanding, particularly when using the styling integration options! The plan is to revamp this option in 1.11 to make it easier to use.

Type

This option can be given in the following type(s):

• string

Default

• Value: lfrtip

Note that if you use one of the styling integration options such as Bootstrap, Foundation or jQuery UI they will alter the default value for this parameter. Please see the description for the values they set.

Examples

No filtering input control:

Javascript
1
2
3
4
5
6
7
8
9
10
/* Results in:
    {length}
    {processing}
    {table}
    {information}
    {pagination}
*/
$('#example').dataTable( {
  "dom": 'lrtip'
} );

Simpler wrapper element:

Javascript
1
2
3
4
5
6
7
8
9
10
11
12
/* Results in:
    <div class="wrapper">
      {filter}
      {length}
      {information}
      {pagination}
      {table}
    </div>
*/
$('#example').dataTable( {
  "dom": '<"wrapper"flipt>'
} );

Length and filter above, information and pagination below table:

Javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* Results in:
    <div>
      {length}
      {filter}
      <div>
        {table}
      </div>
      {information}
      {pagination}
    </div>
*/
$('#example').dataTable( {
  "dom": '<lf<t>ip>'
} );

Table summary in header, filtering, length and processing in footer, with a clearing element.:

Javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/* Results in:
    <div class="top">
      {information}
    </div>
    {processing}
    {table}
    <div class="bottom">
      {filter}
      {length}
      {pagination}
    </div>
    <div class="clear"></div>
*/
$('#example').dataTable( {
  "dom": '<"top"i>rt<"bottom"flp><"clear">'
} );