From c90033b7ea654e63983dd7e30e5484f52191c20a Mon Sep 17 00:00:00 2001 From: Michael Bromley Date: Thu, 25 Nov 2021 14:19:06 +0100 Subject: [PATCH] docs(core): Update & expand docs on custom form input components --- .../developer-guide/customizing-models.md | 33 ++++- .../plugins/extending-the-admin-ui/_index.md | 2 +- .../_index.md | 116 +++++++++++++++--- .../ui-extensions-custom-field-default.jpg | Bin .../ui-extensions-custom-field-slider.jpg | Bin .../custom-field-component.service.ts | 2 + .../register-dynamic-input-components.ts | 5 +- packages/common/src/shared-types.ts | 2 +- 8 files changed, 135 insertions(+), 25 deletions(-) rename docs/content/plugins/extending-the-admin-ui/{custom-field-controls => custom-form-inputs}/_index.md (50%) rename docs/content/plugins/extending-the-admin-ui/{custom-field-controls => custom-form-inputs}/ui-extensions-custom-field-default.jpg (100%) rename docs/content/plugins/extending-the-admin-ui/{custom-field-controls => custom-form-inputs}/ui-extensions-custom-field-slider.jpg (100%) diff --git a/docs/content/developer-guide/customizing-models.md b/docs/content/developer-guide/customizing-models.md index d82863f35f..ea031c7034 100644 --- a/docs/content/developer-guide/customizing-models.md +++ b/docs/content/developer-guide/customizing-models.md @@ -55,6 +55,32 @@ mutation { } ``` +## CustomField UI Form Inputs + +By default, the Admin UI will use an appropriate input component depending on the `type` of the custom field. +For instance, `string` fields will use a `` component, and `boolean` fields will use a `` component. + +These defaults can be overridden by using the `ui` property of the custom field config object. For example, if we want a number to be displayed as a currency input: + +```TypeScript {hl_lines=[8]} +const config = { + // ... + customFields: { + ProductVariant: [ + { + name: 'rrp', + type: 'int', + ui: { component: 'currency-form-input' }, + }, + ] + } +} +``` + +The built-in form inputs are listed in the [DefaultFormConfigHash docs]({{< relref "default-form-config-hash" >}}). + +If you want to use a completely custom form input component which is not provided by the Admin UI, you'll need to create a plugin which [extends the Admin UI]({{< relref "extending-the-admin-ui" >}}) with [custom form inputs]({{< relref "custom-form-inputs" >}}). + ## TypeScript Typings Because custom fields are generated at run-time, TypeScript has no way of knowing about them based on your @@ -273,7 +299,9 @@ mutation { } } ``` -#### UI for relation type + +{{% alert %}} +**UI for relation type** The Admin UI app has built-in selection components for "relation" custom fields which reference certain common entity types, such as Asset, Product, ProductVariant and Customer. If you are relating to an entity not covered by the built-in selection components, you will instead see the message: @@ -281,4 +309,5 @@ The Admin UI app has built-in selection components for "relation" custom fields No input component configured for "" type ``` -In this case, you will need to create a UI extension which defines a custom field control for that custom field. You can read more about this in the [CustomField Controls guide]({{< relref "custom-field-controls" >}}) +In this case, you will need to create a UI extension which defines a custom field control for that custom field. You can read more about this in the [custom form input guide]({{< relref "custom-form-inputs" >}}) +{{< /alert >}} diff --git a/docs/content/plugins/extending-the-admin-ui/_index.md b/docs/content/plugins/extending-the-admin-ui/_index.md index 145a39f66b..576ea0920f 100644 --- a/docs/content/plugins/extending-the-admin-ui/_index.md +++ b/docs/content/plugins/extending-the-admin-ui/_index.md @@ -30,7 +30,7 @@ Angular uses the concept of modules ([NgModules](https://angular.io/guide/ngmodu When creating your UI extensions, you can set your module to be either `lazy` or `shared`. Shared modules are loaded _eagerly_, i.e. their code is bundled up with the main app and loaded as soon as the app loads. -As a rule, modules defining new routes should be lazily loaded (so that the code is only loaded once that route is activated), and modules defining [new navigations items]({{< relref "adding-navigation-items" >}}) and [CustomField controls]({{< relref "custom-field-controls" >}}) should be set to `shared`. +As a rule, modules defining new routes should be lazily loaded (so that the code is only loaded once that route is activated), and modules defining [new navigations items]({{< relref "adding-navigation-items" >}}) and [custom form input]({{< relref "custom-form-inputs" >}}) should be set to `shared`. ## Dev mode diff --git a/docs/content/plugins/extending-the-admin-ui/custom-field-controls/_index.md b/docs/content/plugins/extending-the-admin-ui/custom-form-inputs/_index.md similarity index 50% rename from docs/content/plugins/extending-the-admin-ui/custom-field-controls/_index.md rename to docs/content/plugins/extending-the-admin-ui/custom-form-inputs/_index.md index 71b76d75b2..5ce547dfa5 100644 --- a/docs/content/plugins/extending-the-admin-ui/custom-field-controls/_index.md +++ b/docs/content/plugins/extending-the-admin-ui/custom-form-inputs/_index.md @@ -1,11 +1,13 @@ --- -title: 'CustomField Controls' +title: 'Custom Form Inputs' weight: 5 --- -# CustomField Controls +# Custom Form Inputs -Another way to extend the Admin UI app is to define custom form control components for manipulating any [Custom Fields]({{< ref "/docs/typescript-api/custom-fields" >}}) you have defined on your entities. +Another way to extend the Admin UI app is to define custom form input components for manipulating any [Custom Fields]({{< ref "/docs/typescript-api/custom-fields" >}}) you have defined on your entities as well as [configurable args]({{< relref "config-args" >}}) used by custom [ConfigurableOperationDefs]({{< relref "configurable-operation-def" >}}). + +## For Custom Fields Let's say you define a custom "intensity" field on the Product entity: @@ -23,27 +25,27 @@ By default, the "intensity" field will be displayed as a number input: {{< figure src="./ui-extensions-custom-field-default.jpg" >}} -But let's say we want to display a range slider instead. Here's how we can do this using our shared extension module combined with the `registerCustomFieldComponent()` function: +But let's say we want to display a range slider instead. Here's how we can do this using our shared extension module combined with the `registerFormInputComponent()` function: ```TypeScript import { NgModule, Component } from '@angular/core'; import { FormControl } from '@angular/forms'; -import { SharedModule, CustomFieldControl, - CustomFieldConfigType, registerCustomFieldComponent } from '@vendure/admin-ui/core'; +import { CustomFieldConfig } from '@vendure/common/lib/generated-types'; +import { SharedModule, FormInputComponent, registerFormInputComponent } from '@vendure/admin-ui/core'; @Component({ template: ` {{ formControl.value }} `, }) -export class SliderControl implements CustomFieldControl { +export class SliderControl implements FormInputComponent { readonly: boolean; - config: CustomFieldConfigType; + config: CustomFieldConfig; formControl: FormControl; } @@ -51,23 +53,46 @@ export class SliderControl implements CustomFieldControl { imports: [SharedModule], declarations: [SliderControl], providers: [ - registerCustomFieldComponent('Product', 'intensity', SliderControl), + registerFormInputComponent('slider-form-input', SliderControl), ] }) -export class SharedExtensionModule { } +export class SharedExtensionModule {} ``` +Once registered, this new slider input can be used in our custom field config: + +```TypeScript {hl_lines=[7]} +// project/vendure-config.ts + +customFields: { + Product: [ + { + name: 'intensity', type: 'int', min: 0, max: 100, defaultValue: 0, + ui: { component: 'slider-form-input' } + }, + ], +} +``` +As we can see, adding the `ui` property to the custom field config allows us to specify our custom slider component. +The component id _'slider-form-input'_ **must match** the string passed as the first argument to `registerFormInputComponent()`. + +{{% alert %}} +If we want, we can also pass any other arbitrary data in the `ui` object, which will then be available in our component as `this.config.ui.myField`. Note that only JSON-compatible data types are permitted, so no functions or class instances. +{{< /alert >}} + + Re-compiling the Admin UI will result in our SliderControl now being used for the "intensity" custom field: {{< figure src="./ui-extensions-custom-field-slider.jpg" >}} To recap the steps involved: -1. Create an Angular Component which implements the `CustomFieldControl` interface. +1. Create an Angular Component which implements the `FormInputComponent` interface. 2. Add this component to your shared extension module's `declarations` array. -3. Use `registerCustomFieldComponent()` to register your component for the given entity & custom field name. +3. Use `registerFormInputComponent()` to register your component for the given entity & custom field name. +4. Specify this component's ID in your custom field config. -## Custom Field Controls for Relations +### Custom Field Controls for Relations If you have a custom field of the `relation` type (which allows you to relate entities with one another), you can also define custom field controls for them. The basic mechanism is exactly the same as with primitive custom field types (i.e. `string`, `int` etc.), but there are a couple of important points to know: @@ -77,9 +102,10 @@ If you have a custom field of the `relation` type (which allows you to relate en Here is a simple example taken from the [real-world-vendure](https://github.com/vendure-ecommerce/real-world-vendure/blob/master/src/plugins/reviews/ui/components/featured-review-selector/featured-review-selector.component.ts) repo: ```TypeScript -import { ChangeDetectionStrategy, Component, Input, OnInit } from '@angular/core'; +import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core'; import { FormControl } from '@angular/forms'; import { ActivatedRoute } from '@angular/router'; +import { RelationCustomFieldConfig } from '@vendure/common/lib/generated-types'; import { CustomFieldControl, DataService } from '@vendure/admin-ui/core'; import { Observable } from 'rxjs'; import { switchMap } from 'rxjs/operators'; @@ -107,10 +133,10 @@ import { GetReviewForProduct, ProductReviewFragment } from '../../generated-type `, changeDetection: ChangeDetectionStrategy.OnPush, }) -export class RelationReviewInputComponent implements OnInit, CustomFieldControl { - @Input() readonly: boolean; - @Input() formControl: FormControl; - @Input() config: any; +export class RelationReviewInputComponent implements OnInit, FormInputComponent { + readonly: boolean; + formControl: FormControl; + config: RelationCustomFieldConfig; reviews$: Observable; @@ -133,3 +159,53 @@ export class RelationReviewInputComponent implements OnInit, CustomFieldControl } } ``` + +### Legacy `registerCustomFieldComponent` + +Prior to v1.4, the function `registerCustomFieldComponent()` was used to register a form control for a custom field. This function has now been deprecated in favour of `registerFormInputComponent()`, but is kept for backward-compatibility and will be removed in v2.0. + +`registerCustomFieldComponent` is used like this: + +```TypeScript +import { NgModule, Component } from '@angular/core'; +import { SharedModule, registerCustomFieldComponent } from '@vendure/admin-ui/core'; + +// SliderControl component definition as above + +@NgModule({ + imports: [SharedModule], + declarations: [SliderControl], + providers: [ + registerCustomFieldComponent('Product', 'intensity', SliderControl), + ] +}) +export class SharedExtensionModule { } +``` + +## For ConfigArgs + +[ConfigArgs]({{< relref "config-args" >}}) are used by classes which extend [ConfigurableOperationDef]({{< relref "configurable-operation-def" >}}) (such as ShippingCalculator or PaymentMethodHandler). These ConfigArgs allow user-input values to be passed to the operation's business logic. + +They are configured in a very similar way to custom fields, and likewise can use custom form inputs by specifying the `ui` property. + +Here's an example: + +```TypeScript {hl_lines=[6,7,8]} +export const orderFixedDiscount = new PromotionOrderAction({ + code: 'order_fixed_discount', + args: { + discount: { + type: 'int', + ui: { + component: 'currency-form-input', + }, + }, + }, + execute(ctx, order, args) { + return -args.discount; + }, + description: [{ languageCode: LanguageCode.en, value: 'Discount order by fixed amount' }], +}); +``` + + diff --git a/docs/content/plugins/extending-the-admin-ui/custom-field-controls/ui-extensions-custom-field-default.jpg b/docs/content/plugins/extending-the-admin-ui/custom-form-inputs/ui-extensions-custom-field-default.jpg similarity index 100% rename from docs/content/plugins/extending-the-admin-ui/custom-field-controls/ui-extensions-custom-field-default.jpg rename to docs/content/plugins/extending-the-admin-ui/custom-form-inputs/ui-extensions-custom-field-default.jpg diff --git a/docs/content/plugins/extending-the-admin-ui/custom-field-controls/ui-extensions-custom-field-slider.jpg b/docs/content/plugins/extending-the-admin-ui/custom-form-inputs/ui-extensions-custom-field-slider.jpg similarity index 100% rename from docs/content/plugins/extending-the-admin-ui/custom-field-controls/ui-extensions-custom-field-slider.jpg rename to docs/content/plugins/extending-the-admin-ui/custom-form-inputs/ui-extensions-custom-field-slider.jpg diff --git a/packages/admin-ui/src/lib/core/src/providers/custom-field-component/custom-field-component.service.ts b/packages/admin-ui/src/lib/core/src/providers/custom-field-component/custom-field-component.service.ts index dcd875262e..182fc79187 100644 --- a/packages/admin-ui/src/lib/core/src/providers/custom-field-component/custom-field-component.service.ts +++ b/packages/admin-ui/src/lib/core/src/providers/custom-field-component/custom-field-component.service.ts @@ -13,6 +13,8 @@ export type CustomFieldEntityName = Exclude; /** * This service allows the registration of custom controls for customFields. + * + * @deprecated The ComponentRegistryService now handles custom field components directly. */ @Injectable({ providedIn: 'root', diff --git a/packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/register-dynamic-input-components.ts b/packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/register-dynamic-input-components.ts index 0de4bf5212..f553ba6237 100644 --- a/packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/register-dynamic-input-components.ts +++ b/packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/register-dynamic-input-components.ts @@ -41,7 +41,8 @@ export const defaultFormInputs = [ /** * @description * Registers a custom FormInputComponent which can be used to control the argument inputs - * of a {@link ConfigurableOperationDef} (e.g. CollectionFilter, ShippingMethod etc) + * of a {@link ConfigurableOperationDef} (e.g. CollectionFilter, ShippingMethod etc) or for + * a custom field. * * @example * ```TypeScript @@ -82,6 +83,8 @@ export function registerFormInputComponent(id: string, component: Type) | ({ component: 'customer-group-form-input' } & DefaultFormComponentConfig<'customer-group-form-input'>) - | { component: string; [prop: string]: any }; + | { component: string; [prop: string]: Json }; export type CustomFieldsObject = { [key: string]: any };