diff --git a/docs/en/UI/Angular/Custom-Setting-Page.md b/docs/en/UI/Angular/Custom-Setting-Page.md index 7c51cf2cca..6aa5d8a3cc 100644 --- a/docs/en/UI/Angular/Custom-Setting-Page.md +++ b/docs/en/UI/Angular/Custom-Setting-Page.md @@ -40,3 +40,7 @@ ngOnInit() { Navigate to `/setting-management` route to see the changes: ![Custom Settings Tab](./images/custom-settings.png) + +## What's Next? + +- [TrackByService](./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..4506f77e47 --- /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) {} +} +``` + + + +> 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 + + +
{%{{{ item.name }}}%}
+``` + + + +`by` is exported as a stand-alone function and is named `trackBy`. + +```js +import { trackBy } from "@abp/ng.core"; + +@Component({ + template: ` +
+ {%{{{ item.name }}}%} +
+ `, +}) +class DemoComponent { + list: Item[]; + + trackById = trackBy('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 + + +
+ {%{{{ item.tenant.name }}}%} +
+``` + + + +`byDeep` is exported as a stand-alone function and is named `trackByDeep`. + +```js +import { trackByDeep } from "@abp/ng.core"; + +@Component({ + template: ` +
+ {%{{{ item.name }}}%} +
+ `, +}) +class DemoComponent { + list: Item[]; + + trackByTenantAccountId = trackByDeep('tenant', 'account', 'id'); +} +``` + diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index a96fb911d2..425b8c526a 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -335,6 +335,10 @@ { "text": "Custom Setting Page", "path": "UI/Angular/Custom-Setting-Page.md" + }, + { + "text": "TrackByService", + "path": "UI/Angular/Track-By-Service.md" } ] }