Merge pull request #4526 from abpframework/docs/4525

Updated ListService documentation according to ngx-datatable

docs/en/UI/Angular/List-Service.md

@@ -53,59 +53,41 @@ class BookComponent {
 }
 ```
 
-> Noticed `list` is `public` and `readonly`? That is because we will use `ListService` properties directly in the component's template. That may be considered as an anti-pattern, but it is much quicker to implement. You can always use public component properties instead.
+> Noticed `list` is `public` and `readonly`? That is because we will use `ListService` directly in the component's template. That may be considered as an anti-pattern, but it is much quicker to implement. You can always use public component members to expose the `ListService` instance instead.
 
-Place `ListService` properties into the template like this:
+Bind `ListService` to ngx-datatable like this:
 
 ```html
-<abp-table
+<ngx-datatable
-  [value]="book.items"
+  [rows]="items"
-  [(page)]="list.page"
+  [count]="count"
-  [rows]="list.maxResultCount"
+  [list]="list"
-  [totalRecords]="book.totalCount"
+  default
-  [headerTemplate]="tableHeader"
-  [bodyTemplate]="tableBody"
-  [abpLoading]="list.isLoading$ | async"
 >
-</abp-table>
+  <!-- column templates here -->
-
+</ngx-datatable>
-<ng-template #tableHeader>
-  <tr>
-    <th (click)="nameSort.sort('name')">
-      {%{{{ '::Name' | abpLocalization }}}%}
-      <abp-sort-order-icon
-        #nameSort
-        sortKey="name"
-        [(selectedSortKey)]="list.sortKey"
-        [(order)]="list.sortOrder"
-      ></abp-sort-order-icon>
-    </th>
-  </tr>
-</ng-template>
-
-<ng-template #tableBody let-data>
-  <tr>
-    <td>{%{{{ data.name }}}%}</td>
-  </tr>
-</ng-template>
 ```
 
+
 ## Usage with Observables
 
 You may use observables in combination with [AsyncPipe](https://angular.io/guide/observables-in-angular#async-pipe) of Angular instead. Here are some possibilities:
 
-```ts
+```js
   book$ = this.list.hookToQuery(query => this.bookService.getListByInput(query));
 ```
 
 ```html
 <!-- simplified representation of the template -->
 
-<abp-table
+<ngx-datatable
-  [value]="(book$ | async)?.items || []"
+  [rows]="(book$ | async)?.items || []"
-  [totalRecords]="(book$ | async)?.totalCount"
+  [count]="(book$ | async)?.totalCount || 0"
+  [list]="list"
+  default
 >
-</abp-table>
+  <!-- column templates here -->
+</ngx-datatable>
 
 <!-- DO NOT WORRY, ONLY ONE REQUEST WILL BE MADE -->
 ```
@@ -113,7 +95,7 @@ You may use observables in combination with [AsyncPipe](https://angular.io/guide
 ...or...
 
 
-```ts
+```js
   @Select(BookState.getBooks)
   books$: Observable<BookDto[]>;
 
@@ -128,32 +110,41 @@ You may use observables in combination with [AsyncPipe](https://angular.io/guide
 ```html
 <!-- simplified representation of the template -->
 
-<abp-table
+<ngx-datatable
-  [value]="books$ | async"
+  [rows]="(books$ | async) || []"
-  [totalRecords]="bookCount$ | async"
+  [count]="(bookCount$ | async) || 0"
+  [list]="list"
+  default
 >
-</abp-table>
+  <!-- column templates here -->
+</ngx-datatable>
 ```
 
+> We donot recommend using NGXS store for CRUD pages, unless your application needs to share list information between components or use it later on in another page.
+
+
 ## How to Refresh Table on Create/Update/Delete
 
 `ListService` exposes a `get` method to trigger a request with the current query. So, basically, whenever a create, update, or delete action resolves, you can call `this.list.get();` and it will call hooked stream creator again.
 
-```ts
+```js
-this.store.dispatch(new DeleteBook(id)).subscribe(this.list.get);
+  this.bookService.createByInput(form.value)
+    .subscribe(() => {
+      this.list.get();
+
+      // Other subscription logic here
+    });
 ```
 
 ...or...
 
-```ts
+```js
-this.bookService.createByInput(form.value)
+  this.store.dispatch(new DeleteBook(id)).subscribe(this.list.get);
-  .subscribe(() => {
-    this.list.get();
-
-    // Other subscription logic here
-  })
 ```
 
+> We donot recommend using NGXS store for CRUD pages, unless your application needs to share list information between components or use it later on in another page.
+
+
 ## How to Implement Server-Side Search in a Table
 
 `ListService` exposes a `filter` property that will trigger a request with the current query and the given search string. All you need to do is to bind it to an input element with two-way binding.
@@ -163,3 +154,26 @@ this.bookService.createByInput(form.value)
 
 <input type="text" name="search" [(ngModel)]="list.filter">
 ```
+
+## Breaking Change with ABP v3.0
+
+We had to modify the `ListService` to make it work with `ngx-datatable`. Previously, the minimum value for `page` property was `1` and you could use it like this:
+
+```html
+<!-- other bindings are hidden in favor of brevity -->
+<abp-table
+  [(page)]="list.page"
+></abp-table>
+```
+
+As of v3.0, with ngx-datatable, the `page` property has to be set as `0` for inital page. Therefore, if you used `ListService` on your tables before and are going to keep `abp-table`, you need to make the following change:
+
+```html
+<!-- other bindings are hidden in favor of brevity -->
+<abp-table
+  [page]="list.page + 1"
+  (pageChange)="list.page = $event - 1"
+></abp-table>
+```
+
+**Important Note:** The `abp-table` is not removed, but is deprecated and will be removed in the future. Please consider switching to ngx-datatable.