mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[AAE-3493] Update the documentation to provide the proper guidance on custom forms widgets for APA and APS developers (#6158)
* * improve docs * * assets fixed * * links fixed * * versions fixed * * assets added * * fix links * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Update docs/user-guide/aae-extensions.md Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> * * example fixed * * minor changes * Make stencils document step-based Co-authored-by: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Co-authored-by: Mark Hulbert <mark.hulbert@alfresco.com>
This commit is contained in:
dhrn
GitHub
172
docs/user-guide/aae-extensions.md
Normal file
172
docs/user-guide/aae-extensions.md
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
Title: Form Extensibility for AAE Form Widget
|
||||
Added: v4.1.0
|
||||
---
|
||||
|
||||
## Form Extensibility for AAE 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 custom form widget with custom components](#replace-custom-form-widgets-with-custom-components)
|
||||
|
||||
## Replace default form widgets with AAE 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 `<adf-form>` component.
|
||||
|
||||
1. Create a simple form with some `Text` widgets:
|
||||
|
||||
|
||||
|
||||
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: `
|
||||
<div style="color: red">Look, I'm a AAE custom editor!</div>
|
||||
`
|
||||
})
|
||||
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:
|
||||
|
||||
|
||||
|
||||
|
||||
## 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`:
|
||||
|
||||
|
||||
|
||||
**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:
|
||||
|
||||
|
||||
|
||||
### Create a custom widget
|
||||
|
||||
When displayed in a task, the field will look similar to the following:
|
||||
|
||||
|
||||
|
||||
|
||||
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: `<div style="color: green">ADF version of custom form widget</div>`
|
||||
})
|
||||
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:
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
184
docs/user-guide/aps-extensions.md
Normal file
184
docs/user-guide/aps-extensions.md
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
Title: Form Extensibility for APS Stencil
|
||||
Added: v1.9.0
|
||||
---
|
||||
|
||||
## Form Extensibility for APS Stencil
|
||||
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](#replacing-default-form-widgets-with-custom-components)
|
||||
- [Replace custom stencils with custom components](#replacing-custom-stencils-with-custom-components)
|
||||
|
||||
## Replace default form widgets with custom components
|
||||
|
||||
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 APS forms rendered within the `<adf-form>` component.
|
||||
|
||||
1. Create a simple form with some `Text` widgets:
|
||||
|
||||
|
||||
|
||||
Every custom [widget](../../lib/testing/src/lib/core/pages/form/widgets/widget.ts) 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: `
|
||||
<div style="color: red">Look, I'm a custom editor!</div>
|
||||
`
|
||||
})
|
||||
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](../../lib/testing/src/lib/core/pages/form/widgets/widget.ts) should be added into 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) in 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) {
|
||||
formRenderingService.setComponentTypeResolver('text', () => CustomEditorComponent, true);
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
5. At runtime it should look similar to the following:
|
||||
|
||||
|
||||
|
||||
## Replace custom stencils with custom components
|
||||
|
||||
This is an example of rendering custom APS stencils using custom Angular components.
|
||||
|
||||
### Create a custom stencil
|
||||
|
||||
1. Create a basic stencil and call it `Custom Stencil 01`:
|
||||
|
||||
|
||||
|
||||
**Note**: the `internal identifier` is important as it will become the `field type` when the form is rendered.
|
||||
|
||||
2. Create a simple html layout for the [`Form`](../../lib/process-services/src/lib/task-list/models/form.model.ts)`runtime template` and [`Form`](../../lib/process-services/src/lib/task-list/models/form.model.ts)`editor template` fields:
|
||||
|
||||
```html
|
||||
<div style="color: blue">Custom activiti stencil</div>
|
||||
```
|
||||
|
||||
3. Create a test form based on your custom stencil:
|
||||
|
||||
|
||||
|
||||
4. Create a task using the test form. It will look similar to the following:
|
||||
|
||||
|
||||
|
||||
### Create a custom widget
|
||||
|
||||
1. Load the form created in the previous steps into the ADF `<adf-form>` component:
|
||||
|
||||
|
||||
|
||||
2. Create an Angular component to render the missing content:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
import { WidgetComponent } from '@alfresco/adf-core';
|
||||
|
||||
@Component({
|
||||
selector: 'custom-stencil-01',
|
||||
template: `<div style="color: green">ADF version of custom Activiti stencil</div>`
|
||||
})
|
||||
export class CustomStencil01 extends WidgetComponent {}
|
||||
```
|
||||
|
||||
3. Place it inside a custom module:
|
||||
|
||||
```ts
|
||||
import { NgModule } from '@angular/core';
|
||||
import { CustomStencil01 } from './custom-stencil-01.component';
|
||||
|
||||
@NgModule({
|
||||
declarations: [ CustomStencil01 ],
|
||||
exports: [ CustomStencil01 ]
|
||||
})
|
||||
export class CustomEditorsModule {}
|
||||
```
|
||||
|
||||
4. Import it into your Application Module:
|
||||
|
||||
```ts
|
||||
@NgModule({
|
||||
imports: [
|
||||
// ...
|
||||
CustomEditorsModule
|
||||
// ...
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [ AppComponent ]
|
||||
})
|
||||
export class AppModule {}
|
||||
```
|
||||
|
||||
5. 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 { CustomStencil01 } from './custom-stencil-01.component';
|
||||
|
||||
@Component({...})
|
||||
export class MyView {
|
||||
|
||||
constructor(formRenderingService: FormRenderingService) {
|
||||
formRenderingService.setComponentTypeResolver('custom_stencil_01', () => CustomStencil01, true);
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
6. At runtime you should now see your custom Angular component rendered in place of the stencils:
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
@@ -18,10 +18,7 @@ _Note: it is assumed you are familiar with Alfresco Process Services (powered by
|
||||
- [How components and widgets are rendered on a Form](#how-components-and-widgets-are-rendered-on-a-form)
|
||||
- [Component type resolvers](#component-type-resolvers)
|
||||
- [Default component mappings](#default-component-mappings)
|
||||
- [Replacing default form widgets with custom components](#replacing-default-form-widgets-with-custom-components)
|
||||
- [Replacing custom stencils with custom components](#replacing-custom-stencils-with-custom-components)
|
||||
- [Creating custom stencil](#creating-custom-stencil)
|
||||
- [Creating custom widget](#creating-custom-widget)
|
||||
- [Form Extensibility for APS/AAE](#form-extensibility-for-apsaae)
|
||||
- [See Also](#see-also)
|
||||
|
||||
## How components and widgets are rendered on a Form
|
||||
@@ -102,173 +99,9 @@ formRenderingService.setComponentTypeResolver('text', customResolver, true);
|
||||
| Attach | upload | AttachWidgetComponent or [`UploadWidgetComponent`](../../lib/core/form/components/widgets/upload/upload.widget.ts) (based on metadata) |
|
||||
| N/A | N/A | [`UnknownWidgetComponent`](../../lib/core/form/components/widgets/unknown/unknown.widget.ts) |
|
||||
|
||||
## Replacing default form widgets with custom components
|
||||
|
||||
This is a short walkthrough on replacing a standard `Text` [widget](../../lib/testing/src/lib/core/pages/form/widgets/widget.ts) with a custom component for all APS forms
|
||||
rendered within `<adf-form>` component.
|
||||
|
||||
First let's create a simple APS form with `Text` widgets:
|
||||
|
||||
|
||||
|
||||
Every custom [widget](../../lib/testing/src/lib/core/pages/form/widgets/widget.ts) must inherit [`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: `
|
||||
<div style="color: red">Look, I'm a custom editor!</div>
|
||||
`
|
||||
})
|
||||
export class CustomEditorComponent extends WidgetComponent {}
|
||||
```
|
||||
|
||||
Now you will need to 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 {}
|
||||
```
|
||||
|
||||
Every custom [widget](../../lib/testing/src/lib/core/pages/form/widgets/widget.ts) should be added into the following collections: `declarations`, `exports`.
|
||||
|
||||
If you decided to store custom widgets in a separate dedicated module (and optionally as separate redistributable library)
|
||||
don't forget to import it into your main application one:
|
||||
|
||||
```ts
|
||||
@NgModule({
|
||||
imports: [
|
||||
// ...
|
||||
CustomEditorsModule
|
||||
// ...
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [ AppComponent ]
|
||||
})
|
||||
export class AppModule {}
|
||||
```
|
||||
|
||||
Now you can import [`FormRenderingService`](../core/services/form-rendering.service.md) in any of your Views and override default mapping similar to the following:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
import { CustomEditorComponent } from './custom-editor.component';
|
||||
|
||||
@Component({...})
|
||||
export class MyView {
|
||||
|
||||
constructor(formRenderingService: FormRenderingService) {
|
||||
formRenderingService.setComponentTypeResolver('text', () => CustomEditorComponent, true);
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
At runtime it should look similar to the following:
|
||||
|
||||
|
||||
|
||||
## Replacing custom stencils with custom components
|
||||
|
||||
This is a short walkthrough on rendering custom APS stencils by means of custom Angular components.
|
||||
|
||||
### Creating custom stencil
|
||||
|
||||
First let's create a basic stencil and call it `Custom Stencil 01`:
|
||||
|
||||
|
||||
|
||||
_Note the `internal identifier` value as it will become a `field type` value when corresponding form is rendered._
|
||||
|
||||
Next put some simple html layout for [`Form`](../../lib/process-services/src/lib/task-list/models/form.model.ts)`runtime template` and [`Form`](../../lib/process-services/src/lib/task-list/models/form.model.ts)`editor template` fields:
|
||||
|
||||
```html
|
||||
<div style="color: blue">Custom activiti stencil</div>
|
||||
```
|
||||
|
||||
Now you are ready to design a test form based on your custom stencil:
|
||||
|
||||
|
||||
|
||||
Once wired with a new task it should look like the following within APS web application:
|
||||
|
||||
|
||||
|
||||
### Creating custom widget
|
||||
|
||||
If you load previously created task into ADF `<adf-form>` component you will see something like the following:
|
||||
|
||||
|
||||
|
||||
Let's create an Angular component to render missing content:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
import { WidgetComponent } from '@alfresco/adf-core';
|
||||
|
||||
@Component({
|
||||
selector: 'custom-stencil-01',
|
||||
template: `<div style="color: green">ADF version of custom Activiti stencil</div>`
|
||||
})
|
||||
export class CustomStencil01 extends WidgetComponent {}
|
||||
```
|
||||
|
||||
Put it inside custom module:
|
||||
|
||||
```ts
|
||||
import { NgModule } from '@angular/core';
|
||||
import { CustomStencil01 } from './custom-stencil-01.component';
|
||||
|
||||
@NgModule({
|
||||
declarations: [ CustomStencil01 ],
|
||||
exports: [ CustomStencil01 ]
|
||||
})
|
||||
export class CustomEditorsModule {}
|
||||
```
|
||||
|
||||
And import into your Application Module
|
||||
|
||||
```ts
|
||||
@NgModule({
|
||||
imports: [
|
||||
// ...
|
||||
CustomEditorsModule
|
||||
// ...
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [ AppComponent ]
|
||||
})
|
||||
export class AppModule {}
|
||||
```
|
||||
|
||||
Now you can import [`FormRenderingService`](../core/services/form-rendering.service.md) in any of your Views and provide new mapping:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
import { CustomStencil01 } from './custom-stencil-01.component';
|
||||
|
||||
@Component({...})
|
||||
export class MyView {
|
||||
|
||||
constructor(formRenderingService: FormRenderingService) {
|
||||
formRenderingService.setComponentTypeResolver('custom_stencil_01', () => CustomStencil01, true);
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
At runtime you should now see your custom Angular component rendered in place of the stencils:
|
||||
|
||||
|
||||
## Form Extensibility for APS/AAE
|
||||
- [Form Extensibility for APS Stencil](./aps-extensions.md)
|
||||
- [Form Extensibility for AAE Form Widget](./aae-extensions.md)
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
Reference in New Issue
Block a user