diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 3dbd7cbe97..7e735695d9 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -1503,6 +1503,10 @@ { "text": "Lookup Components(Pro)", "path": "framework/ui/angular/lookup-components.md" + }, + { + "text": "Entity Filters(Pro)", + "path": "framework/ui/angular/entity-filters.md" } ] } diff --git a/docs/en/framework/ui/angular/entity-filters.md b/docs/en/framework/ui/angular/entity-filters.md new file mode 100644 index 0000000000..75a197b81b --- /dev/null +++ b/docs/en/framework/ui/angular/entity-filters.md @@ -0,0 +1,143 @@ +# Entity Filters + +Every CRUD page includes some sort of inputs to filter the listed data. Some of the inputs are common among all of the entities like the `Search` box. In addition, every entity has its own advanced filters depending on its fields. To reduce the amount of code written on every CRUD page, the Angular UI of ABP Commercial introduces a new type of component called `abp-advanced-entity-filters` + +## Setup + +The components are in the _@volo/abp.commercial.ng.ui_ package, which is included in the ABP templates. So, as long as your project is a product of these templates and unless you delete the package, you have access to the entity filter components. +You can either import the `CommercialUiModule` which contains other components as well as `AdvancedEntityFilters` or you can directly import the `AdvancedEntityFiltersModule` if you do not need other components. Here is how you import them in your Angular module: + +```javascript +import { + CommercialUiModule, + AdvancedEntityFiltersModule, +} from "@volo/abp.commercial.ng.ui"; + +@NgModule({ + imports: [ + // other imports + CommercialUiModule, + + // OR + + AdvancedEntityFiltersModule, + ], + // rest of the module metadata +}) +export class YourModule {} +``` + +## Usage + +Let's take a look at the `Users` page from the `Identity` module. + +![ABP Angular UI Users Page with Advanced Entity Filters](./images/angular-advanced-entity-filters.png) + +As shown in the screenshot, `abp-advanced-entity-filters` usually contain two parts, an entity filter (common among entities), i.e. `abp-entity-filter`, and entity-specific filters which are encapsulated within the `abp-advanced-entity-filters-form` component. + +`users.component.html` + +```html + + +
+
+ + +
+
+
+ +
+
+ +
+
+
+
+
+ + +``` + +The `abp-advanced-entity-filters` already contains the `abp-entity-filter` component so you do not need to pass it. However, the `abp-entity-filter` component needs an instance of `ListService` which is usually stored in the `list` field of the page. You can also change the placeholder of the component via `entityFilterPlaceholder` input which is passed into the `abpLocalization` pipe so that it uses the translated text. Default is `'AbpUi::PagerSearch'` + +E.g + +```html + + + +``` + +### Inputs + +- `list`: an instance of `ListService` +- `entityFilterPlaceholder`: the placeholder of `abp-entity-filter` component. Default: `'AbpUi::PagerSearch'` +- `localizationSourceName`: the localization source of the current page. E.g: `AbpIdentity` + +### Inner components + +Some entities are simple and do not require any filter other than the `abp-entity-filter`. In this case, you can simply use the `abp-advanced-entity-filters` without anything in between. + +E.g. + +Let's remove `form` from the `Users` page + +```html + + +``` + +![ABP Angular UI Users Page with Advanced Entity Filters without form](./images/angular-advanced-entity-filters-without-form.png) + +If your component needs other filters, you can pass your own `form` within the `abp-advanced-entity-filters-form` component. This will render your form as well as a toggle (`abp-advanced-entity-filters-toggle`) to show and hide the form + +E.g. + +```html + + +
+ +
+ + +``` + +![ABP Angular UI Users Page with Advanced Entity Filters with form](./images/angular-advanced-entity-filters-with-form.png) + +Last but not least, if you need to render some content above the `abp-entity-filter` component, you can use the `abp-advanced-entity-filters-above-search`. + +E.g. + +```html + + +

Custom Content above entity-filter

+ + + +
+ +
+ + +``` + +![ABP Angular UI Users Page with Advanced Entity Filters with custom content above filter](./images/angular-advanced-entity-filters-with-custom-content-above-filter.png) diff --git a/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-with-custom-content-above-filter.png b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-with-custom-content-above-filter.png new file mode 100644 index 0000000000..0feab57342 Binary files /dev/null and b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-with-custom-content-above-filter.png differ diff --git a/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-with-form.png b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-with-form.png new file mode 100644 index 0000000000..ef469a3d9d Binary files /dev/null and b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-with-form.png differ diff --git a/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-without-form.png b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-without-form.png new file mode 100644 index 0000000000..18b7780008 Binary files /dev/null and b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters-without-form.png differ diff --git a/docs/en/framework/ui/angular/images/angular-advanced-entity-filters.png b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters.png new file mode 100644 index 0000000000..3f381a1cc6 Binary files /dev/null and b/docs/en/framework/ui/angular/images/angular-advanced-entity-filters.png differ