diff --git a/docs/docassets/images/aae-form-widget.png b/docs/docassets/images/apa-form-widget.png similarity index 100% rename from docs/docassets/images/aae-form-widget.png rename to docs/docassets/images/apa-form-widget.png diff --git a/docs/docassets/images/aae-form-with-widget.png b/docs/docassets/images/apa-form-with-widget.png similarity index 100% rename from docs/docassets/images/aae-form-with-widget.png rename to docs/docassets/images/apa-form-with-widget.png diff --git a/docs/docassets/images/aae-resolved-widget.png b/docs/docassets/images/apa-resolved-widget.png similarity index 100% rename from docs/docassets/images/aae-resolved-widget.png rename to docs/docassets/images/apa-resolved-widget.png diff --git a/docs/docassets/images/aae-simple-form.png b/docs/docassets/images/apa-simple-form.png similarity index 100% rename from docs/docassets/images/aae-simple-form.png rename to docs/docassets/images/apa-simple-form.png diff --git a/docs/docassets/images/aae-simple-override-form.png b/docs/docassets/images/apa-simple-override-form.png similarity index 100% rename from docs/docassets/images/aae-simple-override-form.png rename to docs/docassets/images/apa-simple-override-form.png diff --git a/docs/docassets/images/aae-unresolved-widget.png b/docs/docassets/images/apa-unresolved-widget.png similarity index 100% rename from docs/docassets/images/aae-unresolved-widget.png rename to docs/docassets/images/apa-unresolved-widget.png diff --git a/docs/user-guide/aae-extensions.md b/docs/user-guide/aae-extensions.md index 743dd6153a..453dd7244b 100644 --- a/docs/user-guide/aae-extensions.md +++ b/docs/user-guide/aae-extensions.md @@ -1,23 +1,23 @@ --- -Title: Form Extensibility for AAE Form Widget +Title: Form Extensibility for APA Form Widget Added: v4.1.0 --- -## Form Extensibility for AAE Form Widget +## 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-aae-form-widgets) +- [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 AAE form widgets +## 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 AAE forms rendered within the `` component. +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. 1. Create a simple form with some `Text` widgets: - ![default text widget](../docassets/images/aae-simple-form.png) + ![default text widget](../docassets/images/apa-simple-form.png) Every custom widget component must inherit the [`WidgetComponent`](../insights/components/widget.component.md) class in order to function properly: @@ -27,7 +27,7 @@ This is an example of replacing the standard `Text` [widget](../../lib/testing/s @Component({ selector: 'custom-editor', template: ` -
Look, I'm a AAE custom editor!
+
Look, I'm a APA custom editor!
` }) export class CustomEditorComponent extends WidgetComponent {} @@ -77,7 +77,7 @@ This is an example of replacing the standard `Text` [widget](../../lib/testing/s 5. At runtime the form should look similar to the following: - ![custom text widget](../docassets/images/aae-simple-override-form.png) + ![custom text widget](../docassets/images/apa-simple-override-form.png) ## Replace custom form widgets with custom components @@ -88,19 +88,19 @@ This is an example of rendering custom form widgets using custom Angular compone To begin, create a basic form widget and call it `demo-widget`: -![custom form widget](../docassets/images/aae-form-widget.png) +![custom form widget](../docassets/images/apa-form-widget.png) **Note**: The `type` is important as it will become the `field type` when the form is rendered. You can now design a form that uses your custom form widget: -![custom form widget form](../docassets/images/aae-form-with-widget.png) +![custom form widget form](../docassets/images/apa-form-with-widget.png) ### Create a custom widget When displayed in a task, the field will look similar to the following: -![adf form widget](../docassets/images/aae-unresolved-widget.png) +![adf form widget](../docassets/images/apa-unresolved-widget.png) To render the missing content: @@ -161,7 +161,7 @@ To render the missing content: At runtime you should now see your custom Angular component rendered in place of the original form widgets: -![adf form widget runtime](../docassets/images/aae-resolved-widget.png) +![adf form widget runtime](../docassets/images/apa-resolved-widget.png) ## See Also diff --git a/docs/user-guide/apa-extensions.md b/docs/user-guide/apa-extensions.md new file mode 100644 index 0000000000..453dd7244b --- /dev/null +++ b/docs/user-guide/apa-extensions.md @@ -0,0 +1,172 @@ +--- +Title: Form Extensibility for APA Form Widget +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. + +1. Create a simple form with some `Text` widgets: + + ![default text widget](../docassets/images/apa-simple-form.png) + + Every custom widget component must inherit the [`WidgetComponent`](../insights/components/widget.component.md) class in order to function properly: + + ```ts + import { Component } from '@angular/core'; + import { WidgetComponent } from '@alfresco/adf-core'; + @Component({ + selector: 'custom-editor', + template: ` +
Look, I'm a APA custom editor!
+ ` + }) + export class CustomEditorComponent extends WidgetComponent {} + ``` + +2. Add it to the application module or any custom module that is imported into the application one: + + ```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 { + constructor(formRenderingService: FormRenderingService) { + this.formRenderingService.register({ + 'text': () => CustomEditorComponent + }, true); + } + } + ``` + +5. 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 + +This is an example of rendering custom form widgets using custom Angular components. + +### Create a custom form widget + +To begin, create a basic form widget and call it `demo-widget`: + +![custom form widget](../docassets/images/apa-form-widget.png) + +**Note**: The `type` is important as it will become the `field type` when the form is rendered. + +You can now design a form that uses your custom form widget: + +![custom form widget form](../docassets/images/apa-form-with-widget.png) + +### Create a custom widget + +When displayed in a task, the field will look similar to the following: + +![adf form widget](../docassets/images/apa-unresolved-widget.png) + + +To render the missing content: + +1. Create an Angular component: + + ```ts + import { Component } from '@angular/core'; + import { WidgetComponent } from '@alfresco/adf-core'; + @Component({ + selector: 'app-demo-widget', + template: `
ADF version of custom form widget
` + }) + export class DemoWidgetComponent extends WidgetComponent {} + ``` + +2. Place it inside the custom module: + + ```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 { + constructor(formRenderingService: FormRenderingService) { + this.formRenderingService.register({ + 'custom-editor': () => DemoWidgetComponent + }); + } + } + ``` + +At runtime you should now see your custom Angular component rendered in place of the original form widgets: + +![adf form widget runtime](../docassets/images/apa-resolved-widget.png) + +## See Also + +- [Extensibility](./extensibility.md) +- [Form field model](../core/models/form-field.model.md) +- [Form rendering service](../core/services/form-rendering.service.md) +- [Form component](../core/components/form.component.md) +- [Widget component](../insights/components/widget.component.md)