Skip to content

Commit a2ed659

Browse files
farfromrefugfarfromrefug
committed
chore: readme update
1 parent bb52a55 commit a2ed659

File tree

1 file changed

+58
-39
lines changed

1 file changed

+58
-39
lines changed

‎packages/collectionview/README.md‎

Lines changed: 58 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,13 @@
77
A NativeScript CollectionView widget. The CollectionView displays data in separate cells, each cell representing one data item. For iOS wraps up [UICollectionView](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UICollectionView_class/) and for Android wraps up [RecyclerView](https://developer.android.com/reference/android/support/v7/widget/RecyclerView.html). This can be used as an Open Source alternative to [RadListView](https://docs.nativescript.org/ui/components/radlistview/overview).
88

99
| <img src="images/demo-ios.gif" height="500" /> | <img src="images/demo-android.gif" height="500" /> |
10-
| --- | ----------- |
11-
| iOS Demo | Android Demo |
10+
| ---------------------------------------------- | -------------------------------------------------- |
11+
| iOS Demo | Android Demo |
1212

1313
---
14+
1415
## Table of Contents
16+
1517
1. [Installation](#installation)
1618
2. [Configuration](#configuration)
1719
3. [API](#api)
@@ -23,43 +25,53 @@ A NativeScript CollectionView widget. The CollectionView displays data in separa
2325
9. [Demos](#demos)
2426

2527
## Installation
28+
2629
Run the following command from the root of your project:
2730

2831
`ns plugin add @nativescript-community/ui-collectionview`
2932

3033
This command automatically installs the necessary files, as well as stores @nativescript-community/ui-collectionview as a dependency in your project's package.json file.
3134

3235
## Configuration
36+
3337
There is no additional configuration needed!
3438

3539
## API
3640

3741
### Events
3842

39-
| Property | Description |
40-
| ------------------- | ---------------------------------------------------------------------------- |
41-
| itemLoading | Triggered when generating an item in the CollectionView. |
42-
| itemTap | Triggered when the user taps on an item in the CollectionView. |
43-
| loadMoreItems | Triggered when the generated items reached the end of the items property. |
44-
| scroll | Triggered on collectionview scroll. |
45-
| scrollEnd | Triggered on collectionview scroll end. |
46-
| itemReorderStarting | Triggered when a reorder is starting. Changing the `returnValue` of the event data allows you to cancel it |
47-
| itemReorderStarted | Triggered when a reorder started. |
48-
| itemReordered | Triggered when a reorder finished. |
49-
| dataPopulated | Triggered when a refresh has been called. |
50-
51-
43+
| Property | Description |
44+
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
45+
| itemLoading | Triggered when generating an item in the CollectionView. |
46+
| itemTap | Triggered when the user taps on an item in the CollectionView. |
47+
| loadMoreItems | Triggered when the generated items reached the end of the items property. |
48+
| scroll | Triggered on collectionview scroll. |
49+
| scrollEnd | Triggered on collectionview scroll end. |
50+
| itemReorderStarting | Triggered when a reorder is starting. Changing the `returnValue` of the event data allows you to cancel it |
51+
| itemReorderStarted | Triggered when a reorder started. |
52+
| itemReordered | Triggered when a reorder finished. |
53+
| dataPopulated | Triggered when a refresh has been called. |
5254

5355
### Properties
5456

55-
| Property | Type | Description |
56-
| ------------- | ------------------------------------------------ | ------------------------------------------------------- |
57-
| ios | [UICollectionView](https://tinyurl.com/y4ugbfgc) | Gets the native iOS view that represents the user interface for this component. Valid only when running on iOS. |
58-
| android | [android.support.v7.widget.RecyclerView](https://tinyurl.com/lvqebpq) | Gets the native android widget that represents the user interface for this component. Valid only when running on Android OS. |
59-
| items | `array` or `ItemsSource` | Gets or sets the items collection of the CollectionView. The items property can be set to an array or an object defining length and getItem(index) method. |
60-
| itemTemplate | `string` | Gets or sets the item template of the CollectionView. |
61-
| rowHeight | `PercentLength` | Gets or sets the height for every row in the CollectionView. |
62-
| colWidth | `PercentLength` | Gets or sets the width for every column in the CollectionView. |
57+
| Property | Type | Description |
58+
| ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
59+
| ios | [UICollectionView](https://tinyurl.com/y4ugbfgc) | Gets the native iOS view that represents the user interface for this component. Valid only when running on iOS. |
60+
| android | [android.support.v7.widget.RecyclerView](https://tinyurl.com/lvqebpq) | Gets the native android widget that represents the user interface for this component. Valid only when running on Android OS. |
61+
| items | `array` or `ItemsSource` | Gets or sets the items collection of the CollectionView. The items property can be set to an array or an object defining length and getItem(index) method. |
62+
| itemTemplate | `string` | Gets or sets the item template of the CollectionView. |
63+
| rowHeight | `PercentLength` | Gets or sets the height for every row in the CollectionView. |
64+
| colWidth | `PercentLength` | Gets or sets the width for every column in the CollectionView. |
65+
| spanSize | `Function` | Function to return the span of a cell. For example with `colWidth:50%` a cell with a spanSize of 2 will be `100%` in width |
66+
| orientation | `'horizontal' | 'vertical'` | Set the orientation for the collectionView |
67+
| isBounceEnabled | `boolean` | (iOS) enable/disable CollectionView bounce |
68+
| isScrollEnabled | `boolean` | enable/disable CollectionView scroll |
69+
| reverseLayout | `boolean` | enable/disable CollectionView reversed layout (for message like views) |
70+
| loadMoreThreshold | `number` | set the loadMore threshold (called on the `item.length - loadMoreThreshold` item appearing) |
71+
| reorderEnabled | `boolean` | enable/disable CollectionView reorder feature |
72+
| reorderLongPressEnabled | `boolean` | enable/disable CollectionView longpress to reorder |
73+
| scrollBarIndicatorVisible | `boolean` | enable/disable CollectionView scrollBars |
74+
| nestedScrollingEnabled | `boolean` | (Android) enable/disable CollectionView nested scrolling |
6375

6476
### Methods
6577

@@ -69,6 +81,7 @@ There is no additional configuration needed!
6981
| scrollToIndex(index: number, animated: boolean = true) | `void` | Scrolls the CollectionView to the item with the given index. This can be either animated or not. Defaults to animated. |
7082

7183
## Usage
84+
7285
You need to add `xmlns:gv="@nativescript-community/ui-collectionview"` to your page tag, and then simply use `<gv:CollectionView/>` in order to add the widget to your page. Use `<gv:Gridview.itemTemplate/>` to specify the template for each cell:
7386

7487
### Simple Example:
@@ -104,9 +117,11 @@ const items = [
104117
```
105118

106119
### Templates Example:
120+
107121
You can also have multiple templates the same way you add them in the builtin `ListView` control:
122+
108123
```xml
109-
<gv:CollectionView id="gv" row="0" class="{{ cssClass }}" items="{{ items }}"
124+
<gv:CollectionView id="gv" row="0" class="{{ cssClass }}" items="{{ items }}"
110125
colWidth="{{ colWidth }}" rowHeight="{{ rowHeight }}" itemTemplateSelector="templateSelector"
111126
itemTap="gridViewItemTap" itemLoading="gridViewItemLoading" loadMoreItems="gridViewLoadMoreItems">
112127
<gv:CollectionView.itemTemplates>
@@ -125,9 +140,10 @@ You can also have multiple templates the same way you add them in the builtin `L
125140
</gv:CollectionView.itemTemplates>
126141
</gv:CollectionView>
127142
```
143+
128144
```ts
129145
export function templateSelector(item: any, index: number, items: any) {
130-
return index % 2 === 0 ? "even" : "odd";
146+
return index % 2 === 0 ? 'even' : 'odd';
131147
}
132148
```
133149

@@ -144,6 +160,7 @@ import { CollectionViewModule } from '@nativescript-community/ui-collectionview/
144160
],
145161
})
146162
```
163+
147164
### Simple Example:
148165

149166
Create a simple array of objects in your Typescript file.
@@ -164,6 +181,7 @@ items = [
164181
```
165182

166183
Add the following to your component HTML.
184+
167185
```xml
168186
<CollectionView [items]="items" colWidth="50%" rowHeight="100">
169187
<ng-template let-item="item">
@@ -173,30 +191,32 @@ Add the following to your component HTML.
173191
```
174192

175193
### Templates Example:
194+
176195
If you want to use multiple item templates, you can do that very similarly to how you do it for the builtin `ListView` control. The only difference is that due to current limitations instead of using the `nsTemplateKey` directive you need to use the `cvTemplateKey` directive that comes from the CollectionView. (In a future version, once the framework allows it this will be changed and you will be able to use the same directive for the `CollectionView` as well)
196+
177197
```html
178198
<CollectionView row="1" [items]="items" colWidth="33%" rowHeight="100" [itemTemplateSelector]="templateSelector">
179199
<ng-template cvTemplateKey="Defender" let-item="item" let-odd="odd">
180200
<StackLayout [nsRouterLink]="['/item', item.id]" borderColor="blue" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
181-
<Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
201+
<label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></label>
182202
</StackLayout>
183203
</ng-template>
184204

185205
<ng-template cvTemplateKey="Goalkeeper" let-item="item" let-odd="odd">
186206
<StackLayout [nsRouterLink]="['/item', item.id]" borderColor="black" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
187-
<Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
207+
<label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></label>
188208
</StackLayout>
189209
</ng-template>
190210

191211
<ng-template cvTemplateKey="Midfielder" let-item="item" let-odd="odd">
192212
<StackLayout [nsRouterLink]="['/item', item.id]" borderColor="yellow" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
193-
<Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
213+
<label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></label>
194214
</StackLayout>
195215
</ng-template>
196216

197217
<ng-template cvTemplateKey="Forward" let-item="item" let-odd="odd">
198218
<StackLayout [nsRouterLink]="['/item', item.id]" borderColor="red" borderWidth="2" borderRadius="5" verticalAlignment="stretch" class="list-group-item" [class.odd]="odd">
199-
<Label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></Label>
219+
<label verticalAlignment="center" [text]="item.name" class="list-group-item-text" textWrap="true"></label>
200220
</StackLayout>
201221
</ng-template>
202222
</CollectionView>
@@ -214,6 +234,7 @@ Vue.use(CollectionView);
214234
```
215235

216236
### Simple Example:
237+
217238
In your component, add the following to make a simple array of objects.
218239

219240
```typescript
@@ -235,7 +256,7 @@ export default {
235256
return {
236257
itemList: items
237258
};
238-
},
259+
}
239260
// ...
240261
};
241262
```
@@ -289,8 +310,8 @@ const items = [
289310
Then add the following XML to your component:
290311

291312
```xml
292-
<collectionView
293-
{items}
313+
<collectionView
314+
{items}
294315
colWidth="50%"
295316
rowHeight="100"
296317
>
@@ -337,21 +358,19 @@ interface Item {
337358
color: string;
338359
}
339360

340-
const cellFactory = (item: Item) => (
341-
<label text={item.name} />
342-
);
361+
const cellFactory = (item: Item) => <label text={item.name} />;
343362

344363
export function First() {
345-
return (
346-
<CollectionView items={items} colWidth="50%" rowHeight="100" cellFactory={cellFactory} width="100%" height="100%" />
347-
);
364+
return <CollectionView items={items} colWidth="50%" rowHeight="100" cellFactory={cellFactory} width="100%" height="100%" />;
348365
}
349366
```
350367

351368
For a more complete example, look in the `demo-react` directory.
352369

353370
## Demos
371+
354372
This repository includes Angular, Vue.js, and Svelte demos. In order to run these execute the following in your shell:
373+
355374
```shell
356375
$ git clone https://github.com/@nativescript-community/ui-collectionview
357376
$ cd ui-collectionview
@@ -360,4 +379,4 @@ $ npm run setup
360379
$ npm run build # && npm run build.angular
361380
$ cd demo-ng # or demo-vue or demo-svelte
362381
$ ns run ios|android
363-
```
382+
```

0 commit comments

Comments
 (0)