docs(table): updated docs for the table #8162

andrewseguin · 2017-10-31T18:40:10Z

To be added later: expanding rows (using when predicate), customizing column widths, adding/removing data, dynamic columns (add/remove/move), trackBy

Re-opened PR at #8770

willshowell

Break newlines?
The single quotes look styled from copy-paste. I dunno if that matters, but it looks out of place in the code blocks.

willshowell · 2017-10-31T18:57:15Z

src/lib/table/table.md

-data.
+The `mat-table` provides a Material Design styled data-table that can be used to display rows of data. 
+
+The table’s template is made up of column definitions where each definition provides the content for that column’s header and row cells. It also includes a `mat-header-row` and `mat-row` where each takes an ordered list of the columns they should render out.


Maybe

...they should render.

or

...they should stamp out.

Also consider making <mat-header-row> and <mat-row>

willshowell · 2017-10-31T19:06:30Z

src/lib/table/table.md

+
+```ts
+const myDataSource = new MatTableDataSource();
+myDataSource.data = dataToRender;


Change to emphasize the data source is a class property?

this.myDataSource = new MatTableDataSource(); this.myDataSource.data = dataToRender;

willshowell · 2017-10-31T19:12:06Z

src/lib/table/table.md

+```js
+const initialSelection = [];
+const allowMultiSelect = true;
+const selection = new SelectionModel<MyDataType>(allowMultiSelect, initialSelection);


Same thing here since selection should be a class property

willshowell · 2017-10-31T19:12:30Z

src/lib/table/table.md

+
+```html
+<ng-container matColumnDef="select">
+ <mat-header-cell *matHeaderCellDef>


Indentation off by 1

willshowell · 2017-10-31T19:14:13Z

src/lib/table/table.md

+
+```css
+.mat-column-select {
+ overflow: initial;


Indentation off by 1

andrewseguin · 2017-10-31T19:35:49Z

Thanks for the review - made the changes. Wasn't sure what you mean about breaking newlines

willshowell

Oops yeah I just meant to break the lines around 100 columns 👍

willshowell · 2017-10-31T19:42:58Z

src/lib/table/table.md

+will let the table know what columns each row should render.
+
+```html
+<mat-header-row *matHeaderRowDef="[‘userName', ‘age']"></mat-header-row>


Looks like only the closing ones have changed. There are a few remaining opening single-quotes that are styled.

Ugh, thanks Google Docs

jelbourn · 2017-10-31T19:54:27Z

src/lib/table/table.md

+
+The table's template is made up of column definitions where each definition provides the content for 
+that column's header and row cells. It also includes a `<mat-header-row>` and `<mat-row>` where each 
+takes an ordered list of the columns they should render.


I would rephrase this paragraph a bit

The table's template consists of two parts: column definitions and row definitions. Each column definition contains templates for that column's header and content cells. Each row definition captures the columns used for that row and any bindings applied to the row element.

jelbourn · 2017-10-31T20:06:40Z

src/lib/table/table.md

+providing an Observable that emits an array of data. The table picks up this data array and writes 
+a `mat-row` for each data object in the array. It is the responsibility of the `DataSource` to send 
+exactly what data should be rendered by the table, so any data manipulation features such as 
+sorting or filtering should be implemented here.


Trying to tighten the language a bit, avoiding passive voice:

A `DataSource` provides data to the table by emitting an `Observable` stream of the items to be rendered. Each emit includes the _entire set of items_ that being displayed. The table, listening to this stream, will render a row per item. Any manipulation of the data being displayed (e.g. sorting, pagination, filtering) should be captured by the `DataSource`, ultimately emitting a new set of items to reflect any changes.

jelbourn · 2017-10-31T20:10:01Z

src/lib/table/table.md

 <!-- example(table-basic) -->

-### Features
+Start by writing your table's column definitions. Each column definition should be given a unique 


Would numbered subheaders help here?

#### 1. Define the table's columns ... #### 2. Define the table's rows ... #### 3. Provide data ...

jelbourn · 2017-10-31T20:16:45Z

src/lib/table/table.md

+<mat-row *matRowDef="let myRowData; columns: ['userName', 'age']"></mat-row>
+```
+
+Once your template is set up, the final step is to provide data to the table. This must be done 


Maybe something like

The column and row definitions now capture _how_ data will render- all that's left is to provide the data itself. For simple scenarios with client-side operations, `MatTableDataSource` offers a quick and easy starting point. Simply create an instance of `MatTableDataSource` and set the items to be displayed to the `data` property. For more advanced scenarios, applications will implement one or more custom `DataSource` to capture more specific behaviors.

jelbourn · 2017-10-31T20:17:42Z

src/lib/table/table.md

+changes made by the user and send the right paged data to the table.
+
+For more information on using and configuring the `<mat-paginator>`, check out the 
+[mat-paginator docs](https://material.angular.io/components/paginator/overview).


We should mention here that mat-paginator is just one option. The table can work with any paginator control or any pagination strategy.

(same for sorting, filtering, and selection)

jelbourn · 2017-10-31T20:21:17Z

src/lib/table/table.md

-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.
+To remove filtered rows from the table's data, simply provide the filter string to the 


This section is too specifically about the MatTableDataSource. We should mention that we don't provide any filtering UI components and that filtering is up to the app. Then MatTableDataSource can be the "if you want something simple" extra thing.

Flexibility is great, but this documentation is under angular/material2. Most developers won't have time to try a lot of different options. Would still be good to provide example code for MatTableDataSource.

jelbourn · 2017-10-31T20:22:37Z

src/lib/table/table.md

-and selection).
+#### Selection
+
+To add row selection to the table, first set up a `SelectionModel` from `@angular/cdk/collections` 


Same comment here about specificity- I want to keep it clear that users can do selection however they want. If we present it as "this is the way you are supposed to do selection", it begs the question as to why it's not just built in. I would really rather include this in an example with explanation that say "Here is the One True Way to do selection" (same for filtering)

Flexibility is nice, but most developers are just going to want a working example they can start with.

angular-automatic-lock-bot · 2019-09-07T21:01:51Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

docs(table): updated docs for the table

07bb7b7

andrewseguin added the pr: needs review label Oct 31, 2017

andrewseguin requested review from jelbourn and mmalerba October 31, 2017 18:40

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Oct 31, 2017

andrewseguin added 2 commits October 31, 2017 11:42

emphasize headers

4e83d98

update column username

183c4d1

willshowell reviewed Oct 31, 2017

View reviewed changes

andrewseguin added 2 commits October 31, 2017 12:35

review

4319864

change

fe31df8

willshowell reviewed Oct 31, 2017

View reviewed changes

fix single quote

9b7e82a

andrewseguin added the P2 The issue is important to a large percentage of users, with a workaround label Oct 31, 2017

jelbourn reviewed Oct 31, 2017

View reviewed changes

willshowell mentioned this pull request Nov 6, 2017

[table] add example how to write generic code for md-table #8249

Closed

andrewseguin mentioned this pull request Nov 21, 2017

Add detailed documentation for using DataSource with MatTable #8227

Closed

andrewseguin closed this Nov 28, 2017

andrewseguin deleted the table-updated-docs branch November 28, 2017 20:38

andrewseguin restored the table-updated-docs branch November 28, 2017 20:38

andrewseguin mentioned this pull request Dec 2, 2017

docs(table): updated docs for the table #8770

Merged

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 7, 2019

docs(table): updated docs for the table #8162

docs(table): updated docs for the table #8162

Uh oh!

Conversation

andrewseguin commented Oct 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

willshowell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewseguin commented Oct 31, 2017

Uh oh!

willshowell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

angular-automatic-lock-bot bot commented Sep 7, 2019

Uh oh!

Uh oh!

andrewseguin commented Oct 31, 2017 •

edited

Loading