Table Widget


Table Widgetversion added: 1.3

Description: Creates a responsive table

QuickNavExamples

Methods

Events

Responsive tables

One of the biggest challenges in responsive web design (RWD) is presenting tabular data. Large tables with lots of columns don't fit on smaller screens and there isn't a simple way to re-format the table content with CSS and media queries for an acceptable presentation. To address this, the framework offers two different options for presenting tables responsively. Each has benefits and tradeoffs, the right choice will depend on the data being presented.

Reflow mode - Re-formats the table columns at narrow widths so each row of data is presented as a formatted block of label/data pairs. This is ideal for tables with product or contact information with more complex or lengthy data formatting that doesn't need comparison across rows of data.

Column toggle mode - Selectively hides columns at narrower widths as a sensible default but also offers a menu to let users manually control which columns they want to see. This mode is better for financial data tables that have compact values and need to maintain comparisons across columns and rows of data. It can also be used for building things like product comparison tables.

The responsive table feature is built with a core table plugin (table.js) that initializes when the data-role="table" attribute is added to the markup. This plugin is very lightweight and adds ui-table class, parses the table headers and generates information on the columns of data, and fires a tablecreate event. Both the table modes, reflow and column toggle, are written as extensions to the table widget that hook in via the create event to add the additional behaviors that make the tables responsive. Reflow is the default mode so if the extension is present, it will be applied automatically if the data-role="table" attribute is on the table.

If only one mode is used on a project, the download builder tool can be used to package only the table plugin and the single extension to save code weight.

General table markup guidelines

Here is the basic table markup you should use for both table modes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<table data-role="table" id="my-table" data-mode="reflow">
<thead>
<tr>
<th>Rank</th>
<th>Movie Title</th>
<th>Year</th>
<th><abbr title="Rotten Tomato Rating">Rating</abbr></th>
<th>Reviews</th>
</tr>
</thead>
<tbody>
<tr>
<th>1</th>
<td><a href="foo.com" data-rel="external">Citizen Kane</a></td>
<td>1941</td>
<td>100%</td>
<td>74</td>
</tr>
</tbody>
</table>

Both table modes start with standard HTML table markup but there are some specific guidelines you must follow for the responsive table to work correctly:

  • Follow standard HTML table markup guidelines for proper semantics
  • Do not use rowspan or colspan in your tables, these aren't supported except for grouped headers (see below)
  • Adding thead and tbody elements are optional but provide improved semantics
  • Assign a unique ID to the table (required for the column toggle mode)
  • Add the data-role="table" to apply the responsive table plugin
  • The default table mode is reflow, add data-mode="columntoggle" change modes
  • The first row of the table must contain the table headers, be sure to use TH instead of TD tags
  • To display longer table header text in the column chooser or reflow labels, wrap the text in the TH with a abbr element and set the title. This string will be used in place.

Styling and theming tables

The responsive table plugin is as minimally styled as possible to give you a clean slate for your designs. The plugin focuses primarily on the difficult scripting elements: generating the labels for the reflow table and creating the button and column chooser popup. Out of the box, the table just has a few basic style rules to add a bit of padding and set the vertical alignment of cells to be top left for visual consistency.

The table will adapt to whatever content block it sits on, but there isn't an explicit theming attribute for this widget. We did this because it's simple enough to add theme classes like ui-body-a to individual cells if a more heavily themed look is wanted.

Row strokes and stripes

The theme CSS contains a preset row strokes and alternating row stripes style which can be applied by adding table-stroke or table-stripe class to the table element.

Note: the table-stroke and table-stripe classes are deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. The demos contain an example how to apply these styles with custom CSS.

Options

classes.table 

Type: String
Default: "ui-table"
Class assigned to the table.

The classes option is only configurable via JavaScript because it expects an object literal value.

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the table with the defaults option specified:

1
2
3
$( ".selector" ).table({
defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
// Getter
var defaults = $( ".selector" ).table( "option", "defaults" );
// Setter
$( ".selector" ).table( "option", "defaults", true );

disabled 

Type: Boolean
Default: false
Disables the table if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the table with the disabled option specified:

1
2
3
$( ".selector" ).table({
disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
// Getter
var disabled = $( ".selector" ).table( "option", "disabled" );
// Setter
$( ".selector" ).table( "option", "disabled", true );

initSelector 

Type: Selector
Default: See below

The default initSelector for the table widget is:

1
":jqmData(role='table')"

Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit event and overwriting the initSelector on the prototype:

1
2
3
$( document ).on( "mobileinit", function() {
$.mobile.table.prototype.initSelector = "div.custom";
});

Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.

The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates table widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

Methods

rebuild()Returns: jQuery (plugin only)

Re-process the entire table to ensure it is displayed correctly.
  • This method does not accept any arguments.
Code examples:

Invoke the rebuild method:

1
$( ".selector" ).table( "rebuild" );

Events

create( event, ui )Type: tablecreate

Triggered when a table is created

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the table with the create callback specified:

1
2
3
$( ".selector" ).table({
create: function( event, ui ) {}
});

Bind an event listener to the tablecreate event:

1
$( ".selector" ).on( "tablecreate", function( event, ui ) {} );

Example:

A basic example of a reponsive table.

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
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>table demo</title>
<link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
<div data-role="page" id="page1">
<div data-role="header">
<h1>jQuery Mobile Example</h1>
</div>
<div role="main" class="ui-content">
<table data-role="table" id="my-table" data-mode="reflow">
<thead>
<tr>
<th>Rank</th>
<th>Movie Title</th>
<th>Year</th>
<th><abbr title="Rotten Tomato Rating">Rating</abbr></th>
<th>Reviews</th>
</tr>
</thead>
<tbody>
<tr>
<th>1</th>
<td><a href="foo.com" data-rel="external">Citizen Kane</a></td>
<td>1941</td>
<td>100%</td>
<td>74</td>
</tr>
</tbody>
</table>
</div>
</div>
</body>
</html>

Demo: