Permalink
Browse files

Improve the documentation for ListView and ListViewDataSource

Summary:
What existing problem does the pull request solve?
My motivation was to improve the documentation for ListView and ListViewDataSource because I always have trouble remembering how they work and the documentation was lacking an example for `cloneWithRowsAndSections`

My PR does the following:
* add a note about how headers and footers are rendered on a horizontal ListView
* fix a typo in an example
* clarify that the sectionIdentities should match the keys or array indexes of the data source
* add an example of cloneWithRowsAndSections
* add notes on the return values of `getRowCount` and `getRowAndSectionCount`

n/a; documentation only

![screenshot of ListViewDataSource changes](https://cloud.githubusercontent.com/assets/580060/25768881/d339544a-31c1-11e7-88a1-5e60bc008500.png)
Closes #13811

Differential Revision: D5473192

Pulled By: hramos

fbshipit-source-id: f31fc6edfdeb8dff75d39bbcceda06fd839df934
  • Loading branch information...
gwmccull authored and facebook-github-bot committed Jul 21, 2017
1 parent 436218b commit 8117fa16c90c0462131f310e8e8f3290e229fc01
Showing with 23 additions and 3 deletions.
  1. +2 −0 Libraries/Lists/ListView/ListView.js
  2. +21 −3 Libraries/Lists/ListView/ListViewDataSource.js
@@ -173,6 +173,8 @@ var ListView = createReactClass({
* on every render pass. If they are expensive to re-render, wrap them
* in StaticContainer or other mechanism as appropriate. Footer is always
* at the bottom of the list, and header at the top, on every render pass.
* In a horizontal ListView, the header is rendered on the left and the
* footer on the right.
*/
renderFooter: PropTypes.func,
renderHeader: PropTypes.func,
@@ -62,7 +62,7 @@ type ParamType = {
*
* ```
* getInitialState: function() {
* var ds = new ListViewDataSource({rowHasChanged: this._rowHasChanged});
* var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
* return {ds};
* },
* _onDataArrived(newData) {
@@ -154,11 +154,19 @@ class ListViewDataSource {
* you also specify what your `sectionIdentities` are. If you don't care
* about sections you should safely be able to use `cloneWithRows`.
*
* `sectionIdentities` is an array of identifiers for sections.
* ie. ['s1', 's2', ...]. If not provided, it's assumed that the
* `sectionIdentities` is an array of identifiers for sections.
* ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes
* of the data you wish to include. If not provided, it's assumed that the
* keys of dataBlob are the section identities.
*
* Note: this returns a new object!
*
* ```
* const dataSource = ds.cloneWithRowsAndSections({
* addresses: ['row 1', 'row 2'],
* phone_numbers: ['data 1', 'data 2'],
* }, ['phone_numbers']);
* ```
*/
cloneWithRowsAndSections(
dataBlob: any,
@@ -207,10 +215,20 @@ class ListViewDataSource {
return newSource;
}
/**
* Returns the total number of rows in the data source.
*
* If you are specifying the rowIdentities or sectionIdentities, then `getRowCount` will return the number of rows in the filtered data source.
*/
getRowCount(): number {
return this._cachedRowCount;
}
/**
* Returns the total number of rows in the data source (see `getRowCount` for how this is calculated) plus the number of sections in the data.
*
* If you are specifying the rowIdentities or sectionIdentities, then `getRowAndSectionCount` will return the number of rows & sections in the filtered data source.
*/
getRowAndSectionCount(): number {
return this._cachedRowCount + this.sectionIdentities.length;
}

0 comments on commit 8117fa1

Please sign in to comment.