docs(virtual-scroll): add initial documentation #11496

mmalerba · 2018-05-24T17:29:52Z

crisbeto · 2018-05-24T17:33:11Z

src/cdk-experimental/scrolling/virtual-scroll.md

+The easiest way to provide a strategy is with one of the directives `itemSize` or `autosize`.
+
+For some example usages, 
+[see the demo app](https://github.com/angular/material2/tree/master/src/demo-app/virtual-scroll).


Add a TODO here to add live examples once this lands in stable?

crisbeto · 2018-05-24T17:33:41Z

src/cdk-experimental/scrolling/virtual-scroll.md

+
+### Creating items in the viewport
+`*cdkVirtualFor` should be used instead of `*ngFor` to create items in the
+`<cdk-virtual-scroll-viewport>`. `*cdkVirtualFor` supports most of the same features as `*ngFor`.


Should it mention which features it doesn't support?

I wrote that because I'm naturally hedgey, but I think it supports all of the same features as *ngFor, updated to say that.

crisbeto · 2018-05-24T17:35:07Z

src/cdk-experimental/scrolling/virtual-scroll.md

+
+#### View recycling
+In order to improve performance `*cdkVirtualFor` saves the views it creates in a cache when they are
+no longer needed. This way the next time a new view is needed once can be recycled from the cache


The "once" seems out of place here.

whoops, was supposed to read "one"

crisbeto · 2018-05-24T17:35:45Z

src/cdk-experimental/scrolling/virtual-scroll.md

+In order to improve performance `*cdkVirtualFor` saves the views it creates in a cache when they are
+no longer needed. This way the next time a new view is needed once can be recycled from the cache
+rather than being created from scratch. The size of this cache can be adjusted using the
+`templateCacheSize` input. The cache size defaults to `20` and caching can be disabled by setting it


IMO we should avoid specifying defaults in the docs since they could change and we'll probably forget to update them.

I think its useful for people to know. I'll put it in the jsdoc rather than here though.

crisbeto · 2018-05-24T17:36:45Z

src/cdk-experimental/scrolling/virtual-scroll.md

+connect process.
+
+### Scrolling over fixed size items
+If you're scrolling over a list of items that are all the same fixed size, you can use the


Mention the advantages/disadvantages of using a fixed-size viewport?

jelbourn · 2018-05-25T16:30:22Z

src/cdk-experimental/scrolling/auto-size-virtual-scroll.ts

@@ -435,6 +436,7 @@ export class CdkAutoSizeVirtualScroll implements OnChanges {
   * The number of pixels worth of buffer to shoot for when rendering new items.
   * If the actual amount turns out to be less it will not necessarily trigger an additional
   * rendering cycle (as long as the amount of buffer is still greater than `minBufferPx`).
+   * The default add buffer px is 200.


Defaults to 200px

jelbourn · 2018-05-25T16:30:31Z

src/cdk-experimental/scrolling/auto-size-virtual-scroll.ts

@@ -425,6 +425,7 @@ export class CdkAutoSizeVirtualScroll implements OnChanges {
  /**
   * The minimum amount of buffer rendered beyond the viewport (in pixels).
   * If the amount of buffer dips below this number, more items will be rendered.
+   * The default minBufferPx is 100.


Defaults to 100px

jelbourn · 2018-05-25T16:31:00Z

src/cdk-experimental/scrolling/fixed-size-virtual-scroll.ts

-  /** The number of extra elements to render on either side of the scrolling viewport. */
+  /**
+   * The number of extra elements to render on either side of the scrolling viewport.
+   * The default buffer size is 5.


Defaults to 5 elements

jelbourn · 2018-05-25T16:31:31Z

src/cdk-experimental/scrolling/virtual-for-of.ts

@@ -109,6 +109,10 @@ export class CdkVirtualForOf<T> implements CollectionViewer, DoCheck, OnDestroy
    }
  }

+  /**
+   * The size of the cache used to store templates that are not being used for re-use later.
+   * Setting the cache size to `0` will disable caching. The default cache size is 20.


Defaults to 20 templates

jelbourn · 2018-05-25T16:43:28Z

src/cdk-experimental/scrolling/virtual-scroll.md

+**Warning: this component is still experimental. It may have bugs and the API may change at any
+time**
+
+`<cdk-virtual-scroll-viewport>` is used to display a scrolling list containing a large number of


I would shorten the lede here and move the bits about the strategies to their own section immediately after this. The section for strategies should talk about why you would use one or the other.

Also some editing for brevity and passive voice:

`<cdk-virtual-scroll-viewport>` displays large lists of elements performantly by only rendering the items that appear on-screen. This components works with `*cdkVirtualFor`, a virtualized replacement for `*ngFor`.

jelbourn · 2018-05-25T17:23:39Z

src/cdk-experimental/scrolling/virtual-scroll.md

+</cdk-virtual-scroll-viewport>
+```
+
+The `autosize` strategy allows the buffer to be configured through two inputs `minBufferPx` and


I would break up the paragraph structure a bit here:

The `autosize` strategy is configured through two inputs: `minBufferPx` and `addBufferPx`. **`minBufferPx`** determines the minimum space outside virtual scrolling viewport that will be filled with content. Increasing this will increase the amount of content a user will see before more content must be rendered. However, too large a value will cause more content to be rendered than is necessary. **`addBufferPx`** determines the amount of content that will be added incrementally as the viewport is scrolled. This should be greater than the size of `minBufferPx` so that one "render" is needed at a time.

jelbourn · 2018-05-25T17:24:09Z

src/cdk-experimental/scrolling/virtual-scroll.md

+**Note: The fixed size strategy will likely be changed to allow specifying a separate
+`minBufferPx` and `addBufferPx` like the autosize strategy**
+
+The fixed size viewport strategy is less flexible than the autosize strategy because it requires all


I would just explain this once near the beginning of the doc; it's currently mentioned a few times throughout

jelbourn · 2018-05-25T17:24:28Z

src/cdk-experimental/scrolling/virtual-scroll.md

+Because the auto size strategy needs to measure the size of the elements, its performance may not
+be as good as the fixed size strategy. 
+
+### Setting the viewport orientation


Just #### Viewport orientation ?

jelbourn · 2018-05-25T17:26:00Z

src/cdk-experimental/scrolling/virtual-scroll.md

+`vertical` which virtualizes scrolling along the y-axis. It can be set to `horizontal` to virtualize
+scrolling along the x-axis. If you use this option you need to make sure that the content is
+actually laid out so that it extends along the x-axis. To do this you may want to target CSS at
+`.cdk-virtual-scroll-content-wrapper` which is the wrapper element that contains the rendered


Would it be better/possible to recommend styling their own element instead of a class built into the virtual scroller?

It's eventually going to be possible to specify that element themselves, or just allow it to be implicitly created if they don't specify. That's part of the work for making it work with <table>, <ul>, etc.

jelbourn · 2018-05-25T17:30:46Z

src/cdk-experimental/scrolling/virtual-scroll.md

+be as good as the fixed size strategy. 
+
+### Setting the viewport orientation
+The orientation of the viewport can be adjusted by using the `orientation` input. It defaults to


The virtual-scroll viewport defaults to a vertical orientation, but can also be set to `orientation="horizontal"`. When changing the orientation, ensure that the item are laid out horizontally via CSS.

jelbourn

Looks like some of the comments from the first pass still apply

jelbourn · 2018-05-25T23:09:38Z

src/cdk-experimental/scrolling/virtual-scroll.md

+time**
+
+`<cdk-virtual-scroll-viewport>` displays large lists of elements performantly by only
+rendering the items that appear on-screen. This components works with `*cdkVirtualFor`,


appear -> fit (just occurred to me on second reading)

jelbourn

Did you push your commits? Still seeing text w/ comments on it

jelbourn

LGTM

amcdnl

Few nits

amcdnl · 2018-06-03T15:21:29Z

src/cdk-experimental/scrolling/virtual-scroll.md

+**Warning: this component is still experimental. It may have bugs and the API may change at any
+time**
+
+`<cdk-virtual-scroll-viewport>` displays large lists of elements performantly by only


I think we need to explain virtual scroll a little bit. I don't think people understand the difference between virtual scroll and infinite scroll. A idea gist.

Virtual scrolling enables developers to render large lists of data in a performant way. Loading hundreds of elements can be slow in any browser, virtual scrolling enables a performant want to simulate all items are rendered by making the height of the container element the total number of elements to be rendered and then only rendering the items in view. Virtual scroll is different from strategies like infinite scroll where it renders a set amount of elements and then when you hit the bottom renders the rest.

made some slight tweaks and merged with my sentence above

amcdnl · 2018-06-03T15:22:02Z

src/cdk-experimental/scrolling/virtual-scroll.md

+[see the demo app](https://github.com/angular/material2/tree/master/src/demo-app/virtual-scroll).
+
+### Creating items in the viewport
+`*cdkVirtualFor` replaces `*ngFor` inside of a `<cdk-virtual-scroll-viewport>`, supporting the exact


The replacement is mentioned right above this. Perhaps remove from one or the other?

amcdnl · 2018-06-03T15:22:35Z

src/cdk-experimental/scrolling/virtual-scroll.md

+connect process.
+
+### Scrolling over fixed size items
+When all items are the same fixed size,, you can use the `FixedSizeVirtualScrollStrategy`. This can


Two commas: fixed size,,

amcdnl · 2018-06-03T15:23:48Z

src/cdk-experimental/scrolling/virtual-scroll.md

+
+```html
+<cdk-virtual-scroll-viewport itemSize="50">
+  <div *cdkVirtualFor="let item of items;


You'd be surprised ....

amcdnl · 2018-06-03T15:24:19Z

src/cdk-experimental/scrolling/virtual-scroll.md

+</cdk-virtual-scroll-viewport>
+```
+
+A `trackBy` function can be specified and works the same as the `*ngFor` `trackBy`. The `index`


I feel like this trackBy is just randomly mentioned at the end here.

That's because trackBy isn't a context variable, so it didn't fit in the part above, but I do want to mention that it's still supported

amcdnl · 2018-06-03T15:25:09Z

src/cdk-experimental/scrolling/virtual-scroll.md

+portion.
+
+#### View recycling
+To improve rendering performance, `*cdkVirtualFor` caches previously created views after


Might be worth mentioning things like portals that are attached to the VCR can cause issues.

Might even put this at the end too. Its a implementation detail rather than something important for the user to know.

It can be important for the user to know depending on their use case, some components may not deal well with having their templates recycled.

It does sound like a good idea to mention somewhere that the ViewContainer is managed by the virtual-scroller and so any components that attempt to do things with it are going to run into issues. I'm not sure where the best place for this is... In the future I also think we could mark the views that are managed by the virtual scroll in order to play better with other components that may modify the ViewContainer

Probably put it at the bottom as a note.

amcdnl · 2018-06-03T15:26:30Z

src/cdk-experimental/scrolling/virtual-scroll.md

+content.
+
+```html
+<cdk-virtual-scroll-viewport autosize orientation="horizontal">


I'd generally discourage users from using autosize, thus removing it as the default on examples like this.

Fair enough, we don't want users putting autosize just because its less typing. If they know the itemSize it's going to be more performant.

amcdnl · 2018-06-03T15:26:53Z

src/cdk-experimental/scrolling/virtual-scroll.md

+</cdk-virtual-scroll-viewport>
+```
+
+The fixed size strategy also supports setting the buffer size, i.e. the number of items rendered


Whats the default buffer size?

amcdnl · 2018-06-03T15:28:03Z

src/cdk-experimental/scrolling/virtual-scroll.md

+
+```html
+<cdk-virtual-scroll-viewport itemSize="50">
+  ...


I think the examples should show the for in them, people like to just copy/paste.

I'll add full working embedded example code when I move this out of cdk-experimental

amcdnl · 2018-06-03T15:28:39Z

src/cdk-experimental/scrolling/virtual-scroll.md

+```
+
+#### Specifying data
+`*cdkVirtualFor` accepts data from an `Array`, `Observable<Array>`, or `DataSource`. The


I'd show an example code snippet here.

I'll add that once we move it into the cdk proper and have actual embedded examples

mmalerba · 2018-06-18T02:51:21Z

@jelbourn @amcdnl PTAL

addressed comments

jelbourn

LGTM

angular-automatic-lock-bot · 2019-09-09T03:02:32Z

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.}

mmalerba assigned amcdnl, jelbourn and crisbeto May 24, 2018

mmalerba requested review from amcdnl, jelbourn and crisbeto May 24, 2018 17:29

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label May 24, 2018

crisbeto reviewed May 24, 2018

View reviewed changes

jelbourn reviewed May 25, 2018

View reviewed changes

mmalerba force-pushed the vs-docs branch from bc100d1 to 816f225 Compare May 29, 2018 15:07

mmalerba added 4 commits May 29, 2018 08:50

docs(virtual-scroll): add initial documentation

9ba1e32

address comments

7a212f0

address comments

27a8ea4

address more comments

f650f29

jelbourn reviewed May 29, 2018

View reviewed changes

address even more comments

b870753

mmalerba force-pushed the vs-docs branch from 816f225 to b870753 Compare May 29, 2018 16:21

mmalerba added target: minor This PR is targeted for the next minor release pr: merge safe labels May 29, 2018

jelbourn approved these changes Jun 1, 2018

View reviewed changes

jelbourn added pr: lgtm action: merge The PR is ready for merge by the caretaker labels Jun 1, 2018

amcdnl previously requested changes Jun 3, 2018

View reviewed changes

andrewseguin removed the action: merge The PR is ready for merge by the caretaker label Jun 7, 2018

address comments

465a089

jelbourn approved these changes Jun 19, 2018

View reviewed changes

jelbourn added the action: merge The PR is ready for merge by the caretaker label Jun 19, 2018

jelbourn added the docs This issue is related to documentation label Jun 19, 2018

jelbourn merged commit 93b5e89 into angular:master Jun 19, 2018

victoriaaa234 pushed a commit that referenced this pull request Jul 25, 2018

docs(virtual-scroll): add initial documentation (#11496)

3c9beea

angular-automatic-lock-bot bot unassigned amcdnl Sep 9, 2019

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

docs(virtual-scroll): add initial documentation #11496

docs(virtual-scroll): add initial documentation #11496

Uh oh!

Conversation

mmalerba commented May 24, 2018

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jelbourn May 25, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

amcdnl 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!

jelbourn May 25, 2018 •

edited

Loading