diff --git a/guides/cdk-table.md b/guides/cdk-table.md index 0b6881d8be6..61c2c55eecc 100644 --- a/guides/cdk-table.md +++ b/guides/cdk-table.md @@ -18,98 +18,100 @@ top of the CDK data-table. The first step to writing the data-table template is to define the columns. A column definition is specified via an `` with the `cdkColumnDef` directive, giving -column a name. Each column definition then further defines both a header-cell template +the column a name. Each column definition then further defines both a header-cell template (`cdkHeaderCellDef`) and a data-cell template (`cdkCellDef`). - ```html - - User name - {{row.a}} - + + User name + {{row.a}} + ``` The set of columns defined represent the columns that are _available_ to be rendered. The specific -columns rendered in a given row, and their order, are specified on the row (see below). +columns rendered in a given row, and their order, are specified on the row (see below). Note that `cdkCellDef` exports the row context such that the row data can be referenced in the cell template. The directive also exports the same properties as `ngFor` (index, even, odd, first, last). -The next step is to define the table's header-row (`cdkHeaderRowDef`) and data-row (`cdkRowDef`). +The next step is to define the table's header-row (`cdkHeaderRowDef`) and data-row (`cdkRowDef`). ```html - - + + ``` These row templates accept the specific columns to be rendered via the name given to the `cdkColumnDef`. - The `cdkRowDef` also exports row context, which can be used for event and property bindings on the row element. Any content placed _inside_ of the header row or data row template will be ignored, as the rendered content of the row comes from the cell templates described above. - ##### Example: table with three columns + ```html - - - User name - {{row.username}} - + + + User name + {{row.username}} + - - - Age - {{row.age}} - + + + Age + {{row.age}} + - - - Title - {{row.title}} - + + + Title + {{row.title}} + - - - - + + + + ``` The columns given on the row determine which cells are rendered and in which order. Thus, the columns can be set via binding to support dynamically changing the columns shown at run-time. +```html + +``` It is not required to display all the columns that are defined within the template, nor use the same ordering. For example, to display the table with only `age` and `username` and in that order, then the row and header definitions would be written as: ```html - + ``` -Event and property bindings can be added directly to the row element. +Event and property bindings can be added directly to the row element. ##### Example: table with event and class binding ```html - - + + - = 18” - (click)=”handleRowClick(row)”> - + + ``` #### Connecting the table to a data source + Data is provided to the table through a `DataSource`. When the table receives a data source, -it calls the DataSource's connect function which returns an observable that emits an array of data. -Whenever the data source emits data to this stream, the table will update. +it calls the DataSource's `connect()` method which returns an observable that emits an array of data. +Whenever the data source emits data to this stream, the table will render an update. Because the _data source_ provides this stream, it bears the responsibility of triggering table updates. This can be based on _anything_: websocket connections, user interaction, model updates, @@ -117,8 +119,9 @@ time-based intervals, etc. Most commonly, updates will be triggered by user inte sorting and pagination. ##### `trackBy` -To improve performance, a trackBy function can be provided to the table similar to Angular’s -[`ngFor` trackBy](https://angular.io/api/common/NgForOf#change-propagation). This informs the + +To improve performance, a `trackBy` function can be provided to the table similar to Angular’s +[`ngFor` `trackBy`](https://angular.io/api/common/NgForOf#change-propagation). This informs the table how to uniquely identify rows to track how the data changes with each update. ```html diff --git a/src/cdk/table/table.ts b/src/cdk/table/table.ts index 592e56d63fa..1ef7bb06c4e 100644 --- a/src/cdk/table/table.ts +++ b/src/cdk/table/table.ts @@ -74,7 +74,7 @@ export const CDK_TABLE_TEMPLATE = ` `; /** - * A data table that connects with a data source to retrieve data of type T and renders + * A data table that connects with a data source to retrieve data of type `T` and renders * a header row and data rows. Updates the rows when new data is provided by the data source. */ @Component({ @@ -110,7 +110,7 @@ export class CdkTable implements CollectionViewer { /** * Tracking function that will be used to check the differences in data changes. Used similarly - * to ngFor trackBy function. Optimize row operations by identifying a row based on its data + * to `ngFor` `trackBy` function. Optimize row operations by identifying a row based on its data * relative to the function to know if a row should be added/removed/moved. * Accepts a function that takes two parameters, `index` and `item`. */ @@ -129,7 +129,7 @@ export class CdkTable implements CollectionViewer { // TODO(andrewseguin): Remove max value as the end index // and instead calculate the view on init and scroll. /** - * Stream containing the latest information on what rows are being displayed on screen. + * Stream containing the latest information on the range of rows being displayed on screen. * Can be used by the data source to as a heuristic of what data should be provided. */ viewChange = diff --git a/src/lib/table/table.md b/src/lib/table/table.md index 69df1b41e78..bd043b7fc54 100644 --- a/src/lib/table/table.md +++ b/src/lib/table/table.md @@ -3,16 +3,14 @@ data. This table builds on the foundation of the CDK data-table and uses a similar interface for its data source input and template, except that its element selectors will be prefixed with `md-` -instead of `cdk-`. - - - -Note that the column definition directives (`cdkColumnDef` and `cdkHeaderCellDef`) are still +instead of `cdk-`. Note that the column definition directives (`cdkColumnDef` and `cdkHeaderCellDef`) are still prefixed with `cdk-`. For more information on the interface and how it works, see the [guide covering the CDK data-table](https://material.angular.io/guide/cdk-table). + + ### Features The `` itself only deals with the rendering of a table structure (rows and cells). @@ -29,6 +27,7 @@ paginator emits events that can be used to trigger an update via the table's dat #### Sorting + Use the `mdSort` directive and `` adds a sorting UI the table's column headers. The sort headers emit events that can be used to trigger an update via the table's data source. @@ -36,11 +35,10 @@ sort headers emit events that can be used to trigger an update via the table's d #### Filtering -While Angular Material does not offer a specific component for filtering tabular data, the table's +While Angular Material does not offer a specific component for filtering tabular data, the table's data source can be updated based on any custom filter UI. Any filtering pattern need only trigger an update via the table's data source. - ### Simple Table