-
Notifications
You must be signed in to change notification settings - Fork 60
/
Copy pathtable-reflow.xml
228 lines (204 loc) · 12.1 KB
/
table-reflow.xml
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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
<entry name="table" namespace="fn" type="widget" widgetnamespace="mobile" event-prefix="table">
<title>Reflow Table Widget</title>
<desc>Creates a responsive table in reflow mode</desc>
<longdesc>
<p>The reflow table mode works by collapsing the table columns into a stacked presentation that looks like blocks of label/data pairs for each row. Since the HTML source order of a table prohibits styling a table to look like this, the plugin dynamically adds a bit of markup to make the display work (without affecting accessibility). Here is a demo of a basic table using reflow mode:</p>
<iframe src="/resources/table/example1.html" style="width:100%;height:740px;border:0px"></iframe>
<h3>Applying reflow mode to a table</h3>
<p>The reflow responsive table mode is the simplest in terms of markup requirements because it only requires a table with a <code>data-role="table"</code> on the table element. There is no need to set the <code>data-mode</code> attribute since <code>reflow</code> is the default.</p>
<pre><code><![CDATA[
<table data-role="table" id="my-table">
]]></code></pre>
<h3>How reflow mode works</h3>
<p>The plugin works by parsing the values (or <code>abbr title</code>) of the first row of header (<code>th</code>) elements found in the table. For example, in the table above, the third table header is parsed to grab the contents ("Year"):</p>
<pre><code><![CDATA[
<th>Year</th>
]]></code></pre>
<p>The script then appends an element with the table header text <em>before</em> the contents of every cell in that column. For example, for every table cell in the year column:</p>
<pre><code><![CDATA[
<td>1941</td>
]]></code></pre>
<p>An element is added before the text of each cell with a <code>class</code> of <code>ui-table-cell-label</code>:</p>
<pre><code><![CDATA[
<td><b class="ui-table-cell-label">Year</b>1941</td>
]]></code></pre>
<p>With our mobile-first approach, the base styles for a reflow table stacks each row and presents each cell in the label/data style format. This is done by hiding the table header rows, making each table cell <code>display:block</code> so they are stacked. The the label element injected into each cell is styled as <code>display:inline-block</code> with a <code>min-width:30%</code> rule to place the labels on the same line as the content at a consistent width to form a two column presentation.</p>
<p>It is important to note that you are required to wrap your table headers in a <code><thead> ... </thead></code> block, and the table body in a <code><tbody> ... </tbody></code> block, as shown in the <a href="#entry-examples">full demo Example</a>.</p>
<h3>Making the table responsive</h3>
<p>By default, a table with reflow mode will display the stacked presentation style on all screen widths. The styles to make the table responsive are added by applying a media query with rules to switch to the tabular style presentation above a specific screen width.</p>
<p>This is done by wrapping a few simple CSS rules in and a media query that only applies the rules above a certain width breakpoint. The styles make the table header rows visible, display the cells in a tabular format, and hide the generated label elements within each. Here is an example media query that swaps the presentation at 40em (640 pixels): </p>
<pre><code><![CDATA[
@media ( min-width: 40em ) {
/* Show the table header rows and set all cells to display: table-cell */
.my-custom-breakpoint td,
.my-custom-breakpoint th,
.my-custom-breakpoint tbody th,
.my-custom-breakpoint tbody td,
.my-custom-breakpoint thead td,
.my-custom-breakpoint thead th {
display: table-cell;
margin: 0;
}
/* Hide the labels in each cell */
.my-custom-breakpoint td .ui-table-cell-label,
.my-custom-breakpoint th .ui-table-cell-label {
display: none;
}
}
]]></code></pre>
<p>It's best to use a <code>class</code> on the table to apply the breakpoint. Add these rules to your custom stylesheet that is included in the <code>head</code> of the page. We recommend creating a set of custom breakpoint classes that can be used to apply standard table breakpoints in your project.</p>
<p>In the example above, we're assuming there is a class of <code>my-custom-breakpoint</code> added to the table to apply the breakpoint. Each of the rules in the custom media query are scoped against that table class to target only tables that have the <code>my-custom-breakpoint</code> class.</p>
<p>In order for this technique to work, a browser must support media queries and the ability to style table cells as block-level elements. In testing, most popular desktop and mobile browsers meet these criteria, but older versions of Internet Explorer (8 and older) fall back to a normal table presentation. IE 9 can support this technique but there are a few additional styles needed so we recommend applying these in a <code>max-width</code> media query to only apply them below the table presentation because they are hard to negate. </p>
<h3>Choosing a breakpoint</h3>
<p>The goal is to determine the minimum width at which the <em>entire table</em> will fit comfortably within the screen. Find this width by populating a table with realistic sample data, then adjust the browser window until the table completely fits and has a bit of extra space to account for rendering differences across devices. This is the natural place to set the breakpoint that switches between the stacked and tabular presentation modes. </p>
<p>The breakpoint width is highly dependent on the number of columns in the table and content within each cell. On some sites, this may be as low as 30em (480px) and on others, it could be as wide as 100em (1,600px). There is no way for the framework to decide on a "standard breakpoint" that will work for everyone — that's why there isn't a breakpoint built into the table by default.</p>
<p>We recommend writing media query widths are in <code>em</code>'s so they respond to font size changes. To convert a pixel width into <code>em</code>'s, divide the target width by 16 (pixels). Use this value for the <code>min-width</code> value in the media query above.</p>
<h3>Applying a preset breakpoint</h3>
<p>Even though we strongly encourage you to write custom breakpoints yourself, the framework includes a single pre-configured breakpoint that targets the stacked style to smaller phones and swaps to a tabular prsentation on larger phones, tablet and desktop devices. To use this preset breakpoint, add the <code>ui-responsive</code> class to the table to convert from the stacked presentation to a tabular presentation at 560px (35em). If this breakpoint doesn't work for your content, we encourage you to write a custom breakpoint as descibed above.</p>
<pre><code><![CDATA[
<table data-role="table" class="ui-responsive">
]]></code></pre>
<h3>Working with grouped column headers</h3>
<p>It's fairly common to need to logically group multiple columns together under a heading group for financial or scientific data. The framework can support the most simple version of this by allowing for two rows of table headers (<code>TH</code>), with the first row containing simple <code>colspan</code> attributes to group the columns below. In this configuration, the framework will add a class to the label of the first cell in each group to allow you to style these differently and provide aditional visual hierarchy. </p>
</longdesc>
<added>1.3</added>
<options>
<option name="classes.reflowTable" default='"ui-table-reflow"' >
<desc>Class added to the generated label content added to each table cell based on the header name.
<p>Note: The reflow mode has one option, classes, which is only configurable via JavaScript because it expects an object literal value. The classes option has two properties that define the structural classnames that the plugin uses.</p></desc>
<type name="String" />
</option>
<option name="classes.cellLabels" default='"ui-table-cell-label"' >
<desc>Class added to the first cell within each grouped header's column. This makes it easy to style these differently to visually delineate the column groups.
<p>Note: The reflow mode has one option, classes, which is only configurable via JavaScript because it expects an object literal value. The classes option has two properties that define the structural classnames that the plugin uses.</p></desc>
<type name="String" />
</option>
<option name="initSelector" default='":jqmData(role='table')"'>
<desc>This is used to define the selectors (element types, data roles, etc.) that will automatically be initialized as tables. To change which elements are initialized, bind this option to the mobileinit event:
<pre><code><![CDATA[
$( document ).on( "mobileinit", function() {
$.mobile.table.prototype.options.initSelector = ".mytable";
});
]]></code></pre>
</desc>
<type name="CSS selector string" />
</option>
</options>
<events>
<event name="create">
<desc>Since this plugin is written as an extension to the core table plugin, it binds to the tablecreate event but does not issue any additional events.
</desc>
<argument name="event" type="Event">
<desc></desc>
</argument>
<argument name="ui" type="Object">
<desc></desc>
</argument>
</event>
</events>
<methods>
<method name="refresh">
<desc>Updates the labels in the cells.
</desc>
</method>
</methods>
<example>
<height>550</height>
<desc>A basic example of a responsive table in reflow mode.</desc>
<html><![CDATA[
<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="movie-table" data-mode="reflow" class="ui-responsive table-stroke">
<thead>
<tr>
<th data-priority="1">Rank</th>
<th data-priority="persist">Movie Title</th>
<th data-priority="2">Year</th>
<th data-priority="3"><abbr title="Rotten Tomato Rating">Rating</abbr></th>
<th data-priority="4">Reviews</th>
</tr>
</thead>
<tbody>
<tr>
<th>1</th>
<td><a href="http://en.wikipedia.org/wiki/Citizen_Kane" data-rel="external">Citizen Kane</a></td>
<td>1941</td>
<td>100%</td>
<td>74</td>
</tr>
<tr>
<th>2</th>
<td><a href="http://en.wikipedia.org/wiki/Casablanca_(film)" data-rel="external">Casablanca</a></td>
<td>1942</td>
<td>97%</td>
<td>64</td>
</tr>
<tr>
<th>3</th>
<td><a href="http://en.wikipedia.org/wiki/The_Godfather" data-rel="external">The Godfather</a></td>
<td>1972</td>
<td>97%</td>
<td>87</td>
</tr>
<tr>
<th>4</th>
<td><a href="http://en.wikipedia.org/wiki/Gone_with_the_Wind_(film)" data-rel="external">Gone with the Wind</a></td>
<td>1939</td>
<td>96%</td>
<td>87</td>
</tr>
<tr>
<th>5</th>
<td><a href="http://en.wikipedia.org/wiki/Lawrence_of_Arabia_(film)" data-rel="external">Lawrence of Arabia</a></td>
<td>1962</td>
<td>94%</td>
<td>87</td>
</tr>
<tr>
<th>6</th>
<td><a href="http://en.wikipedia.org/wiki/Dr._Strangelove" data-rel="external">Dr. Strangelove Or How I Learned to Stop Worrying and Love the Bomb</a></td>
<td>1964</td>
<td>92%</td>
<td>74</td>
</tr>
<tr>
<th>7</th>
<td><a href="http://en.wikipedia.org/wiki/The_Graduate" data-rel="external">The Graduate</a></td>
<td>1967</td>
<td>91%</td>
<td>122</td>
</tr>
<tr>
<th>8</th>
<td><a href="http://en.wikipedia.org/wiki/The_Wizard_of_Oz_(1939_film)" data-rel="external">The Wizard of Oz</a></td>
<td>1939</td>
<td>90%</td>
<td>72</td>
</tr>
<tr>
<th>9</th>
<td><a href="http://en.wikipedia.org/wiki/Singin%27_in_the_Rain" data-rel="external">Singin' in the Rain</a></td>
<td>1952</td>
<td>89%</td>
<td>85</td>
</tr>
<tr>
<th>10</th>
<td class="title"><a href="http://en.wikipedia.org/wiki/Inception" data-rel="external">Inception</a></td>
<td>2010</td>
<td>84%</td>
<td>78</td>
</tr>
</tbody>
</table>
</div>
</div>
]]></html>
</example>
<category slug="widgets"/>
</entry>