Design
Tables are used to display and sort large sets of tabular information. They are also used to provide controls for contextual or inline editing of that information.
Design rules
- Use sortable tables by default (ie. if no other instruction received, make them sortable)
- It is important to consider the fact ACE sortable tables are sorted on the client-side, not the server side. Client-side sorting can only re-order the current view's data. If the current view is part of paginated data, a true sort may require a server-side call and re-render; or it may be more appropriate to simply disable sorting. All of this must be considered in the design phase.
- 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
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 for any layout purpose. It is very rare to genuinely need a nested table for display of data.
There are two table types:
- Default - used for tables which do not have any interactive controls. That is, they are purely for data.
- With Controls (
with-controls) - used for tables where the user is interacting and potentially changing the contents of the table.
Both types can use table sorting.
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 %>
h3.ace-h3 ASP Attributes
+ace-table
+ace-table-thead
+ace-table-tr()
+ace-table-th Element
+ace-table-th Name
+ace-table-th Use
+ace-table-th Description
+ace-table-tbody
+ace-table-tr()
+ace-table-td ace.Table
+ace-table-td sortable
+ace-table-td boolean
+ace-table-td Makes the table sortable
+ace-table-tr()
+ace-table-td ace.Table
+ace-table-td type
+ace-table-td string
+ace-table-td Sets type of table
+ace-table-tr()
+ace-table-td ace.Table
+ace-table-td caption
+ace-table-td string
+ace-table-td Adds a caption
+ace-table-tr()
+ace-table-td ace.Table
+ace-table-td customclass
+ace-table-td string
+ace-table-td 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" title="Actions 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" title="Really important stuff">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 class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr>
<td>2
</td>
<td>Blue-and-yellow Macaw
</td>
<td>Panama
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr>
<td>3
</td>
<td>Green-winged Macaw
</td>
<td>South America
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">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 class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr class="ace-table-disabled">
<td>5
</td>
<td>Scarlet Macaw
</td>
<td>Mexico
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" disabled="disabled" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr class="ace-table-disabled">
<td>6
</td>
<td>James Brown
</td>
<td>Portland
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" disabled="disabled" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr class="ace-table-disabled">
<td>7
</td>
<td>Sam Morison
</td>
<td>Oakville
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" disabled="disabled" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
</tbody>
</table>
</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 provide client-side sorting for tables. 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 class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr>
<td>2
</td>
<td>Blue-and-yellow Macaw
</td>
<td>Panama
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr>
<td>3
</td>
<td>Green-winged Macaw
</td>
<td>South America
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr>
<td>4
</td>
<td>Blue-throated Macaw
</td>
<td>North Bolivia
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">More actions</span></span></button>
</td>
</tr>
<tr>
<td>5
</td>
<td>Scarlet Macaw
</td>
<td>Mexico
</td>
<td>
<button class="ace-button ace-button-subtle ace-button-icon" data-ace-dropdown-trigger="dropdown-menu-trigger" type="button"><span><span class="ace-icon ace-icon-control-menu" title="More actions">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.
To prevent an entire table being sortable, add data-ace-sortable="false" to the table element. Note that this is currently the default; and omitting the data-ace-sortable attribute will have the same effect as explicitly encoding false. However it may be useful to explicitly encode a choice (self-documenting code) or to entirely future-proof a table that must never be sorted.
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>