| Rank | From 50721dab4eb863ebaf52fb99c0eeb4514fe5cacd Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof
|---|
The column chooser mode requires a table element with two attributes: data-role="table" and data-mode="columntoggle". An ID attribute is also required on the table to associate it with the column chooser popup menu.
The column chooser mode requires a table element with two attributes: data-role="table" and data-mode="columntoggle". An id attribute is also required on the table to associate it with the column chooser popup menu and the button that launches the popup. The table's id attribute will serve as the prefix for the button's attribute (which will append -button to the previx) nad the popup's attribute (which will append -popup to the prefix).
-
+
+ Re-process the entire table to ensure it is displayed correctly.
+ Note:This method is deprecated as of 1.5.0. Use the refresh() method instead.
+
+
+
+ 1.5.0
Re-process the entire table to ensure it is displayed correctly.
From 8ee9cc7230754e4f07ade2cfc8067fb6a3a23ca8 Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof
Date: Mon, 12 May 2014 14:58:15 +0300
Subject: [PATCH 03/12] Table: Consolidating extension into a single entry
---
entries/table-columntoggle.xml | 351 ------------------------------
entries/table-reflow.xml | 228 --------------------
entries/table.xml | 383 +++++++++++++++++++++++++++++----
3 files changed, 347 insertions(+), 615 deletions(-)
delete mode 100644 entries/table-columntoggle.xml
delete mode 100644 entries/table-reflow.xml
diff --git a/entries/table-columntoggle.xml b/entries/table-columntoggle.xml
deleted file mode 100644
index 8f2ca3aa..00000000
--- a/entries/table-columntoggle.xml
+++ /dev/null
@@ -1,351 +0,0 @@
-
-
-
- Column-Toggle Table Widget
- Creates a responsive table in column toggle mode
-
- This table mode automatically hides less important columns at narrower widths and surfaces a button to open a menu that allows the user to choose what columns they want to see. In this mode, the author attempts to define which columns are most important to show across various widths by assigning a priority to each column.
-
- A user may choose to check as many columns as they want by tapping the "Columns..." button to open the column
- chooser popup. The popup contains a dynamically generated list of columns based on the table markup that can be checked and unchecked to adjust the visible columns.
-
-
- Applying column chooser mode to a table
-
- The column chooser mode requires a table element with two attributes: data-role="table" and data-mode="columntoggle". An id attribute is also required on the table to associate it with the column chooser popup menu and the button that launches the popup. The table's id attribute will serve as the prefix for the button's attribute (which will append -button to the previx) nad the popup's attribute (which will append -popup to the prefix).
-
-
-
- How column toggle mode works
-
- The plugin automates a few key things: it injects the column chooser button, and generates the popup with check list of columns that can be hidden or shown by the user. The list of columns in the chooser menu is populated by parsing the values (or abbr title) of the first row of header (TH) elements. Only headers that have a data-priority attribute are included in the column chooser; headers without this attribute won't made available in the chooser to allow developers to identify critical columns that shouldn't be hidden. If columns are hidden via responsive media queries, these will be unchecked in the chooser to reflect the current column visibility.
-
- The automatic column hiding behavior is accomplished by CSS media queries that hide or show columns based on priority levels at various screen widths. Since each site will have different content and column configurations, we provide a simple media query block that you can copy, paste and customize for each project. This is explained in detail below.
-
- The priorities assigned to headers and media queries used to hide columns act as a sensible default for showing the most important columns that will fit on a device. The column chooser menu gives users the ability to override these defaults and choose which columns they want to see. These user preferences take precedence over the priority mappings so if a column is manually checked, it will remain visible across all screen widths until the page is refreshed.
-
- Because of the flexibility this plugin provides, it's possible for users to introduce horizontal scrolling if the data in each column is long or if many columns are selected to be shown on a smaller screen.
-
- Setting column priority
-
- The table works by hiding and showing columns based on two inputs: available screen width or by the user checking and unchecking which columns to display in a column picker popup. Add data-priority attributes to each of the table headers of columns you want to responsively display and assign a priority (1 = highest, 6 = lowest). Any table header given a priority will be available in the column picker menu.
- To make a column persistent so it's not available for hiding, omit the data-priority attribute. This will make the column visible at all widths and won't be available in the column chooser menu.
-
-
-
- Behind the scenes, the plugin will apply classes to each cell that map to the priority set in the data attribute on the header. For example, if a table heading has a data-priority="3" attribute, every cell in that column will assigned a ui-table-priority-3 class once enhanced. These classes are then used in media queries to hide and show columns based on screen width (see below).
-
-
-
- You may use any priority naming convention and assign as many (or few) levels of priority for the columns. The plugin simply generates class names based on the values in the data-priority attribute so even though we default to using a numeric system of 1-6, any naming convention is possible.
-
- For example, if a priority of data-priority="critical" is added to the heading, a class of ui-table-priority-critial will be applied to each cell in that column. If a priority is assigned, the column will be made available for the toggling in the column menu and adds the classes to each cell, the rest of the styling and media query creation is up to you write in your custom stylesheet.
-
- It is important to note that you are required to wrap your table headers in a <thead> ... </thead> block, and the table body in a <tbody> ... </tbody> block, as shown in the full demo Example.
-
- Making the table responsive
-
- The styles for the all priority columns (1-6) start as display:none in the structure stylesheet since we're taking a mobile-first approach to our styles. This means that only columns that should be persistent are visible in the styles to start.
-
- The framework does not automatically include the the media queries to progressively display columns at wider widths. We do this to make it easier for developers to customize the media query widths for each priority level.
-
- Media queries add the responsive behavior to show and hide columns by priority. Each media query is written using min-width widths so they build on top of each other. The widths are set in ems so they respond to font size changes. To calculate a pixel withs in em's, divide the target width by 16 (pixels) - it's that easy.
-
- Inside each media query, we override the display:none style properties set on all the priority columns in the basic styles to display:table-cell so they become visible again and act as a table.
-
- To customize the breakpoints, copy the following style block into your custom style overrides and adjust the min-width media query values for each priority level to specify where various priority columns should appear.
-
- In the example styles below for a my-custom-class class on the table, the priority 1 columns are shown first, at widths above 20em (320px), then priority 2 kicks in above 30em (480px) and so on up to wide desktop widths with priority 6. Feel free to change these breakpoints in your stylesheet and choose how many priority levels you'd like to use.
-
-
-Due to CSS specificity, you will also need to include the class definitions for the hidden and visible states after the custom breakpoints in your custom stylesheet so be sure to include these as well:
-
-
- Applying a preset breakpoint
-
- Even though we strongly encourage you to write custom breakpoints yourself, the framework includes a set of pre-configured breakpoints for each of the six priority levels that you can use if they happen work well for your content.
-
- These breakpoints can applied by adding a class="ui-responsive" to the table element. Here is an example of a table with this class added:
-
-
-
- The six preset breakpoints classes included in the column toggle stylesheet use regular increments of 10em (160 pixels). Here is a summary of the breakpoints assigned to each priority in the preset styles:
-
-
- data-priority="1"- Displays the column at 320px (20em)
- data-priority="2"- Displays the column at 480px (30em)
- data-priority="3"- Displays the column at 640px (40em)
- data-priority="4"- Displays the column at 800px (50em)
- data-priority="5"- Displays the column at 960px (60em)
- data-priority="6"- Displays the column at 1,120px (70em)
-
-
- If these preset breakpoints don't work for your content and layout needs, we recommend that you create custom breakpoints to fine tune the styles.
-
- Working with the column menu classes
-
- When the column chooser menu opens, the column checkboxes will be checked or unchecked based on the visibility of each column based on the media queries so it accurately reflects what is being seen. These media queries to hide or show columns act as sensible defaults for what columns should be shown based on the developer's understanding of the column importance and data values. The chooser menu allows the user to have control of the table presentation so this takes precedence over the default display.
-
- If an unchecked column checkbox is checked by the user, they now take control of the column. Until the page is refreshed, the visibility of that column will now always be visible, even if the screen is re-sized. Behind the scenes, a class of ui-table-cell-visible is added to all the cells in that column to ensure they override any visibility set via media queries.
-
- The same idea applies when a column is unchecked: from then on, the column won't be seen at any width because the class of ui-table-cell-hidden is added to each of the cells in that column.
-
- Styling the button and column chooser popup
-
- The column chooser popup is opened via a button that is generated by the framework. The button's text is "Columns..." by default but can be set by adding the data-column-btn-text attribute to the table to the text string you want in the button. The button will inherit the theme from the content area, just like all buttons, but the theme can be set manually by adding the data-column-btn-theme attribute to any swatch letter in your theme.
-
- This button is injected directly before the table element and has basic styles to align it to the right but you may want to further customize the appearance of this button. To style all these buttons across your site, key off the ui-table-columntoggle-btn structural class on this link.
-
- To target styles against only a specific button, use the unique href value that is generated to target a specific column chooser button. For example, a table with an ID of movie-table will generate a popup with an ID of movie-table-popup so a CSS selector of a[href="#movie-table-popup"] will target only the column popup button for this specific table.
-
- The theme for the column chooser popup can be set by adding the data-column-popup-theme attribute to the table and specifying any swatch letter in your theme. For custom styles or scripting, all the column chooser popups can be targeted by using the ui-table-columntoggle-popup structural class added to these popups. To customize a single popup, use the generated ID based on the table ID that added to each specific popup (such as #movie-table-popup) to target a specific popup.
-
- Working with grouped column headers
-
- 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 (TH), with the first row containing simple colspan attributes to group the columns below. In this configuration, the framework will parse the first row only for the priority and expose these heading groups as the options in the column chooser popup. In this configuration, the second heading will not be exposed as columns that can be hidden or shown independently of the groupings in the chooser.
-
- The columntoggle table places an anchor before the table that invokes a popup listing the columns available for showing/hiding. The ID of the popup and thus the href of the anchor should be the ID of the table suffixed by the string -popup. The anchor must also have an id attribute which is identical to that of the table, but postfixed with -button. This will allow the table to correctly enable/disable when you modify its disabled option. You may separately pre-enhance the popup widget, or you may allow autoinitialization to enhance it.
- The popup widget must contain a single controlgroup widget which in turn contains all the checkboxes representing the columns of the table.
- In the example below the parameter data-column-btn-theme="b" is added to the table explicitly to indicate that the theme applied to the "Columns..." button is not the default (null).
-
-
-
-
-
- 1.3
-
-
-
-
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
-
-
-
-
- Updates the labels in the cells.
-
-
-
-
- 550
- A basic example of a responsive table in column toggle mode.
-
-
-
diff --git a/entries/table-reflow.xml b/entries/table-reflow.xml
deleted file mode 100644
index e0b348af..00000000
--- a/entries/table-reflow.xml
+++ /dev/null
@@ -1,228 +0,0 @@
-
-
-
- Reflow Table Widget
- Creates a responsive table in reflow mode
-
- 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:
-
-
- Applying reflow mode to a table
-
- The reflow responsive table mode is the simplest in terms of markup requirements because it only requires a table with a data-role="table" on the table element. There is no need to set the data-mode attribute since reflow is the default.
-
-
-
- How reflow mode works
-
- The plugin works by parsing the values (or abbr title) of the first row of header (th) elements found in the table. For example, in the table above, the third table header is parsed to grab the contents ("Year"):
-
-
-
- The script then appends an element with the table header text before the contents of every cell in that column. For example, for every table cell in the year column:
-
-
-
- An element is added before the text of each cell with a class of ui-table-cell-label:
-
-
- 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 display:block so they are stacked. The the label element injected into each cell is styled as display:inline-block with a min-width:30% rule to place the labels on the same line as the content at a consistent width to form a two column presentation.
-
- It is important to note that you are required to wrap your table headers in a <thead> ... </thead> block, and the table body in a <tbody> ... </tbody> block, as shown in the full demo Example.
-
- Making the table responsive
-
- 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.
- 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):
-
-
-
- It's best to use a class on the table to apply the breakpoint. Add these rules to your custom stylesheet that is included in the head of the page. We recommend creating a set of custom breakpoint classes that can be used to apply standard table breakpoints in your project.
-
- In the example above, we're assuming there is a class of my-custom-breakpoint 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 my-custom-breakpoint class.
-
- 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 max-width media query to only apply them below the table presentation because they are hard to negate.
-
- Choosing a breakpoint
- The goal is to determine the minimum width at which the entire table 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.
- 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.
- We recommend writing media query widths are in em's so they respond to font size changes. To convert a pixel width into em's, divide the target width by 16 (pixels). Use this value for the min-width value in the media query above.
-
- Applying a preset breakpoint
- 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 ui-responsive 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.
-
-
-
- Working with grouped column headers
-
- 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 (TH), with the first row containing simple colspan 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.
-
-
- 1.3
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
-
-
-
-
- Updates the labels in the cells.
-
-
-
-
- 550
- A basic example of a responsive table in reflow mode.
-
-
-
diff --git a/entries/table.xml b/entries/table.xml
index fdcdbd80..2779b9fc 100644
--- a/entries/table.xml
+++ b/entries/table.xml
@@ -5,13 +5,13 @@
Creates a responsive table
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.
+ 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, so 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.
+ 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.
+ 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.
+ 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. It merely adds the 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 add the additional behaviors making 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
@@ -20,61 +20,372 @@
- 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:
+ 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
+ - Add
thead and tbody elements
- 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.
+ - The default table mode is
reflow, so add data-mode="columntoggle" to change modes
+ - The first row of the table must contain the table headers, so 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 an 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.
+ 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 in, 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.
+ The theme CSS contains a preset style for row strokes and alternating row stripes which can be applied by adding the 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.
+ 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 showing you how to apply these styles with custom CSS.
-
+ Reflow Table
+
+ 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:
+
+
+ Applying reflow mode to a table
+
+ The reflow responsive table mode is the simplest in terms of markup requirements because it only requires a table with a data-role="table" on the table element. There is no need to set the data-mode attribute since reflow is the default.
+
+
+
+ How reflow mode works
+
+ The plugin works by parsing the values (or abbr title) of the first row of header (th) elements found in the table. For example, in the table above, the third table header is parsed to grab the contents ("Year"):
+
+
+
+ The script then appends an element with the table header text before the contents of every cell in that column. For example, for every table cell in the year column:
+
+
+
+ an element is added before the text of each cell with a class of ui-table-cell-label:
+
+
+ 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 display:block so they are stacked. The label element injected into each cell is styled as display:inline-block with a min-width:30% rule to place the labels on the same line as the content at a consistent width to form a two column presentation.
+
+ It is important to note that you are required to wrap your table headers in a <thead> ... </thead> block, and the table body in a <tbody> ... </tbody> block, as shown in the full demo example.
+
+ Making the table responsive
+
+ 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.
+ 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):
+
+
+
+ It's best to use a class on the table to apply the breakpoint. Add these rules to your custom stylesheet that is included in the head of the page. We recommend creating a set of custom breakpoint classes that can be used to apply standard table breakpoints in your project.
+
+ In the example above, we're assuming there is a class of my-custom-breakpoint added to the table to apply the breakpoint. Each of the rules in the custom media query is scoped against that table class to target only tables that have the my-custom-breakpoint class.
+
+ 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 max-width media query to only apply them below the table presentation because they are hard to negate.
+
+ Choosing a breakpoint
+ The goal is to determine the minimum width at which the entire table 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.
+ 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 narrow 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.
+ We recommend writing media query widths in ems so they respond to font size changes. To convert a pixel width into ems, divide the target width by 16 (pixels). Use this value for the min-width value in the media query above.
+
+ Applying a preset breakpoint
+ 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 ui-responsive 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.
+
+
+
+ Working with grouped column headers
+
+ 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 (TH), with the first row containing simple colspan 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.
+
+ Column-toggle table
+
+ This table mode automatically hides less important columns at narrower widths and surfaces a button to open a menu that allows the user to choose what columns they want to see. In this mode, the author attempts to define which columns are most important to show across various widths by assigning a priority to each column.
+
+ A user may choose to check as many columns as they want by tapping the "Columns..." button to open the column chooser popup. The popup contains a dynamically generated list of columns based on the table markup that can be checked and unchecked to adjust the visible columns.
+
+
+ Applying column chooser mode to a table
+
+ The column chooser mode requires a table element with two attributes: data-role="table" and data-mode="columntoggle". An id attribute is also required on the table to associate it with the column chooser popup menu and the button that launches the popup. The table's id attribute will serve as the prefix for the button's attribute (which will append -button to the previx) nad the popup's attribute (which will append -popup to the prefix).
+
+
+
+ How column toggle mode works
+
+ The plugin automates a few key things: it injects the column chooser button, and generates the popup with the check list of columns that can be hidden or shown by the user. The list of columns in the chooser menu is populated by parsing the values (or abbr title) of the first row of header (TH) elements. Only headers that have a data-priority attribute are included in the column chooser; headers without this attribute won't be made available in the chooser to allow developers to identify critical columns that shouldn't be hidden. If columns are hidden via responsive media queries, these will be unchecked in the chooser to reflect the current column visibility.
+
+ The automatic column hiding behavior is accomplished by CSS media queries that hide or show columns based on priority levels at various screen widths. Since each site will have different content and column configurations, we provide a simple media query block that you can copy, paste and customize for each project. This is explained in detail below.
+
+ The priorities assigned to headers and media queries used to hide columns act as a sensible default for showing the most important columns that will fit on a device. The column chooser menu gives users the ability to override these defaults and choose which columns they want to see. These user preferences take precedence over the priority mappings so if a column is manually checked, it will remain visible across all screen widths until the page is refreshed.
+
+ Because of the flexibility this plugin provides, it's possible for users to introduce horizontal scrolling if the data in each column is long or if many columns are selected to be shown on a smaller screen.
+
+ Setting column priority
+
+ The table works by hiding and showing columns based on two inputs: available screen width or by the user checking and unchecking which columns to display in a column picker popup. Add data-priority attributes to each of the table headers of columns you want to responsively display and assign a priority (1 = highest, 6 = lowest). Any table header given a priority will be available in the column picker menu.
+ To make a column persistent so it's not available for hiding, omit the data-priority attribute. This will make the column visible at all widths and won't be available in the column chooser menu.
+
+
+
+ Behind the scenes, the plugin will apply classes to each cell that map to the priority set in the data attribute on the header. For example, if a table heading has a data-priority="3" attribute, every cell in that column will assigned a ui-table-priority-3 class once enhanced. These classes are then used in media queries to hide and show columns based on screen width (see below).
+
+
+
+ You may use any priority naming convention and assign as many (or few) levels of priority for the columns. The plugin simply generates class names based on the values in the data-priority attribute so even though we default to using a numeric system of 1-6, any naming convention is possible.
+
+ For example, if a priority of data-priority="critical" is added to the heading, a class of ui-table-priority-critial will be applied to each cell in that column. If a priority is assigned, the column will be made available for the toggling in the column menu and adds the classes to each cell, the rest of the styling and media query creation is up to you write in your custom stylesheet.
+
+ It is important to note that you are required to wrap your table headers in a <thead> ... </thead> block, and the table body in a <tbody> ... </tbody> block, as shown in the full demo Example.
+
+ Making the table responsive
+
+ The styles for the all priority columns (1-6) start as display:none in the structure stylesheet since we're taking a mobile-first approach to our styles. This means that only columns that should be persistent are visible in the styles to start.
+
+ The framework does not automatically include the the media queries to progressively display columns at wider widths. We do this to make it easier for developers to customize the media query widths for each priority level.
+
+ Media queries add the responsive behavior to show and hide columns by priority. Each media query is written using min-width widths so they build on top of each other. The widths are set in ems so they respond to font size changes. To calculate a pixel withs in em's, divide the target width by 16 (pixels) - it's that easy.
+
+ Inside each media query, we override the display:none style properties set on all the priority columns in the basic styles to display:table-cell so they become visible again and act as a table.
+
+ To customize the breakpoints, copy the following style block into your custom style overrides and adjust the min-width media query values for each priority level to specify where various priority columns should appear.
+
+ In the example styles below for a my-custom-class class on the table, the priority 1 columns are shown first, at widths above 20em (320px), then priority 2 kicks in above 30em (480px) and so on up to wide desktop widths with priority 6. Feel free to change these breakpoints in your stylesheet and choose how many priority levels you'd like to use.
+
+
+Due to CSS specificity, you will also need to include the class definitions for the hidden and visible states after the custom breakpoints in your custom stylesheet so be sure to include these as well:
+
+
+ Applying a preset breakpoint
+
+ Even though we strongly encourage you to write custom breakpoints yourself, the framework includes a set of pre-configured breakpoints for each of the six priority levels that you can use if they happen work well for your content.
+
+ These breakpoints can applied by adding a class="ui-responsive" to the table element. Here is an example of a table with this class added:
+
+
+
+ The six preset breakpoints classes included in the column toggle stylesheet use regular increments of 10em (160 pixels). Here is a summary of the breakpoints assigned to each priority in the preset styles:
+
+
+ data-priority="1"- Displays the column at 320px (20em)
+ data-priority="2"- Displays the column at 480px (30em)
+ data-priority="3"- Displays the column at 640px (40em)
+ data-priority="4"- Displays the column at 800px (50em)
+ data-priority="5"- Displays the column at 960px (60em)
+ data-priority="6"- Displays the column at 1,120px (70em)
+
+
+ If these preset breakpoints don't work for your content and layout needs, we recommend that you create custom breakpoints to fine tune the styles.
+
+ Working with the column menu classes
+
+ When the column chooser menu opens, the column checkboxes will be checked or unchecked based on the visibility of each column based on the media queries so it accurately reflects what is being seen. These media queries to hide or show columns act as sensible defaults for what columns should be shown based on the developer's understanding of the column importance and data values. The chooser menu allows the user to have control of the table presentation so this takes precedence over the default display.
+
+ If an unchecked column checkbox is checked by the user, they now take control of the column. Until the page is refreshed, the visibility of that column will now always be visible, even if the screen is re-sized. Behind the scenes, a class of ui-table-cell-visible is added to all the cells in that column to ensure they override any visibility set via media queries.
+
+ The same idea applies when a column is unchecked: from then on, the column won't be seen at any width because the class of ui-table-cell-hidden is added to each of the cells in that column.
+
+ Styling the button and column chooser popup
+
+ The column chooser popup is opened via a button that is generated by the framework. The button's text is "Columns..." by default but can be set by adding the data-column-btn-text attribute to the table to the text string you want in the button. The button will inherit the theme from the content area, just like all buttons, but the theme can be set manually by adding the data-column-btn-theme attribute to any swatch letter in your theme.
+
+ This button is injected directly before the table element and has basic styles to align it to the right but you may want to further customize the appearance of this button. To style all these buttons across your site, key off the ui-table-columntoggle-btn structural class on this link.
+
+ To target styles against only a specific button, use the unique href value that is generated to target a specific column chooser button. For example, a table with an ID of movie-table will generate a popup with an ID of movie-table-popup so a CSS selector of a[href="#movie-table-popup"] will target only the column popup button for this specific table.
+
+ The theme for the column chooser popup can be set by adding the data-column-popup-theme attribute to the table and specifying any swatch letter in your theme. For custom styles or scripting, all the column chooser popups can be targeted by using the ui-table-columntoggle-popup structural class added to these popups. To customize a single popup, use the generated ID based on the table ID that added to each specific popup (such as #movie-table-popup) to target a specific popup.
+
+ Working with grouped column headers
+
+ 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 (TH), with the first row containing simple colspan attributes to group the columns below. In this configuration, the framework will parse the first row only for the priority and expose these heading groups as the options in the column chooser popup. In this configuration, the second heading will not be exposed as columns that can be hidden or shown independently of the groupings in the chooser.
+
+ The columntoggle table places an anchor before the table that invokes a popup listing the columns available for showing/hiding. The ID of the popup and thus the href of the anchor should be the ID of the table suffixed by the string -popup. The anchor must also have an id attribute which is identical to that of the table, but postfixed with -button. This will allow the table to correctly enable/disable when you modify its disabled option. You may separately pre-enhance the popup widget, or you may allow autoinitialization to enhance it.
+ The popup widget must contain a single controlgroup widget which in turn contains all the checkboxes representing the columns of the table.
+ In the example below the parameter data-column-btn-theme="b" is added to the table explicitly to indicate that the theme applied to the "Columns..." button is not the default (null).
+
+
+
+
1.3
-
+
+
+
From 0fc93fce9316bb1f83ecf55e372a053ad15588d5 Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof
Date: Mon, 12 May 2014 15:22:08 +0300
Subject: [PATCH 04/12] Table: Make example responsive
---
entries/table.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/entries/table.xml b/entries/table.xml
index 2779b9fc..e3ed6140 100644
--- a/entries/table.xml
+++ b/entries/table.xml
@@ -419,7 +419,7 @@
jQuery Mobile Example
-
+
Rank
From 50721dab4eb863ebaf52fb99c0eeb4514fe5cacd Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof
Date: Tue, 13 May 2014 00:59:34 +0300
Subject: [PATCH 05/12] Table: Add option "enhanced"
---
entries/table.xml | 1 +
1 file changed, 1 insertion(+)
diff --git a/entries/table.xml b/entries/table.xml
index e3ed6140..24e13f88 100644
--- a/entries/table.xml
+++ b/entries/table.xml
@@ -373,6 +373,7 @@