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 th for header cells
  • You must use thead, tbody and tfoot as 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 Actions Disabled
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-value attribute. 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-type attribute. It must be one of alpha, 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.sssZ or a valid simplification of that; such as YYYY-MM-DD.
  • All numeric types default to a descending sort, meaning 5 will appear before 4

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-customsort to the table.ace-table element.
  • When the column is sorted in ascending order, add the attribute data-ace-sorted-direction="ascending" to the appropriate th element.
  • When the column is sorted in descending order, add the attribute data-ace-sorted-direction="descending" to the appropriate th element.

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 cells
  • number - cells containing just a number
  • date - any date format
  • form - form inputs
  • control - controls, usually buttons
  • checkbox - for checkbox inputs
  • email - email address
  • user - information about a single user
  • user-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. Generic icon 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. Generic icon 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. Generic icon 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.

                                                            <th class="ace-table-cell-icon">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-icon">(icon)
                                                            </td>
Number For cells which contain a number, including numbers with units.

                                                            <th class="ace-table-cell-number">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-number">(number)
                                                            </td>
Date For cells which contain dates (any format).

                                                            <th class="ace-table-cell-date">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-date">(date)
                                                            </td>
Form For cells which contain nothing but form inputs.

                                                            <th class="ace-table-cell-form">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-form">(form inputs)
                                                            </td>
Control For cells which contain nothing but controls - usually buttons.

                                                            <th class="ace-table-cell-control">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-control">(controls)
                                                            </td>
Checkbox For cells which contain nothing but checkboxes.

                                                            <th class="ace-table-cell-checkbox">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-checkbox">(checkbox)
                                                            </td>
Asset For cells which contain nothing but assets.

                                                            <th class="ace-table-cell-asset">(heading)
                                                            </th>

                                                            <td class="ace-table-cell-asset">(asset)
                                                            </td>

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>