Skip to content

Commit 4c9f8db

Browse files
andrewseguinandrewseguin
committed
split cdk table into guide
1 parent c5701d9 commit 4c9f8db

File tree

12 files changed

+148
-313
lines changed

12 files changed

+148
-313
lines changed

‎src/cdk/table/table.md

Lines changed: 30 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,23 @@
1-
The CDK Data Table displays rows of data with fully customizable cell templates.
1+
The CDK data-table displays rows of data with fully customizable cell templates.
22
Its single responsibility is the efficient rendering of rows in a fully accessible way.
33

4-
The CDK table provides a foundation upon which other features, such as sorting and pagination, can be built.
5-
Because the CDK table enforces no opinions on these matters, developers have full control over the interaction patterns associated with the table.
4+
The table provides a foundation upon which other features, such as sorting and pagination, can be built.
5+
Because it enforces no opinions on these matters, developers have full control over the interaction patterns associated with the table.
66

7-
For a Material Design styled table, see `<md-table>`, which builds on top of the CDK Data Table.
7+
For a Material Design styled table, see the documentation for `<md-table>` which builds on top of the CDK data-table.
88

99
In the near future, the material library will include an additional "simple table",
10-
building `<md-table>` with a more minimal interface and sorting, pagination, and selection built-in.
11-
12-
<!-- example(table-basic) -->
10+
building `<md-table>` with a more minimal interface and sorting, pagination, and selection built-in.
1311

1412
## Using the CDK Data Table
1513

1614
### Writing your table template
1715

18-
The first step to writing the CDK Data Table template is to define the columns that will be used in your table.
19-
Each column definition will consist of a header cell template and a data cell template by using
20-
the `<cdk-header-cell>` and `<cdk-cell>`, respectively. These will be wrapped in an `<ng-container>` and given a column name.
16+
The first step to writing the data-table template is to define the columns.
17+
A column definition is specified via an `<ng-container>` with the `cdkColumnDef` directive, giving
18+
column a name. Each column definition then contains further definitions for both a header-cell
19+
template (`cdkHeaderCellDef`) and a data-cell template (`cdkCellDef`).
2120

22-
Both the `<cdk-header-cell>` and `<cdk-cell>` require an additional directive so that the table can
23-
capture the inner template. For `<cdk-header-cell>` you must include the attribute `*cdkHeaderCellDef`
24-
and for `<cdk-cell>` you must include `*cdkCellDef`. Note that the `*cdkCellDef` provides an outlet
25-
to capture the cell’s row data to be used in the template.
2621

2722
```html
2823
<ng-container cdkColumnDef="column_a">
@@ -31,14 +26,20 @@ to capture the cell’s row data to be used in the template.
3126
</ng-container>
3227
```
3328

34-
After the columns have been defined, you must include a `<cdk-header-row>` and `<cdk-row>` which will
35-
each take an array of the column names. This will be the columns that will be rendered in the table and in the order provided.
29+
Note that `cdkCellDef` exports the row context such that the row data (and additional fields) can
30+
be referenced in the cell template.
31+
32+
The next step is to define the table's header-row (`cdkHeaderRowDef`) and data-row (`cdkRowDef`).
33+
Each should be provided a list of which columns should be rendered and in which order.
3634

3735
```html
3836
<cdk-header-row *cdkHeaderRowDef="['column_a', 'column_b', 'column_c']"></cdk-header-row>
3937
<cdk-row *cdkRowDef="let row; columns: ['column_a', 'column_b', 'column_c']"></cdk-row>
4038
```
4139

40+
Note that `cdkRowDef` also exports row context, which can be used to apply event and attribute
41+
bindings that use the row data (and additional fields).
42+
4243
In the following template, we have a data table that displays three columns: Column A, Column B, and Column C.
4344
The <cdk-header-row> and <cdk-row> are given an input of what columns to display.
4445

@@ -62,15 +63,15 @@ The <cdk-header-row> and <cdk-row> are given an input of what columns to display
6263
<cdk-cell *cdkCellDef="let row"> {{row.c}} </cdk-cell>
6364
</ng-container>
6465

65-
<!-- Header and Row Declarations (define columns; provide attribute and event binding) -->
66+
<!-- Header and Row Declarations -->
6667
<cdk-header-row *cdkHeaderRowDef="['column_a', 'column_b', 'column_c']"></cdk-header-row>
6768
<cdk-row *cdkRowDef="let row; columns: ['column_a', 'column_b', 'column_c']"></cdk-row>
6869
</cdk-table>
6970
```
7071

71-
It is not required to display all the columns that are defined within the template,
72-
nor is the order required. For example, if we wanted the table to display only Column B
73-
and Column A and in that order, then the template would look like this:
72+
Note that it is not required to display all the columns that are defined within the template,
73+
nor use the same ordering. For example, to display the table with only Column B
74+
and Column A and in that order, then the row and header definitions would be written as:
7475

7576
```html
7677
<cdk-header-row *cdkHeaderRowDef="['column_b', 'column_a’]"></cdk-header-row>
@@ -94,86 +95,21 @@ property is greater than 20.
9495
```
9596

9697
Changing the list of columns provided to the `<cdk-header-row>` and `<cdk-row>` will automatically
97-
cause the table to re-render to reflect those changes. For more information, see Dynamic Columns below under Features.
98+
cause the table to re-render to reflect those changes.
9899

99100
### Connecting the table to a data source
100101
Data is provided to the table through the `DataSource` interface. When the table receives a DataSource,
101-
it calls its connect function to receive an observable that emits an array of data. Whenever the Data Source emits data to this stream, the table will use it to render its rows.
102+
it calls the DataSource's connect function which returns an observable that emits an array of data.
103+
Whenever the Data Source emits data to this stream, the table will use it to render its rows.
102104

103105
Since the Data Source provides this data stream, it is responsible for watching for data changes
104-
and notifying the table when to re-render. Examples of these data changes includes sorting, pagination, filtering, and more.
105-
To see how these examples can be incorporated in the Data Source, see below under Features.
106+
and notifying the table when to re-render. Examples of these data changes includes sorting, pagination,
107+
filtering, and more.
106108

107-
Note that a trackBy function can be provided to the table similar to Angular’s ngFor trackBy.
108-
This allows you to customize how the table to identifies rows and improves performance.
109+
To improve performance, a trackBy function can be provided to the table similar to Angular’s ngFor trackBy.
110+
This allows you to customize how the table to identifies rows and helps it to understand how
111+
the data is changing.
109112

110113
In the future, the connect function will be able to use the CollectionViewer parameter to be
111114
notified about table events, such as what rows the user is currently viewing. This could be used to
112-
help the Data Source know what data does not need to be retrieved and rendered, further improving performance.
113-
114-
## Material Table
115-
To use the CDK Data Table with styles matching the Material Design spec, you can use the `<md-table>`
116-
defined in `@angular/material`. This will build on the CDK Data Table and apply built-in Material Design styles.
117-
118-
The interface for the `<md-table>` matches the `<cdk-table>`, except that its element selectors
119-
will be prefixed with `md-` instead of `cdk-`.
120-
121-
Note that the column definition directives (`cdkColumnDef` and `cdkHeaderCellDef`) are still prefixed with `cdk-`.
122-
123-
```html
124-
<md-table [dataSource]="dataSource">
125-
<!-- Column A Definition -->
126-
<ng-container cdkColumnDef="column_a">
127-
<md-header-cell *cdkHeaderCellDef> Column A </md-header-cell>
128-
<md-cell *cdkCellDef="let row"> {{row.a}} </md-cell>
129-
</ng-container>
130-
131-
<!-- Column B Definition -->
132-
<ng-container cdkColumnDef="column_b">
133-
<md-header-cell *cdkHeaderCellDef> Column B </md-header-cell>
134-
<md-cell *cdkCellDef="let row"> {{row.b}} </md-cell>
135-
</ng-container>
136-
137-
<!-- Column C Definition -->
138-
<ng-container cdkColumnDef="column_c">
139-
<md-header-cell *cdkHeaderCellDef> Column C </md-header-cell>
140-
<md-cell *cdkCellDef="let row"> {{row.c}} </md-cell>
141-
</ng-container>
142-
143-
<!-- Header and Row Declarations (define columns; provide attribute and event binding) -->
144-
<md-header-row *cdkHeaderRowDef="['column_a', 'column_b', 'column_c']"></md-header-row>
145-
<md-row *cdkRowDef="let row; columns: ['column_a', 'column_b', 'column_c']"></md-row>
146-
</md-table>
147-
```
148-
149-
## Simple Table
150-
151-
In the near future, we would like to provide a simple version of the data table that includes an easy-to-use interface,
152-
material styling, data array input, and out-of-the-box features such as sorting, pagination, and selection.
153-
154-
## Features
155-
156-
The CDK Table’s responsibility is to handle efficient rendering of rows and it’s the Data Source’s job
157-
to let the table know what data should be rendered. As such, features that manipulate what data should
158-
be rendered should be the responsibility of the data source.
159-
160-
### Pagination
161-
Use the MdPagination component to add data paging to the data table. The data source can listen to
162-
paging events from the component and appropriately slice the right data from whatever data provider
163-
is used. Sending this new data to the table will cause it to render the new page of data.
164-
165-
<!-- example(table-pagination) -->
166-
167-
### Sorting
168-
Use the MdSort component to enable sorting the table's data through the column headers.
169-
The data source can listen to sorting events from the component and sort the data before giving it
170-
to the table to render.
171-
172-
<!-- example(table-sorting) -->
173-
174-
### Filtering
175-
176-
Apply filtering to your table's data by listening to an input's changes.
177-
When a change occurs, filter the data in the data source and send it to the table to render.
178-
179-
<!--- example(table-filtering) -->
115+
help the Data Source know what data does not need to be retrieved and rendered, further improving performance.

‎src/lib/table/table.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
The `md-table` provides a Material Design styled data table that can be used to display rows of data.
2+
3+
This table builds on the foundation of the CDK data-table and uses a similar interface for its
4+
data source input and template, except that its element selectors will be prefixed with `md-` instead of `cdk-`.
5+
6+
<!-- example(table-basic) -->
7+
8+
Note that the column definition directives (`cdkColumnDef` and `cdkHeaderCellDef`) are still prefixed with `cdk-`.
9+
10+
For more information on the interface and how it works, see the guide covering the CDK data-table.
11+
12+
## Simple Table
13+
14+
In the near future, we would like to provide a simple version of the data table that includes an easy-to-use interface,
15+
material styling, data array input, and out-of-the-box features such as sorting, pagination, and selection.
16+
17+
## Features
18+
19+
Adding features on top of the `md-table` such as sorting and pagination can be done by merging
20+
events within the data source and sending the updated data to the table through the stream provided
21+
in the `connect` function.
22+
23+
### Pagination
24+
25+
Use the `md-pagination` component to add data paging to the table. The data source can listen to
26+
paging events from the component and appropriately slice the right data from whatever data provider
27+
is used. Sending this new data to the table will cause it to render the new page of data.
28+
29+
<!-- example(table-pagination) -->
30+
31+
### Sorting
32+
Use the `mdSort` directive and `md-sort-header` component to enable sorting on the table through
33+
the column headers. The data source can listen to sorting events from the component and sort the data
34+
before giving it to the table to render.
35+
36+
<!-- example(table-sorting) -->
37+
38+
### Filtering
39+
40+
Apply filtering to your table's data by listening to an input's changes.
41+
When a change occurs, filter the data in the data source and send it to the table to render.
42+
43+
<!--- example(table-filtering) -->

‎src/material-examples/table-basic/table-basic-example.css

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -15,34 +15,6 @@
1515
font-size: 20px;
1616
}
1717

18-
/*
19-
* Styles to make the demo's cdk-table match the material design spec
20-
* https://material.io/guidelines/components/data-tables.html
21-
*/
22-
.cdk-table {
23-
flex: 1 1 auto;
18+
.mat-table {
2419
overflow: auto;
2520
}
26-
27-
.cdk-row, .cdk-header-row {
28-
display: flex;
29-
border-bottom: 1px solid #ccc;
30-
align-items: center;
31-
height: 48px;
32-
padding: 0 24px;
33-
}
34-
35-
.cdk-cell, .cdk-header-cell {
36-
flex: 1;
37-
}
38-
39-
.cdk-header-cell {
40-
font-size: 12px;
41-
font-weight: bold;
42-
color: rgba(0, 0, 0, 0.54);
43-
}
44-
45-
.cdk-cell {
46-
font-size: 13px;
47-
color: rgba(0, 0, 0, 0.87);
48-
}

‎src/material-examples/table-basic/table-basic-example.html

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,36 @@
11
<div class="example-container mat-elevation-z8">
22
<div class="example-header"> Users </div>
33

4-
<cdk-table #table [dataSource]="dataSource">
4+
<md-table #table [dataSource]="dataSource">
55

66
<!--- Note that these columns can be defined in any order.
77
The actual rendered columns are set as a property on the row definition" -->
88

99
<!-- ID Column -->
1010
<ng-container cdkColumnDef="userId">
11-
<cdk-header-cell *cdkHeaderCellDef> ID </cdk-header-cell>
12-
<cdk-cell *cdkCellDef="let row"> {{row.id}} </cdk-cell>
11+
<md-header-cell *cdkHeaderCellDef> ID </md-header-cell>
12+
<md-cell *cdkCellDef="let row"> {{row.id}} </md-cell>
1313
</ng-container>
1414

1515
<!-- Progress Column -->
1616
<ng-container cdkColumnDef="progress">
17-
<cdk-header-cell *cdkHeaderCellDef> Progress </cdk-header-cell>
18-
<cdk-cell *cdkCellDef="let row"> {{row.progress}}% </cdk-cell>
17+
<md-header-cell *cdkHeaderCellDef> Progress </md-header-cell>
18+
<md-cell *cdkCellDef="let row"> {{row.progress}}% </md-cell>
1919
</ng-container>
2020

2121
<!-- Name Column -->
2222
<ng-container cdkColumnDef="userName">
23-
<cdk-header-cell *cdkHeaderCellDef> Name </cdk-header-cell>
24-
<cdk-cell *cdkCellDef="let row"> {{row.name}} </cdk-cell>
23+
<md-header-cell *cdkHeaderCellDef> Name </md-header-cell>
24+
<md-cell *cdkCellDef="let row"> {{row.name}} </md-cell>
2525
</ng-container>
2626

2727
<!-- Color Column -->
2828
<ng-container cdkColumnDef="color">
29-
<cdk-header-cell *cdkHeaderCellDef>Color</cdk-header-cell>
30-
<cdk-cell *cdkCellDef="let row" [style.color]="row.color"> {{row.color}} </cdk-cell>
29+
<md-header-cell *cdkHeaderCellDef>Color</md-header-cell>
30+
<md-cell *cdkCellDef="let row" [style.color]="row.color"> {{row.color}} </md-cell>
3131
</ng-container>
3232

33-
<cdk-header-row *cdkHeaderRowDef="displayedColumns"></cdk-header-row>
34-
<cdk-row *cdkRowDef="let row; columns: displayedColumns;">
35-
</cdk-row>
36-
</cdk-table>
33+
<md-header-row *cdkHeaderRowDef="displayedColumns"></md-header-row>
34+
<md-row *cdkRowDef="let row; columns: displayedColumns;"></md-row>
35+
</md-table>
3736
</div>

‎src/material-examples/table-filtering/table-filtering-example.css

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -30,34 +30,6 @@
3030
margin-left: 32px;
3131
}
3232

33-
/*
34-
* Styles to make the demo's cdk-table match the material design spec
35-
* https://material.io/guidelines/components/data-tables.html
36-
*/
37-
.cdk-table {
38-
flex: 1 1 auto;
33+
.mat-table {
3934
overflow: auto;
4035
}
41-
42-
.cdk-row, .cdk-header-row {
43-
display: flex;
44-
border-bottom: 1px solid #ccc;
45-
align-items: center;
46-
height: 48px;
47-
padding: 0 24px;
48-
}
49-
50-
.cdk-cell, .cdk-header-cell {
51-
flex: 1;
52-
}
53-
54-
.cdk-header-cell {
55-
font-size: 12px;
56-
font-weight: bold;
57-
color: rgba(0, 0, 0, 0.54);
58-
}
59-
60-
.cdk-cell {
61-
font-size: 13px;
62-
color: rgba(0, 0, 0, 0.87);
63-
}

‎src/material-examples/table-filtering/table-filtering-example.html

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,37 +7,36 @@
77
</md-input-container>
88
</div>
99

10-
<cdk-table #table [dataSource]="dataSource">
10+
<md-table #table [dataSource]="dataSource">
1111

1212
<!--- Note that these columns can be defined in any order.
1313
The actual rendered columns are set as a property on the row definition" -->
1414

1515
<!-- ID Column -->
1616
<ng-container cdkColumnDef="userId">
17-
<cdk-header-cell *cdkHeaderCellDef> ID </cdk-header-cell>
18-
<cdk-cell *cdkCellDef="let row"> {{row.id}} </cdk-cell>
17+
<md-header-cell *cdkHeaderCellDef> ID </md-header-cell>
18+
<md-cell *cdkCellDef="let row"> {{row.id}} </md-cell>
1919
</ng-container>
2020

2121
<!-- Progress Column -->
2222
<ng-container cdkColumnDef="progress">
23-
<cdk-header-cell *cdkHeaderCellDef> Progress </cdk-header-cell>
24-
<cdk-cell *cdkCellDef="let row"> {{row.progress}}% </cdk-cell>
23+
<md-header-cell *cdkHeaderCellDef> Progress </md-header-cell>
24+
<md-cell *cdkCellDef="let row"> {{row.progress}}% </md-cell>
2525
</ng-container>
2626

2727
<!-- Name Column -->
2828
<ng-container cdkColumnDef="userName">
29-
<cdk-header-cell *cdkHeaderCellDef> Name </cdk-header-cell>
30-
<cdk-cell *cdkCellDef="let row"> {{row.name}} </cdk-cell>
29+
<md-header-cell *cdkHeaderCellDef> Name </md-header-cell>
30+
<md-cell *cdkCellDef="let row"> {{row.name}} </md-cell>
3131
</ng-container>
3232

3333
<!-- Color Column -->
3434
<ng-container cdkColumnDef="color">
35-
<cdk-header-cell *cdkHeaderCellDef> Color </cdk-header-cell>
36-
<cdk-cell *cdkCellDef="let row" [style.color]="row.color"> {{row.color}} </cdk-cell>
35+
<md-header-cell *cdkHeaderCellDef> Color </md-header-cell>
36+
<md-cell *cdkCellDef="let row" [style.color]="row.color"> {{row.color}} </md-cell>
3737
</ng-container>
3838

39-
<cdk-header-row *cdkHeaderRowDef="displayedColumns"></cdk-header-row>
40-
<cdk-row *cdkRowDef="let row; columns: displayedColumns;">
41-
</cdk-row>
42-
</cdk-table>
39+
<md-header-row *cdkHeaderRowDef="displayedColumns"></md-header-row>
40+
<md-row *cdkRowDef="let row; columns: displayedColumns;"></md-row>
41+
</md-table>
4342
</div>

0 commit comments

Comments
 (0)