From de8fa02ef7660305965e3b91eddfc3490e0c3863 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Thu, 19 Oct 2017 12:24:52 +0100 Subject: [PATCH] [ADF-1586] Added doc files for Form library (#2503) * [ADF-1586] Added docs for Form library * [ADF-1586] Added updated doc index --- docs/FormFieldValidator.md | 153 +++++++++++++++++++++++++++++++++ docs/README.md | 21 +++-- docs/form-field.model.md | 99 +++++++++++++++++++++ docs/form-rendering.service.md | 97 +++++++++++++++++++++ docs/form.component.md | 151 ++++---------------------------- docs/seeAlsoGraph.json | 14 ++- docs/widget.component.md | 38 ++++++++ 7 files changed, 431 insertions(+), 142 deletions(-) create mode 100644 docs/FormFieldValidator.md create mode 100644 docs/form-field.model.md create mode 100644 docs/form-rendering.service.md create mode 100644 docs/widget.component.md diff --git a/docs/FormFieldValidator.md b/docs/FormFieldValidator.md new file mode 100644 index 0000000000..bd23ee85e8 --- /dev/null +++ b/docs/FormFieldValidator.md @@ -0,0 +1,153 @@ +# FormFieldValidator interface + +Defines how the input fields of [ADF Form](form.component.md) and +[ADF Task Details](task-details.component.md) components are validated. + +## Basic Usage + +```html + +``` + +```ts +import { FORM_FIELD_VALIDATORS } from 'ng2-activiti-form'; + +@Component({...}) +export class AppComponent { + + fieldValidators = [ + // default set of ADF validators if needed + ...FORM_FIELD_VALIDATORS, + + // custom validator + new MyValidator() + ]; + +} + +export class MyValidator implements FormFieldValidator { + + isSupported(field: FormFieldModel): boolean { + // Check if this validation can be used with 'field'. + } + + validate(field: FormFieldModel): boolean { + // Perform the validation. + } +} +``` + +### Methods + +`isSupported(field: FormFieldModel): boolean;` +Does this validator support the type of data used in `field`? + +`validate(field: FormFieldModel): boolean;` +Perform validation on `field`. + +## Details + +You can supply a set of validator objects for a form using its `fieldValidators` property. +ADF will determine if a validator should be used with a given field by calling its +`isSupported` method, passing the field's FormFieldModel as a parameter. If the validator +does support the field then its `validate` method will be called on the FormFieldModel +during the validation phase. + +Several validator classes are predefined for you to use: + +| Validator name | Checks that: | +| --- | --- | +| `RequiredFieldValidator` | Field is not left blank | +| `NumberFieldValidator` | Field contains numeric data | +| `MinLengthFieldValidator` | Field text has at least a minimum number of characters | +| `MaxLengthFieldValidator` | Field text has no more than a maximum number of characters | +| `MinValueFieldValidator` | Numeric field's value is greater than a lower limit | +| `MaxValueFieldValidator` | Numeric field's vaue is less than an upper limit | +| `RegExFieldValidator` | Field text matches a regular expression | +| `DateFieldValidator` | Field contains a date in the correct format | +| `MinDateFieldValidator` | Date within a field occurs after a certain starting point | +| `MaxDateFieldValidator` | Date within a field occurs before a certain end point | + +The `FORM_FIELD_VALIDATORS` array contains an instance of each of these classes. You can assign this to the `fieldValidators` property of an Activiti Form or Activiti Task Details component to enable standard validation. + +### Custom validators + +You can implement your own custom validator classes if the standard set doesn't provide the +features you need. For example, you could check for consistency between separate fields on +the form (currency values adding up to a given total, say). + +The `type` property of `FormFieldModel` is often used in the `isSupported` function, since +validation methods typically apply only to specific types of data. +The [FormFieldTypes](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-field-types.ts) +class defines convenient constants for the type strings. + +The validator in the example +below simply checks that "admin" is not entered into a text field: + +```ts +import { FormFieldModel, FormFieldTypes, FormFieldValidator } from 'ng2-activiti-form'; + +export class DemoFieldValidator implements FormFieldValidator { + + isSupported(field: FormFieldModel): boolean { + return field && field.type === FormFieldTypes.TEXT; + } + + validate(field: FormFieldModel): boolean { + if (this.isSupported(field)) { + if (field.value && field.value.toLowerCase() === 'admin') { + field.validationSummary = 'Sorry, the value cannot be "admin".'; + return false; + } + } + return true; + } + +} +``` + +You will usually want to extend the existing `FORM_FIELD_VALIDATORS` set rather than replace +it entirely (although you can do this if necessary): + +```ts +import { DemoFieldValidator } from './demo-field-validator'; + +@Component({...}) +export class AppComponent { + + fieldValidators = [ + ...FORM_FIELD_VALIDATORS, + new DemoFieldValidator() + ]; + +} +``` + +You can now use the 'fieldValidators' property of the Form or Task Details components to assign your +custom validator set: + +```html + + + + + + + +``` + +If you now run the application and try to enter "admin" in one of the text fields (either optional or required), you should see the following error: + +![](docassets/images/demo-validator.png) + + + +## See also + +- [Form field model](form-field.model.md) +- [Form component](form.component.md) + \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 0b402c29cf..94f08352a2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,9 +48,9 @@ for more information about installing and using the source code. - [Analytics generator component](analytics-generator.component.md) - [Analytics report list component](analytics-report-list.component.md) - [Analytics component](analytics.component.md) +- [Widget component](widget.component.md) - [*Analytics report heat map component](../ng2-components/ng2-activiti-analytics/src/components/analytics-report-heat-map.component.ts) - [*Analytics report parameters component](../ng2-components/ng2-activiti-analytics/src/components/analytics-report-parameters.component.ts) -- [*Widget component](../ng2-components/ng2-activiti-analytics/src/components/widgets/widget.component.ts) ### Services @@ -176,21 +176,25 @@ for more information about installing and using the source code. - [Form list component](form-list.component.md) - [Form component](form.component.md) +- [Widget component](widget.component.md) - [*Form field component](../ng2-components/ng2-activiti-form/src/components/form-field/form-field.component.ts) - [*Start form component](../ng2-components/ng2-activiti-form/src/components/start-form.component.ts) - [*Error component](../ng2-components/ng2-activiti-form/src/components/widgets/error/error.component.ts) - [*Text mask component](../ng2-components/ng2-activiti-form/src/components/widgets/text/text-mask.component.ts) -- [*Widget component](../ng2-components/ng2-activiti-form/src/components/widgets/widget.component.ts) ### Directives - [*Form custom button directive](../ng2-components/ng2-activiti-form/src/components/form-custom-button.directive.ts) +### Models + +- [Form field model](form-field.model.md) + ### Services +- [Form rendering service](form-rendering.service.md) - [Form service](form.service.md) - [*Activiti alfresco service](../ng2-components/ng2-activiti-form/src/services/activiti-alfresco.service.ts) -- [*Form rendering service](../ng2-components/ng2-activiti-form/src/services/form-rendering.service.ts) - [*Node service](../ng2-components/ng2-activiti-form/src/services/node.service.ts) - [*Widget visibility service](../ng2-components/ng2-activiti-form/src/services/widget-visibility.service.ts) @@ -219,6 +223,9 @@ for more information about installing and using the source code. - [*Upload widget](../ng2-components/ng2-activiti-form/src/components/widgets/upload/upload.widget.ts) +### Other classes and interfaces + +- [FormFieldValidator interface](FormFieldValidator.md) [(Back to Contents)](#contents) ## ADF Processlist @@ -308,8 +315,8 @@ for more information about installing and using the source code. - [Data column component](data-column.component.md) - [Info drawer layout component](info-drawer-layout.component.md) - [Info drawer component](info-drawer.component.md) +- [Language menu component](language-menu.component.md) - [Pagination component](pagination.component.md) -- [Language Manu](language-menu.component.md) - [Toolbar divider component](toolbar-divider.component.md) - [Toolbar title component](toolbar-title.component.md) - [Toolbar component](toolbar.component.md) @@ -325,12 +332,12 @@ for more information about installing and using the source code. - [Node permission directive](node-permission.directive.md) - [Node restore directive](node-restore.directive.md) - [Upload directive](upload.directive.md) -- [Node Name Tooltip directive](node-name-tooltip.pipe.md) - [*Card view content proxy directive](../ng2-components/ng2-alfresco-core/src/components/view/card-view-content-proxy.directive.ts) - [*Highlight directive](../ng2-components/ng2-alfresco-core/src/directives/highlight.directive.ts) ### Pipes +- [Node name tooltip pipe](node-name-tooltip.pipe.md) - [*File size pipe](../ng2-components/ng2-alfresco-core/src/pipes/file-size.pipe.ts) - [*Mime type icon pipe](../ng2-components/ng2-alfresco-core/src/pipes/mime-type-icon.pipe.ts) - [*Text highlight pipe](../ng2-components/ng2-alfresco-core/src/pipes/text-highlight.pipe.ts) @@ -351,9 +358,11 @@ for more information about installing and using the source code. - [*Context menu service](../ng2-components/ng2-alfresco-core/src/components/context-menu/context-menu.service.ts) - [*Alfresco content service](../ng2-components/ng2-alfresco-core/src/services/alfresco-content.service.ts) - [*Alfresco settings service](../ng2-components/ng2-alfresco-core/src/services/alfresco-settings.service.ts) +- [*Apps process service](../ng2-components/ng2-alfresco-core/src/services/apps-process.service.ts) - [*Auth guard bpm service](../ng2-components/ng2-alfresco-core/src/services/auth-guard-bpm.service.ts) - [*Auth guard ecm service](../ng2-components/ng2-alfresco-core/src/services/auth-guard-ecm.service.ts) - [*Auth guard service](../ng2-components/ng2-alfresco-core/src/services/auth-guard.service.ts) +- [*Comment process service](../ng2-components/ng2-alfresco-core/src/services/comment-process.service.ts) - [*Content service](../ng2-components/ng2-alfresco-core/src/services/content.service.ts) - [*Cookie service](../ng2-components/ng2-alfresco-core/src/services/cookie.service.ts) - [*Deleted nodes api service](../ng2-components/ng2-alfresco-core/src/services/deleted-nodes-api.service.ts) @@ -394,7 +403,7 @@ for more information about installing and using the source code. ### Other classes and interfaces -- [DataTableAdapter interface](docs/DataTableAdapter.md) +- [DataTableAdapter interface](DataTableAdapter.md) [(Back to Contents)](#contents) diff --git a/docs/form-field.model.md b/docs/form-field.model.md new file mode 100644 index 0000000000..9eb4c1628e --- /dev/null +++ b/docs/form-field.model.md @@ -0,0 +1,99 @@ +# Form Field model + +Contains the value and metadata for a field of an +[ADF Form](form.component.md). + +## Properties + +| Name | Type | Default | Description | +|--|--|--|--| +| id | string | | Field ID | +| name | string | | Field name | +| type | string | | Field type (see [Form Rendering service](form-rendering.service.md) for a list of available type strings) | +| value | any | | Field value (implemented by get/set) | +| readOnly | boolean | | Is this a read-only field? (Implemented by get/set) | +| required | boolean | | Is the field required to have a value? (Implemented by get/set) | +| isValid | boolean | | Does the field pass its validation checks? (Implemented by get/set) | +| overrideId | boolean | | Should the auto-generated ID (from `name`) be overridden to let the user set a custom ID? | +| tab | string | | Name of the current form tab | +| rowspan | number | 1 | The number of container rows that the field spans | +| colspan | number | 1 | The number of container columns that the field spans | +| placeholder | string | null | Placeholder text shown before the field is edited | +| minLength | number | 0 | Minimum allowed number of characters in input data | +| maxLength | number | 0 | Maximum allowed number of characters in input data | +| minValue | string | | Minimum allowed value (eg, for number or date) | +| maxValue | string | | Minimum allowed value (eg, for number or date) | +| regexPattern | string | | Regular expression that text data should match | +| options | FormFieldOption[] | [] | Option items for a dropdown menu | +| restUrl | string | | URL for a REST call to populate a dropdown menu | +| restResponsePath | string | | Path within REST response JSON to the array of dropdown data | +| restIdProperty | string | | JSON property name to use for the `id` property of a dropdown item | +| restLabelProperty | string | | JSON property name to use for the `label` property of a dropdown item | +| hasEmptyValue | boolean | | Is the field's value empty? (eg, dropdown with no item selected) | +| className | string | | CSS class name for the field | +| optionType | string | | | +| params | FormFieldMetadata | {} | | +| hyperlinkUrl | string | | URL for Hyperlink widgets | +| displayText | string | | Displayed text for Hyperlink widgets | +| isVisible | boolean | true | Is the field shown on the form? | +| visibilityCondition | WidgetVisibilityModel | null | Defines a expression that determines whether the field is visible or not, based on its logical relation to values in other fields | +| enableFractions | boolean | false | Are numeric values allowed to contain a decimal point? | +| currency | string | null | Currency symbol for Amount widgets | +| dateDisplayFormat | string | | Date/time display format template | +| numberOfColumns | number | 1 | Number of columns defined by a container field | +| fields | FormFieldModel[] | [] | Fields contained within a container field | +| columns | ContainerColumnModel[] | [] | Column definitions for a container field | +| emptyOption | FormFieldOption | | Dropdown menu item to use when no option is chosen | +| validationSummary | string | | Error/information message added during field validation (see [FormFieldValidator](FormFieldValidator) interface) | + +## Details + +Every field of a form has an associated `FormFieldModel` instance that contains the +field's value and metadata. The standard widgets use this information to render fields and you can also make use of it in your own custom widgets and field validators. + +### Custom widgets + +You will need to use the properties of `FormFieldModel` if you want to implement your own +custom widgets. Aside from the `value` property (which contains the data value entered into +the field), there are also a few other fields that are used for specific types of data. For +example, the `currency` property holds the currency symbol to be displayed next to the value +(such as the dollar sign $) and the `dateDisplayFormat` defines how the elements of a date/time will be arranged. See the [Form Extensibility and Customization](extensibility.md) for more information about creating custom widgets. + +### Validation + +A [Form](form.component.md) or [Task Details](task-details.component.md) component can +be supplied with a set of validator objects. Each validator applies a particular kind of +check to a field. A number of `FormFieldModel` properties are used by validators. For +example, `minValue` and `maxValue` are used to check that a numeric value falls within an +allowed range and `regexPattern` defines a regular expression that a text field should +match. Also, the `validationSummary` is used to send a message back from the validator +for the user to read. See the [FormFieldValidator](FormFieldValidator.md) page for more information about implementing validators. + +### REST properties + +You can set the items shown on a dropdown menu using data returned by a REST call. The +properties used by the call are: + +- `restUrl`: The URL for the REST service +- `restResponsePath`: Optional path to an array within the JSON object returned by +the REST call. Each element in the array corresponds to an item on the dropdown. +- `restIdProperty`: The name of a JSON property present in each element of the array +selected by `restResponsePath`. Its value will be used for the `id` property of the +dropdown item. +`restLabelProperty`: The name of a JSON property present in each element of the array +selected by `restResponsePath`. Its value will be used for the `label` property of the +dropdown item (ie, the text visible to the user). + +The [REST Call Task 101](https://community.alfresco.com/community/bpm/blog/2016/08/31/rest-integration) +tutorial on the [APS community site](https://community.alfresco.com/community/bpm) +contains full details about how the REST calls work, along with a worked example. + + + +## See also + +- [Extensibility](extensibility.md) +- [FormFieldValidator](FormFieldValidator.md) +- [Form rendering service](form-rendering.service.md) +- [Form component](form.component.md) + \ No newline at end of file diff --git a/docs/form-rendering.service.md b/docs/form-rendering.service.md new file mode 100644 index 0000000000..7dbb016006 --- /dev/null +++ b/docs/form-rendering.service.md @@ -0,0 +1,97 @@ +# Form Rendering service + +Maps an APS form field type string onto the corresponding form widget component type. + +## Methods + +`getComponentTypeResolver(fieldType: string, defaultValue: Type<{}> = UnknownWidgetComponent): ComponentTypeResolver`
+Gets the currently active ComponentTypeResolver function for a field type. + +`setComponentTypeResolver(fieldType: string, resolver: ComponentTypeResolver, override: boolean = false)`
+Sets or optionally replaces a ComponentTypeResolver function for a field type. + +`resolveComponentType(field: FormFieldModel, defaultValue: Type<{}> = UnknownWidgetComponent): Type<{}>`
+Finds the component type that is needed to render a form field. + +## Details + +The Form Field component uses this service to choose which widget to use to render an instance of a +form field. The Form Field model stores the field type name as a string (see the table below). +The Form Rendering service maintains a mapping between each type name and +a corresponding ComponentTypeResolver function. The function takes a FormFieldModel object as its argument and +uses the data from the object to determine which widget should be used to render the field. + +In some cases, the field type string alone is enough to determine the widget type and so the function +just returns the type directly: + +```ts +let customResolver: ComponentTypeResolver = () => CustomWidgetComponent; +formRenderingService.setComponentTypeResolver('text', customResolver, true); +``` + +In other cases, the function may need to choose the widget dynamically based on +specific values in the form data: + +```ts +let customResolver: ComponentTypeResolver = (field: FormFieldModel): Type<{}> => { + if (field) { + let params = field.params; + } + return UnknownWidgetComponent; +}; +formRenderingService.setComponentTypeResolver('text', customResolver, true); +``` + +### Default type mapping + +The Form Rendering service is initialized with the mapping shown in the table below: + +| Stencil name | Field type string | Component type | +|---|---|---| +| Amount | "amount" | AmountWidgetComponent | +| Attach | "upload" | AttachWidgetComponent or UploadWidgetComponent (based on metadata) | +| Checkbox | "boolean" | CheckboxWidgetComponent | +| Date | "date" | DateWidgetComponent | +| Display text | "readonly-text" | DisplayTextWidgetComponentComponent | +| Display value | "readonly" | DisplayValueWidgetComponent | +| Dropdown | "dropdown" | DropdownWidgetComponent | +| Dynamic table | "dynamic-table" | DynamicTableWidgetComponent | +| Group of people | "functional-group" | FunctionalGroupWidgetComponent | +| Header | "group" | ContainerWidgetComponent | +| Hyperlink | "hyperlink" | HyperlinkWidgetComponent | +| Multi-line text | "multi-line-text" | MultilineTextWidgetComponentComponent | +| Number | "integer" | NumberWidgetComponent | +| People | "people" | PeopleWidgetComponent | +| Radio buttons | "radio-buttons" | RadioButtonsWidgetComponent | +| Text | "text" | TextWidgetComponent | +| Typeahead | "typeahead" | TypeaheadWidgetComponent | + +You can add new items to the mapping or replace existing items in order to customize the way +fields are rendered. + +### Adding new or replacement items to the mapping + +You can use the `setComponentTypeResolver` method to add a new ComponentTypeResolver function for a +particular type string. You can also replace the resolver for a type that already exists in the mapping +if you set the `override` parameter to 'true': + +```ts +formRenderingService.setComponentTypeResolver('text', newResolver, true); +``` + +You would typically use this to replace an existing widget with your own custom version that +implements a modified layout or responds differently when the data is entered. See the +[Form Extensibility and Customisation](extensibility.md) guide for further details and examples +of this technique. + + + +## See also + +- [Extensibility](extensibility.md) +- [Form field model](form-field.model.md) +- [Form component](form.component.md) + + + + diff --git a/docs/form.component.md b/docs/form.component.md index 706a018c0f..203358c584 100644 --- a/docs/form.component.md +++ b/docs/form.component.md @@ -13,9 +13,7 @@ The component shows a Form from Activiti (see it live: [Form Quickstart](https:/ - [Details](#details) * [Custom empty form template](#custom-empty-form-template) * [Controlling outcome execution behaviour](#controlling-outcome-execution-behaviour) - * [Form Field Validators](#form-field-validators) - + [Custom set of validators](#custom-set-of-validators) - + [Custom validator example](#custom-validator-example) + * [Field Validators](#field-validators) - [Other documentation](#other-documentation) * [Common scenarios](#common-scenarios) + [Changing field value based on another field](#changing-field-value-based-on-another-field) @@ -122,7 +120,7 @@ and store the form field as metadata. The param nameNode is optional. | saveMetadata | boolean | false | Store the value of the form as metadata. | | path | string | | Path of the folder where to store the metadata. | | nameNode | string | true | Name to assign to the new node where the metadata are stored. | -| fieldValidators | FormFieldValidator[] | See [Form Field Validators](#form-field-validators) section below | Contains a list of form field validator instances. | +| fieldValidators | FormFieldValidator[] | See [Field Validators](#field-validators) section below | Contains a list of form field validator instances. | ### Advanced properties @@ -233,135 +231,14 @@ There are two additional functions that can be of a great value when controlling **Please note that if `event.preventDefault()` is not called then default outcome behaviour will also be executed after your custom code.** -### Form Field Validators +### Field Validators -The Form component provides you with access to all Form Field validators. By default the following instances are created automatically: - -- RequiredFieldValidator -- NumberFieldValidator -- MinLengthFieldValidator -- MaxLengthFieldValidator -- MinValueFieldValidator -- MaxValueFieldValidator -- RegExFieldValidator -- DateFieldValidator -- MinDateFieldValidator -- MaxDateFieldValidator - -If needed, you can completely redefine the set of validators used by the form. - -All changes to `fieldValidators` collection are automatically applied to all the further validation cycles. - -#### Custom set of validators - -You can provide your own set of field validators based on either custom validator instances, or a mixture of default and custom ones. - -```html - -``` - -The Form component exposes a special `FORM_FIELD_VALIDATORS` constant that allows you get a quick access to all system validator instances. - -```ts -import { FORM_FIELD_VALIDATORS } from 'ng2-activiti-form'; - -@Component({...}) -export class AppComponent { - - fieldValidators = [ - // default set of ADF validators if needed - ...FORM_FIELD_VALIDATORS, - - // custom validators - new MyValidator1(), - new MyValidator2() - ]; - -} -``` - -#### Custom validator example - -A form field validator must implement the "FormFieldValidator" interface: - -```ts -export interface FormFieldValidator { - - isSupported(field: FormFieldModel): boolean; - validate(field: FormFieldModel): boolean; - -} -``` - -There might be many different validators used for various field types and purposes, -so the validation layer needs every validator instance to support "isSupported" call. - -It is up to validator to declare support for a form field. -If you want to check field types the [FormFieldTypes](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-field-types.ts) class can help you with the predefined constants and helper methods. - -In addition every validator has access to all underlying APIs of the [FormFieldModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-field.model.ts), -including the reference to the Form instance and so other form fields. - -Below is a source code for a demo validator that is executed for all the "TEXT" fields, and ensures the value is not "admin", otherwise the `field.validationSummary` value is set to an error. - -```ts -import { FormFieldModel, FormFieldTypes, FormFieldValidator } from 'ng2-activiti-form'; - -export class DemoFieldValidator implements FormFieldValidator { - - isSupported(field: FormFieldModel): boolean { - return field && field.type === FormFieldTypes.TEXT; - } - - validate(field: FormFieldModel): boolean { - if (this.isSupported(field)) { - if (field.value && field.value.toLowerCase() === 'admin') { - field.validationSummary = 'Sorry, the value cannot be "admin".'; - return false; - } - } - return true; - } - -} -``` - -Your component can extend the default validation set instead of replacing it entirely. -In the example below we redefine a default validation set with an additional "DemoFieldValidator": - -```ts -import { DemoFieldValidator } from './demo-field-validator'; - -@Component({...}) -export class AppComponent { - - fieldValidators = [ - ...FORM_FIELD_VALIDATORS, - new DemoFieldValidator() - ]; - -} -``` - -You can now use the 'fieldValidators' property with the Form or Task Details components to assign custom validator set for the underlying Form Model: - -```html - - - - - - - -``` - -Now if you run the application and try to enter "admin" in one of the text fields (either optional or required), you should see the following error: - -![](docassets/images/demo-validator.png) +You can supply a set of validator objects to the form using the `fieldValidators` +property. Each validator implements checks for a particular type of data (eg, a +date validator might check that the date in the field falls between 1980 and 2017). +ADF supplies a standard set of validators that handle most common cases but you can +also implement your own custom validators to replace or extend the set. See the +[FormFieldValidator](FormFieldValidator.md) class for full details and examples. ## Other documentation @@ -401,7 +278,13 @@ formService.formEvents.subscribe((event: Event) => { }); ``` + + ## See also -- [Form Stencils with Angular 2](stencils.md) -- [Form Extensibility and Customisation](extensibility.md). \ No newline at end of file +- [Stencils](stencils.md) +- [FormFieldValidator](FormFieldValidator.md) +- [Extensibility](extensibility.md) +- [Form rendering service](form-rendering.service.md) +- [Form field model](form-field.model.md) + \ No newline at end of file diff --git a/docs/seeAlsoGraph.json b/docs/seeAlsoGraph.json index d3ab66c791..43b1817b5a 100644 --- a/docs/seeAlsoGraph.json +++ b/docs/seeAlsoGraph.json @@ -38,8 +38,17 @@ "file-uploading-dialog.component": [], "folder-actions.service": ["document-actions.service"], "form-list.component": [], - "form.component": [], + "form-field.model": ["extensibility", "FormFieldValidator", "form-rendering.service"], + "form-rendering.service": ["extensibility"], + "form.component": [ + "stencils", + "FormFieldValidator", + "extensibility", + "form-rendering.service", + "form-field.model" + ], "form.service": [], + "FormFieldValidator": [], "info-drawer.component": ["info-drawer-layout.component"], "info-drawer-layout.component": [], "like.component": ["rating.component"], @@ -90,5 +99,6 @@ "user-info.component": [], "user-preferences.service": [], "viewer.component": [], - "webscript.component": [] + "webscript.component": [], + "widget.component": ["extensibility"] } \ No newline at end of file diff --git a/docs/widget.component.md b/docs/widget.component.md new file mode 100644 index 0000000000..cb61d61fe6 --- /dev/null +++ b/docs/widget.component.md @@ -0,0 +1,38 @@ +# Widget component + +Base class for standard and custom widget classes. + +## Basic Usage + +```ts +import { Component } from '@angular/core'; +import { WidgetComponent } from 'ng2-activiti-form'; + +@Component({ + selector: 'custom-editor', + template: ` +
Look, I'm a custom editor!
+ ` +}) +export class CustomEditorComponent extends WidgetComponent {} +``` + +### Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| readOnly | boolean | false | Does the widget show a read-only value? (ie, can't be edited) | +| field | [FormFieldModel](form-field.model.md) | | Data to be displayed in the field | + +## Details + +The Widget component is the base class for all standard and custom form widgets. See the +[Form Extensibility and Customisation](extensibility.md) page for full details about +implementing custom widgets. + + + +## See also + +- [Extensibility](extensibility.md) + \ No newline at end of file