diff --git a/docs/user-guide/apa-extensions.md b/docs/user-guide/apa-extensions.md index 7e774c3f3d..6c9c7db1d7 100644 --- a/docs/user-guide/apa-extensions.md +++ b/docs/user-guide/apa-extensions.md @@ -4,16 +4,18 @@ Added: v4.1.0 --- ## Form Extensibility for APA Form Widget + This page describes how you can customize ADF forms to your own specification. ## Contents + There are two ways to customize the form - [Replace default form widgets with custom components](#replace-default-form-widgets-with-apa-form-widgets) - [Replace custom form widget with custom components](#replace-custom-form-widgets-with-custom-components) ## Replace default form widgets with APA form widgets -This is an example of replacing the standard `Text` [widget](../../lib/testing/src/lib/core/pages/form/widgets/widget.ts) with a custom component for all APA forms rendered within the `` component. +This is an example of replacing the standard `Text` with a custom component for all APA forms rendered within the `` component. 1. Create a simple form with some `Text` widgets: @@ -24,8 +26,10 @@ This is an example of replacing the standard `Text` [widget](../../lib/testing/s ```ts import { Component } from '@angular/core'; import { WidgetComponent } from '@alfresco/adf-core'; + @Component({ selector: 'custom-editor', + standalone: true, template: `
Look, I'm a APA custom editor!
` @@ -33,40 +37,14 @@ This is an example of replacing the standard `Text` [widget](../../lib/testing/s export class CustomEditorComponent extends WidgetComponent {} ``` -2. Add it to the application module or any custom module that is imported into the application one: +2. Import the [`FormRenderingService`](../core/services/form-rendering.service.md) in the feature module, or application module (recommended: `ProcessServicesExtensionModule`), and override the default mapping: ```ts - import { NgModule } from '@angular/core'; import { CustomEditorComponent } from './custom-editor.component'; - @NgModule({ - declarations: [ CustomEditorComponent ], - exports: [ CustomEditorComponent ] - }) - export class CustomEditorsModule {} - ``` - -3. Every custom widget component should be added into the the collections `declarations` and `exports`. If you decided to store custom widgets in a separate dedicated module (and optionally as a separate re-distributable library) don't forget to import it into the main application: - - ```ts - @NgModule({ - imports: [ - // ... - CustomEditorsModule - // ... - ], - providers: [], - bootstrap: [ AppComponent ] - }) - export class AppModule {} - ``` - -4. Import the [`FormRenderingService`](../core/services/form-rendering.service.md) into any of your Views and override the default mapping, for example: - - ```ts - import { Component } from '@angular/core'; - import { CustomEditorComponent } from './custom-editor.component'; - @Component({...}) - export class MyView { + import { FormRenderingService } from '@alfresco/adf-core'; + + @NgModule({...}) + export class ProcessServicesExtensionModule { constructor(formRenderingService: FormRenderingService) { this.formRenderingService.register({ 'text': () => CustomEditorComponent @@ -75,10 +53,12 @@ This is an example of replacing the standard `Text` [widget](../../lib/testing/s } ``` -5. At runtime the form should look similar to the following: +> [!IMPORTANT] +> The widget should be registered outside the custom widget component, otherwise the widget will not be registered correctly. - ![custom text widget](../docassets/images/apa-simple-override-form.png) +At runtime the form should look similar to the following: +![custom text widget](../docassets/images/apa-simple-override-form.png) ## Replace custom form widgets with custom components @@ -105,54 +85,30 @@ When displayed in a task, the field will look similar to the following: To render the missing content: -1. Create an Angular component: +1. Create a standalone Angular component: ```ts import { Component } from '@angular/core'; import { WidgetComponent } from '@alfresco/adf-core'; + @Component({ selector: 'app-demo-widget', + standalone: true, template: `
ADF version of custom form widget
` }) export class DemoWidgetComponent extends WidgetComponent {} ``` -2. Place it inside the custom module: +2. Import the [`FormRenderingService`](../core/services/form-rendering.service.md) in the feature module, or application module (recommended: `ProcessServicesExtensionModule`), and override the default mapping: ```ts - import { NgModule } from '@angular/core'; import { DemoWidgetComponent } from './demo-widget.component'; - @NgModule({ - declarations: [ DemoWidgetComponent ], - exports: [ DemoWidgetComponent ] - }) - export class CustomWidgetsModule {} - ``` - -3. Import it into your Application Module: - - ```ts - @NgModule({ - imports: [ - // ... - CustomWidgetsModule - // ... - ], - providers: [], - bootstrap: [ AppComponent ] - }) - export class AppModule {} - ``` - -4. Import the [`FormRenderingService`](../core/services/form-rendering.service.md) in any of your Views and provide the new mapping: - - ```ts - import { Component } from '@angular/core'; - import { DemoWidgetComponent } from './demo-widget.component'; - @Component({...}) - export class MyView { + import { FormRenderingService } from '@alfresco/adf-core'; + + @NgModule({/*...*/}) + export class ProcessServicesExtensionModule { constructor(formRenderingService: FormRenderingService) { - this.formRenderingService.register({ + formRenderingService.register({ 'custom-editor': () => DemoWidgetComponent }); } @@ -163,6 +119,9 @@ At runtime you should now see your custom Angular component rendered in place of ![adf form widget runtime](../docassets/images/apa-resolved-widget.png) +> [!IMPORTANT] +> The widget should be registered outside the custom widget component, otherwise the widget will not be registered correctly. + ## See Also - [Extensibility](./extensibility.md)