diff --git a/docs/guides/formly.md b/docs/guides/formly.md index 04d34cb4b7..be9c469ca6 100644 --- a/docs/guides/formly.md +++ b/docs/guides/formly.md @@ -39,7 +39,7 @@ In Formly, forms are defined as an array of field configurations and a correspon ### Formly-Form Component To render a form using Formly, the `` component is used. -Simply insert it into your template and pass the following inputs: +Insert it into your template and pass the following inputs: - **fields**: An array of type `FormlyFieldConfig[]` - **model**: An object containing key-value-pairs for each form field @@ -184,7 +184,7 @@ There are many options when it comes to [adding custom validation to formly form The PWA comes with some predefined custom validators which can be found in [special-validators.ts](../../src/app/shared/forms/validators/special-validators.ts). These can be added directly to the `validators.validation` property of a `FormlyFieldConfig`. -Don't forget to also add the corresponding error message to the `validation` property. +Make sure to also add the corresponding error message to the `validation` property. Alternatively, validation can be defined as a key-value pair directly in the `validation` property. However, adding validators here requires a different format: @@ -228,7 +228,7 @@ You can find a simple example of a custom type test in [text-input.field.compone ### Testing Wrappers -To test custom wrappers, create a `FormlyTestingContainerComponent` component, configure the `FormlyModule` with an example type (for example `FormlyTestingExampleComponent`) and the wrapper and set an appropriate testing configuration. +To test custom wrappers, create a `FormlyTestingContainerComponent` component, configure the `FormlyModule` with an example type (for example `FormlyTestingExampleComponent`) and the wrapper, and set an appropriate testing configuration. You can find a simple example of a wrapper test in [maxlength-description-wrapper.component.spec.ts](../../src/app/shared/formly/wrappers/maxlength-description-wrapper/maxlength-description-wrapper.component.spec.ts). @@ -236,7 +236,7 @@ You can find a simple example of a wrapper test in [maxlength-description-wrappe There are multiple ways to adapt Formly for projects or development on the main repository. -If you implement widely used functionality that can be used in multiple components and different pages, add your field types, wrappers or extensions to `src/app/shared/formly` and register them in the `formly.module.ts`. +If you implement widely used functionality that can be used in multiple components and different pages, add your field types, wrappers, or extensions to `src/app/shared/formly` and register them in the `formly.module.ts`. If you need specific fields or behavior that is not used everywhere, it would not be a good idea to pollute `formly.module.ts`. Instead, register your logic in the relevant module using `FormlyModule.forChild()`. @@ -254,42 +254,42 @@ Refer to the tables below for an overview of these parts. - Template option `inputClass`: These CSS class(es) will be added to all input/select/textarea/text tags. - Template option `ariaLabel`: Adds an aria-label to all input/select/textarea tags. -| Name | Description | Relevant props | +| Name | Description | Relevant properties | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ish-text-input-field | Basic input field, supports all text types | `type`: 'text (default),'email','tel','password'. `mask`: input mask for a needed pattern (see [ngx-mask](https://www.npmjs.com/package/ngx-mask) for more information) | -| ish-select-field | Basic select field | `options`: `{ value: any; label: string}[]` or Observable. `placeholder`: Translation key or string for the default selection | -| ish-textarea-field | Basic textarea field | `cols` & `rows`: Specifies the dimensions of the textarea | -| ish-checkbox-field | Basic checkbox input | `title`: Title for a checkbox | -| ish-email-field | Email input field that automatically adds an e-mail validator and error messages | ---- | -| ish-password-field | Password input field that automatically adds a password validator and error messages | ---- | -| ish-phone-field | Phone number input field that automatically adds a phone number validator and error messages | ---- | -| ish-fieldset-field | Wraps fields in a `
` tag for styling | `fieldsetClass`: Class that will be added to the fieldset tag. `childClass`: Class that will be added to the child div. `legend`: Legend element that will be added to the fieldset, use the value as the legend text. `legendClass`: Class that will be added to the legend tag. | -| ish-captcha-field | Includes the `` component and adds the relevant `formControls` to the form | `topic`: Topic that will be passed to the Captcha component. | -| ish-radio-field | Basic radio input | ---- | -| ish-plain-text-field | Only display the form value | ---- | -| ish-html-text-field | Only display the form value as html | ---- | -| ish-date-picker-field | Basic datepicker | `minDays`: Computes the minDate by adding the minimum allowed days to today. `maxDays`: Computes the maxDate by adding the maximum allowed days to today. `isSatExcluded`: Specifies if saturdays can be disabled. `isSunExcluded`: Specifies if sundays can be disabled. | -| ish-date-range-picker-field | Datepicker with range | `minDays`: Computes the minDate by adding the minimum allowed days to today. `maxDays`: Computes the maxDate by adding the maximum allowed days to today. `startDate`: The start date. `placeholder`: Placeholder that displays the date format in the input field. | -| ish-number-field | Basic number input field for smaller Integer numbers, with `+` and `-` buttons (use `ish-text-input-field` with `mask` for larger numbers) | `min`, `max` and `step` input configuration is considered by the in-/decrease buttons | -| ish-information-field | Include any freestyle text within a Formly generated form (HTML content is supported) | provide text via `localizationKey` or just plain `text` and adapt the styling via `containerClass` | +| ish-text-input-field | Basic input field, supports all text types | `type`: 'text (default),'email','tel','password'. `mask`: input mask for a needed pattern (see [ngx-mask](https://www.npmjs.com/package/ngx-mask) for more information) | +| ish-select-field | Basic select field | `options`: `{ value: any; label: string}[]` or Observable. `placeholder`: Translation key or string for the default selection | +| ish-textarea-field | Basic textarea field | `cols` & `rows`: Specifies the dimensions of the textarea | +| ish-checkbox-field | Basic checkbox input | `title`: Title for a checkbox | +| ish-email-field | E-mail input field that automatically adds an e-mail validator and error messages | ---- | +| ish-password-field | Password input field that automatically adds a password validator and error messages | ---- | +| ish-phone-field | Phone number input field that automatically adds a phone number validator and error messages | ---- | +| ish-fieldset-field | Wraps fields in a `
` tag for styling | `fieldsetClass`: Class that will be added to the fieldset tag. `childClass`: Class that will be added to the child div. `legend`: Legend element that will be added to the fieldset. Use the value as the legend text. `legendClass`: Class that will be added to the legend tag. | +| ish-captcha-field | Includes the `` component and adds the relevant `formControls` to the form | `topic`: Topic that will be passed to the Captcha component | +| ish-radio-field | Basic radio input | ---- | +| ish-plain-text-field | Only display the form value | ---- | +| ish-html-text-field | Only display the form value as html | ---- | +| ish-date-picker-field | Basic datepicker | `minDays`: Computes the minDate by adding the minimum number of days allowed to the current date. `maxDays`: Computes the maxDate by adding the maximum number of days allowed to the current date. `isSatExcluded`: Specifies if Saturdays can be disabled. `isSunExcluded`: Specifies if Sundays can be disabled. | +| ish-date-range-picker-field | Datepicker with range | `minDays`: Computes the minDate by adding the minimum number of days allowed to the current date. `maxDays`: Computes the maxDate by adding the maximum number of days allowed to the current date. `startDate`: The start date. `placeholder`: Placeholder that displays the date format in the input field. | +| ish-number-field | Basic number input field for smaller Integer numbers, with `+` and `-` buttons (use `ish-text-input-field` with `mask` for larger numbers) | `min`, `max` and `step` input configuration is considered by the in-/decrease buttons | +| ish-information-field | Include any freestyle text within a Formly generated form (HTML content is supported) | Provide text via `localizationKey` or just plain `text` and adapt the styling via `containerClass` | ### Wrappers -| Name | Functionality | Relevant props | +| Name | Functionality | Relevant properties | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| form-field-horizontal | Adds a label next to the field, adds a `required` marker and adds red styling for invalid fields. | `labelClass` & `fieldClass`: Classes that will be added to the label or field `
`. `labelNoTranslate`: Prevents the label from being translated (e.g. if it is not a translation key). `hideRequiredMarker`: Hides the required marker while still validating a `required` field. | -| form-field-checkbox-horizontal | Adds a label for a checkbox or radio field, adds a `required` marker, adds red styling and error messages for invalid fields. Adds a title for a checkbox, if provided. Uses `validators.validation` and `validation.messages` properties. Adds a tooltip behind the label, see also tooltip-wrapper | `labelClass`, `titleClass` & `fieldClass`: Classes that will be added to the label, title or the outer field `
`. `labelNoTranslate`, `titleNoTranslate`: Prevents the label or title from being translated. . `hideRequiredMarker`: Hides the required marker while still validating a `required` field. | +| form-field-horizontal | Adds a label next to the field, adds a `required` marker, and adds red styling for invalid fields. | `labelClass` & `fieldClass`: Classes that will be added to the label or field `
`. `labelNoTranslate`: Prevents the label from being translated (e.g., if it is not a translation key). `hideRequiredMarker`: Hides the required marker while still validating a `required` field. | +| form-field-checkbox-horizontal | Adds a label for a checkbox or radio field, adds a `required` marker, adds red styling and error messages for invalid fields. Adds a title for a checkbox if provided. Uses `validators.validation` and `validation.messages` properties. Adds a tooltip behind the label, see also tooltip wrapper | `labelClass`, `titleClass` & `fieldClass`: Classes that will be added to the label, title, or the outer field `
`. `labelNoTranslate`, `titleNoTranslate`: Prevents the label or title from being translated. `hideRequiredMarker`: Hides the required marker while still validating a `required` field. | | validation | Adds validation icons and error messages to the field. Uses `validators.validation` and `validation.messages` properties. | `showValidation`: `(field: FormlyFieldConfig) => boolean`: optional, used to determine whether to show validation check marks | | maxlength-description | Adds a description to textarea fields, including the amount of remaining characters (added to textarea by default, can be used for other fields as well). | `maxLength`: Specifies the maximum length to be displayed in the message (required). `maxLengthDescription`: Translation key for the maxlength description (default: 'textarea.max_limit' ). | | description | Adds a custom description to any field | `customDescription`: `string` or `{key: string; args: any}` that will be translated | -| tooltip | Adds a tooltip to a field. Includes `` component. | `tooltip`: `{ title?: string; text: string; link: string }` that defines the different tooltip texts. | -| input-addon | Adds a prepended or appended text to a field, e.g. a currency or unit. | `addonLeft?`: `{ text: string \| Observable; }, addonRight?: {text: string \| Observable}` that defines the addon texts. | +| tooltip | Adds a tooltip to a field. Includes `` component. | `tooltip`: `{ title?: string; text: string; link: string }` that defines the different tooltip texts | +| input-addon | Adds a prepended or appended text to a field, e.g., a currency or unit. | `addonLeft?`: `{ text: string \| Observable; }, addonRight?: {text: string \| Observable}` that defines the addon texts | ### Extensions -| Name | Functionality | Relevant props | +| Name | Functionality | Relevant properties | | ------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | hide-if-empty | Hides fields of type `ish-select-field` that have an empty `options` attribute. | `options`: used to determine emptiness. | | translate-select-options | Automatically translates option labels and adds a placeholder option. | `options`: options whose labels will be translated. `placeholder`: used to determine whether to set placeholder and its text. | -| translate-placeholder | Automatically translates the placeholder value | `placeholder`: value to be translated. | +| translate-placeholder | Automatically translates the placeholder value. | `placeholder`: value to be translated. | | post-wrappers | Appends wrappers to the default ones defined in the `FormlyModule` | `postWrappers`: `[]` of extensions to append to the default wrappers, optional index to specify at which position the wrapper should be inserted. |