Tables
Design
Tables are used to display and sort large sets of information. Design rules:
- Use sortable tables by default (ie. if no other instruction received, make them sortable)
- Avoid 'stacking' multiple lines of content in table cells, instead push pieces of content out to their own columns.
- disabled table rows to be coloured fuchsia and must always include a "disabled" icon
- additional controls may be included: checkbox for toggling column, icons (or icon buttons) to launch dropdowns
- by default, the alignment of text in TH and TD cells should match
Code
API: stable
Tables must follow correct semantic structure in order to function:
- You must use
thfor header cells - You must use
thead,tbodyandtfootas appropriate - Do not nest tables
There are two table types:
- Default
- With Controls (
with-controls)
Basic table
| ID | Species | Location | Description |
|---|---|---|---|
| 1 | Glaucous Macaw | South America | 70 cm (27.5 in) long, mostly pale turquoise-blue with a large greyish head. It has a long tail and a large bill. It has a yellow, bare eye-ring and half-moon-shaped lappets bordering the mandible.[3] |
| 2 | Hyacinth Macaw | South America | 100 cm (39 in) long, 120-140 cm (48-56 in) wingspan. It is almost entirely blue and has black under the wings. It has a large black beak with bright yellow along the sides of the lower part of the beak and also yellow eyerings.[4] |
| 3 | Lear's Macaw | Brazil | 70 cm (27.5 in) long, mainly blue and the head is a slightly paler blue. It has bare pale yellow skin at the base of its beak and orange-yellow eyerings. It has a large blackish beak.[5] |
<div class="ace-table-scroll-container">
<div class="ace-table-container">
<table class="ace-table">
<thead>
<tr>
<th>ID
</th>
<th>Species
</th>
<th>Location
</th>
<th>Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>1
</td>
<td>Glaucous Macaw
</td>
<td>South America
</td>
<td>70 cm (27.5 in) long, mostly pale turquoise-blue with a large greyish head. It has a long tail and a large bill. It has a yellow, bare eye-ring and half-moon-shaped lappets bordering the mandible.
</td>
</tr>
<tr>
<td>2
</td>
<td>Hyacinth Macaw
</td>
<td>South America
</td>
<td>100 cm (39 in) long, 120-140 cm (48-56 in) wingspan. It is almost entirely blue and has black under the wings. It has a large black beak with bright yellow along the sides of the lower part of the beak and also yellow eyerings.
</td>
</tr>
<tr>
<td>3
</td>
<td>
Lear's Macaw
</td>
<td>Brazil
</td>
<td>70 cm (27.5 in) long, mainly blue and the head is a slightly paler blue. It has bare pale yellow skin at the base of its beak and orange-yellow eyerings. It has a large blackish beak.
</td>
</tr>
</tbody>
</table>
</div>
</div>
<% ace.Table(Array())
ace.TableThead(Array())
ace.TableTr(Array())
ace.TableTh(Array()) %>
ID
<% ace.TableThEnd
ace.TableTh(Array()) %>
Species
<% ace.TableThEnd
ace.TableTh(Array()) %>
Location
<% ace.TableThEnd
ace.TableTh(Array()) %>
Description
<% ace.TableThEnd
ace.TableTrEnd
ace.TableTheadEnd
ace.TableTbody(Array())
ace.TableTr(Array())
ace.TableTd(Array()) %>
Glaucous Macaw
<% ace.TableTdEnd
ace.TableTd(Array()) %>
South America
<% ace.TableTdEnd
ace.TableTd(Array()) %>
70 cm (27.5 in) long, mostly pale turquoise-blue with a large greyish head. It has a long tail and a large bill. It has a yellow, bare eye-ring and half-moon-shaped lappets bordering the mandible.
<% ace.TableTdEnd
ace.TableTrEnd
ace.TableTr(Array())
ace.TableTd(Array()) %>
Hyacinth Macaw
<% ace.TableTdEnd
ace.TableTd(Array()) %>
South America
<% ace.TableTdEnd
ace.TableTd(Array()) %>
100 cm (39 in) long, 120-140 cm (48-56 in) wingspan. It is almost entirely blue and has black under the wings. It has a large black beak with bright yellow along the sides of the lower part of the beak and also yellow eyerings.
<% ace.TableTdEnd
ace.TableTrEnd
ace.TableTr(Array())
ace.TableTd(Array()) %>
Lear's Macaw
<% ace.TableTdEnd
ace.TableTd(Array()) %>
Brazil
<% ace.TableTdEnd
ace.TableTd(Array()) %>
70 cm (27.5 in) long, mainly blue and the head is a slightly paler blue. It has bare pale yellow skin at the base of its beak and orange-yellow eyerings. It has a large blackish beak.
<% ace.TableTdEnd
ace.TableTrEnd
ace.TableTbodyEnd
ace.TableEnd %>
ASP Attributes
| Element | Name | Use | Description |
|---|---|---|---|
| ace.Table | sortable | boolean | Makes the table sortable |
| ace.Table | type | string | Sets type of table |
| ace.Table | caption | string | Adds a caption |
| ace.Table | customclass | string | Adds a custom class |
Disabled table rows
Rows can be set to disabled style by adding the class ace-table-disabled to the tr element. Note that all controls within the row must be disabled elsewhere in your code, the class simply sets the style.
<tr class="ace-table-disabled">
<td>Content
</td>
<td><span class="ace-icon ace-icon-status-disabled">Actions Disabled</span>
</td>
</tr>Highlighted table rows
Rows can be statically highlighted by adding the class ace-table-highlighted to the tr element.
<tr class="ace-table-highlighted">
<td>Content
</td>
<td><span class="ace-icon ace-icon-status-caution">Really important stuff</span>
</td>
</tr>Inline Controls
| ID | Species | Location | Actions |
|---|---|---|---|
| 1 | Great Green Macaw | Central and South America | |
| 2 | Blue-and-yellow Macaw | Panama | |
| 3 | Green-winged Macaw | South America | |
| 4 | Blue-throated Macaw | North Bolivia | |
| 5 | Scarlet Macaw | Mexico | |
| 6 | James Brown | Portland | |
| 7 | Sam Morison | Oakville |
Code
<div class="ace-table-scroll-container">
<div class="ace-table-container">
<table class="ace-table ace-table-with-controls">
<thead>
<tr>
<th>ID
</th>
<th>Species
</th>
<th>Location
</th>
<th>Actions
</th>
</tr>
</thead>
<tbody>
<tr>
<td>1
</td>
<td>Great Green Macaw
</td>
<td>Central and South America
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr>
<td>2
</td>
<td>Blue-and-yellow Macaw
</td>
<td>Panama
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr>
<td>3
</td>
<td>Green-winged Macaw
</td>
<td>South America
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr class="ace-table-highlighted">
<td>4
</td>
<td>Blue-throated Macaw
</td>
<td>North Bolivia
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr class="ace-table-disabled">
<td>5
</td>
<td>Scarlet Macaw
</td>
<td>Mexico
</td>
<td><span class="ace-icon ace-icon-status-disabled">Actions Disabled</span>
</td>
</tr>
<tr class="ace-table-disabled">
<td>6
</td>
<td>James Brown
</td>
<td>Portland
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr class="ace-table-disabled">
<td>7
</td>
<td>Sam Morison
</td>
<td>Oakville
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" disabled="true"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
</tbody>
</table>
</div>
</div>The dropdown markup is referenced in the hidden div at the end of the page.
<!--DO NOT USE THIS CODE. Copy the code from the Code example in the table.
-->
<div class="ace-table-container">
<div id="table-actions-menu-trigger" class="ace-dropdown">
<div id="table-actions-menu-trigger-content" style="display:block; position:initial;" class="ace-dropdown-content">
<div class="ace-dropdown-content-group">
<ul class="ace-dropdown-menu">
<li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-add-generic"></span> Add</a></li>
<li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-remove"></span> Remove</a></li>
<li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-edit"></span> Edit</a></li>
</ul>
</div>
<div class="ace-dropdown-content-group">
<ul class="ace-dropdown-menu">
<li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-download"></span> Download</a></li>
</ul>
</div>
<div class="ace-dropdown-content-group">12Mb Acrobat PDF
</div>
</div>
</div>
</div>Scrolling
Scrolling is enabled by default. Omitting the .ace-table-scroll-container wrapper will disable scrolling.
The scrollable attribute in templates controls this wrapper.
Sorting
ACE can automatically add sortable table functionality. Simply add data-ace-sortable="true" to the table element.
| ID | Species | Location | Actions |
|---|---|---|---|
| 1 | Great Green Macaw | Central and South America | |
| 2 | Blue-and-yellow Macaw | Panama | |
| 3 | Green-winged Macaw | South America | |
| 4 | Blue-throated Macaw | North Bolivia | |
| 5 | Scarlet Macaw | Mexico |
Code
<div class="ace-table-scroll-container">
<div class="ace-table-container">
<table class="ace-table ace-table-with-controls" data-ace-sortable="true">
<thead>
<tr>
<th>ID
</th>
<th>Species
</th>
<th>Location
</th>
<th>Actions
</th>
</tr>
</thead>
<tbody>
<tr>
<td>1
</td>
<td>Great Green Macaw
</td>
<td>Central and South America
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr>
<td>2
</td>
<td>Blue-and-yellow Macaw
</td>
<td>Panama
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr>
<td>3
</td>
<td>Green-winged Macaw
</td>
<td>South America
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr>
<td>4
</td>
<td>Blue-throated Macaw
</td>
<td>North Bolivia
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
<tr>
<td>5
</td>
<td>Scarlet Macaw
</td>
<td>Mexico
</td>
<td>
<button type="button" class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>
</td>
</tr>
</tbody>
</table>
</div>
</div>Prevent sorting
To prevent a column being sortable, add the attribute data-ace-sortable="false" to the th element.
Sortable options
The sorter has some automatic behaviour depending on the content of the table cells.
- The data being sorted can be optionally controlled using the
data-ace-valueattribute. If this attribute exists, its value will be used rather than the content of the table cell. - The sort function can be optionally controlled using the
data-ace-sort-typeattribute. It must be one ofalpha, numeric, date. This attribute is useful when you have user-defined table content that might mistakenly cause your tables to sort unpredictably. eg. a user enters a date for their security group name. - The sorter attempts to coerce the value into one of the following types. If successful, that resulting value will be used as the basis for sorting.
- A number as defined by any float or integer value, eg
28,28.5. - A number with a currency preceding it, eg
$21.50. - A number with a percentage following it, eg
57.3%. - A date in the format specified by ECMA5 15.9.1.15, eg
YYYY-MM-DDTHH:mm:ss.sssZor a valid simplification of that; such asYYYY-MM-DD.
- A number as defined by any float or integer value, eg
- All numeric types default to a descending sort, meaning
5will appear before4
Custom sortable table
In some scenarios, tables are sorted either server-side or with a custom Javascript solution. To access the ACE sortable table styles without invoking the Javascript:
- Add the class
ace-table-customsortto thetable.ace-tableelement. - When the column is sorted in ascending order, add the attribute
data-ace-sorted-direction="ascending"to the appropriatethelement. - When the column is sorted in descending order, add the attribute
data-ace-sorted-direction="descending"to the appropriatethelement.
Note that while the current version of ACE does not provide different styles for ascending and descending states, you must implement those states to make your custom solution more future-robust.
Table cell types
Some content requires alternative treatment or styling. To enable that, table cells can be set to a content type:
icon- icon-only cellsnumber- cells containing just a numberdate- any date formatform- form inputscontrol- controls, usually buttonscheckbox- for checkbox inputsemail- email addressuser- information about a single useruser-group- information about a user group
To set a content type, apply the class to both the TH and TD elements. In the templates, set the type in the template call.
Examples:
| Default (text) | Icons | Default (text) | Numbers | Dates | Default (text) | Numbers | Checkboxes | Numbers | Numbers | Default (text) | Checkboxes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Sentio aliquos togatos contra me conspirare. | Sentio aliquos togatos contra me conspirare. | 100 | 2015-02-01 | Sentio aliquos togatos contra me conspirare. | 200 |
|
400 | 400% | Sentio aliquos togatos contra me conspirare. |
|
|
| Sentio aliquos togatos contra me conspirare. | Sentio aliquos togatos contra me conspirare. | 100 | 2015-01-01 | Sentio aliquos togatos contra me conspirare. | 200 |
|
400 | 400% | Sentio aliquos togatos contra me conspirare. |
|
|
| Sentio aliquos togatos contra me conspirare. | Sentio aliquos togatos contra me conspirare. | 100 | 2015-01-31 | Sentio aliquos togatos contra me conspirare. | 200 |
|
400 | 400% | Sentio aliquos togatos contra me conspirare. |
|
Code
| Type | Details | Code: header cells | Code: data cells |
|---|---|---|---|
| Icon | For cells which contain nothing but a single icon. The icon will be centre aligned. |
|
|
| Number | For cells which contain a number, including numbers with units. |
|
|
| Date | For cells which contain dates (any format). |
|
|
| Form | For cells which contain nothing but form inputs. |
|
|
| Control | For cells which contain nothing but controls - usually buttons. |
|
|
| Checkbox | For cells which contain nothing but checkboxes. |
|
|
| Asset | For cells which contain nothing but assets. |
|
|
Multiple rows in table header
Table headers can have two rows where required. All cells must be TH elements and colspan can be used in the first row to group cells in the second row.
| User Group 1 | User Group 2 | ||
|---|---|---|---|
| User | Role | User | Role |
| Jo User | Author | Kim User | Approver |
| Alex User | Approver | Charlie User | Author |
Code
<div class="ace-table-scroll-container">
<div class="ace-table-container">
<table class="ace-table">
<thead>
<tr>
<th colspan="2">User Group 1
</th>
<th colspan="2">User Group 2
</th>
</tr>
<tr>
<th>User
</th>
<th>Role
</th>
<th>User
</th>
<th>Role
</th>
</tr>
</thead>
<tbody>
<tr>
<td>Jo User
</td>
<td>Author
</td>
<td>Kim User
</td>
<td>Approver
</td>
</tr>
<tr>
<td>Alex User
</td>
<td>Approver
</td>
<td>Charlie User
</td>
<td>Author
</td>
</tr>
</tbody>
</table>
</div>
</div>