From 56295b730704121c2c6734920136e7e167569494 Mon Sep 17 00:00:00 2001
From: Arman Ozak <arman@armanozak.com>
Date: Mon, 23 Mar 2020 21:08:44 +0300
Subject: [PATCH] docs(core): add how to create TrackByFunction using
 TrackByService

---
 docs/en/UI/Angular/Track-By-Service.md | 114 +++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/en/UI/Angular/Track-By-Service.md

diff --git a/docs/en/UI/Angular/Track-By-Service.md b/docs/en/UI/Angular/Track-By-Service.md
new file mode 100644
index 0000000000..4b8d2d8a1e
--- /dev/null
+++ b/docs/en/UI/Angular/Track-By-Service.md
@@ -0,0 +1,114 @@
+# Easy TrackByFunction Implementation
+
+`TrackByService` is a utility service to provide an easy implementation for one of the most frequent needs in Angular templates: `TrackByFunction`. Please see [this page in Angular docs](https://angular.io/guide/template-syntax#ngfor-with-trackby) for its purpose.
+
+
+
+## Getting Started
+
+You do not have to provide the `TrackByService` at module or component level, because it is already **provided in root**. You can inject and start using it immediately in your components. For better type support, you may pass in the type of the iterated item to it.
+
+```js
+import { TrackByService } from '@abp/ng.core';
+
+@Component({
+  /* class metadata here */
+})
+class DemoComponent {
+  list: Item[];
+
+  constructor(public readonly track: TrackByService<Item>) {}
+}
+```
+
+
+
+> Noticed `track` is `public` and `readonly`? That is because we will see some examples where methods of `TrackByService` instance are directly called in the component's template. That may be considered as an anti-pattern, but it has its own advantage, especially when component inheritance is leveraged. You can always use public component properties instead.
+
+
+
+**The members are also exported as separate functions.** If you do not want to inject `TrackByService`, you can always import and use those functions directly in your classes.
+
+
+
+## Usage
+
+There are two approaches available.
+
+1. You may inject `TrackByService` to your component and use its members.
+2. You may use exported higher-order functions directly on component properties.
+
+
+
+### How to Track Items by a Key
+
+You can use `by` to get a `TrackByFunction` that tracks the iterated object based on one of its keys. For type support, you may pass in the type of the iterated item to it.
+
+```html
+<!-- template of DemoComponent -->
+
+<div *ngFor="let item of list; trackBy: track.by('id')">{{ item.name }}</div>
+```
+
+
+
+`by` is exported as a stand-alone function and is named `trackBy`.
+
+```js
+import { trackBy } from "@abp/ng.core";
+
+@Component({
+  template: `
+    <div
+      *ngFor="let item of list; trackBy: trackById"
+    >
+      {{ item.name }}
+    </div>
+  `,
+})
+class DemoComponent {
+  list: Item[];
+
+  trackById = trackBy<Item>('id');
+}
+```
+
+
+
+### How to Track by a Deeply Nested Key
+
+You can use `byDeep` to get a `TrackByFunction` that tracks the iterated object based on a deeply nested key. For type support, you may pass in the type of the iterated item to it.
+
+```html
+<!-- template of DemoComponent -->
+
+<div
+  *ngFor="let item of list; trackBy: track.byDeep('tenant', 'account', 'id')"
+>
+  {{ item.tenant.name }}
+</div>
+```
+
+
+
+`byDeep` is exported as a stand-alone function and is named `trackByDeep`.
+
+```js
+import { trackByDeep } from "@abp/ng.core";
+
+@Component({
+  template: `
+    <div
+      *ngFor="let item of list; trackBy: trackByTenantAccountId"
+    >
+      {{ item.name }}
+    </div>
+  `,
+})
+class DemoComponent {
+  list: Item[];
+
+  trackByTenantAccountId = trackByDeep<Item>('tenant', 'account', 'id');
+}
+```
+