diff --git a/src/assets/attachments/blog/2023/005-range-custom-entries.png b/src/assets/attachments/blog/2023/005-range-custom-entries.png new file mode 100644 index 00000000..05a5a46e Binary files /dev/null and b/src/assets/attachments/blog/2023/005-range-custom-entries.png differ diff --git a/src/assets/attachments/blog/2023/005-range-palette.png b/src/assets/attachments/blog/2023/005-range-palette.png new file mode 100644 index 00000000..6058db40 Binary files /dev/null and b/src/assets/attachments/blog/2023/005-range-palette.png differ diff --git a/src/assets/attachments/blog/2023/005-range-properties.png b/src/assets/attachments/blog/2023/005-range-properties.png new file mode 100644 index 00000000..664438bf Binary files /dev/null and b/src/assets/attachments/blog/2023/005-range-properties.png differ diff --git a/src/assets/attachments/blog/2023/005-range-validate.png b/src/assets/attachments/blog/2023/005-range-validate.png new file mode 100644 index 00000000..b086d987 Binary files /dev/null and b/src/assets/attachments/blog/2023/005-range-validate.png differ diff --git a/src/blog/2023/005-custom-form-fields.md b/src/blog/2023/005-custom-form-fields.md new file mode 100644 index 00000000..37507c17 --- /dev/null +++ b/src/blog/2023/005-custom-form-fields.md @@ -0,0 +1,196 @@ +--- + +title: Create custom form components +description: "Introducing newest form-js extension capabilities to create custom form components." +preview_image: http://bpmn.io/assets/attachments/blog/2023/005-range-validate.png +layout: blogpost.hbs +slug: 2023-custom-form-components +author: +- Niklas Kiefer +published: 2023-11-01 18:00 + +releases: + - 'form-js@1.4.0' + +--- + +

+ We are excited to inform you about the latest [form-js](https://github.com/bpmn-io/form-js) improvements that add new extension capabilities to create custom form components. It is easier now to use existing form-js components in your custom renderers and provide properties panel extensions. +

+ + + +The ability to create custom form components was [a long-awaited feature](https://github.com/bpmn-io/form-js/issues/123). With the recent form-js@1.4.0 release, we added extension features to the toolkit in the nature of common bpmn-io extension patterns. + +Check out [our example](https://github.com/bpmn-io/form-js-examples/tree/master/custom-components) to gather more insights about the new extension capabilities. + +## Define a custom form component renderer + +Creating and registering custom form components with a [Preact](https://github.com/preactjs/preact) component was already possible. It is now also possible to use existing core form-js components in the renderer. + +```javascript +import { + Errors, + Description, + Label +} from '@bpmn-io/form-js'; + +import { + html +} from 'diagram-js/lib/ui'; + +export function RangeRenderer(props) { + + // ... + + return html`
+ <${Label} + id=${ prefixId(id, formId) } + label=${ label } /> +
+ // ... +
+ <${Description} description=${ description } /> + <${Errors} errors=${ errors } id=${ errorMessageId } /> +
`; +} +``` + +
+ + The custom range component in the form viewer. + + +

+ Render a custom range component into the form viewer. +

+
+ +We also added new options to a form field `config` object. For example, you can now define the default properties panel entries that should be shown in the form editor. You can also specify an icon for the form component. + +```javascript +import { + Numberfield +} from '@bpmn-io/form-js'; + +RangeRenderer.config = { + + /* we can even extend the configuration of existing fields */ + ...Numberfield.config, + type: rangeType, + label: 'Range', + iconUrl: `data:image/svg+xml,${ encodeURIComponent(RangeIcon) }`, + propertiesPanelEntries: [ + 'key', + 'label', + 'description', + 'min', + 'max', + 'disabled', + 'readonly' + ] +}; +``` + +That's all! The component library and properties panel will be automatically updated with the new form component, and the renderer will take over the rendering of the form component. + +
+ + The component library with the custom range component + + +

+ The custom range component gets populated into the component library. +

+
+ + +
+ + The properties panel with default entries for the custom range component + + +

+ Re-use existing properties entries. +

+
+ +Please find out more about [rendering extensions](https://github.com/bpmn-io/form-js-examples/tree/master/custom-components#add-a-custom-form-component-renderer) in our dedicated example. + + +## Create a properties panel extension + +We added the ability to extend the properties panel with custom entries. We mirrored the [proven provider architecture](https://bpmn.io/blog/posts/2022-new-properties-panel-foundation.html) of other bpmn.io properties panel libraries. + +Next to the `propertiesPanelEntries` we described above, you can create a properties provider that can add, remove, and modify existing entries. + +```javascript +export class CustomPropertiesProvider { + constructor(propertiesPanel) { + propertiesPanel.registerProvider(this, 500); + } + + getGroups(field, editField) { + + ... + return (groups) => { + + if (field.type !== 'range') { + return groups; + } + + const generalIdx = findGroupIdx(groups, 'general'); + + groups.splice(generalIdx + 1, 0, { + id: 'range', + label: 'Range', + entries: RangeEntries(field, editField) + }); + + return groups; + }; + } +} +``` + +
+ + Custom properties panel entries for the range component + + +

+ Custom properties panel entries for the range component. +

+
+ +Find out more about [properties panel extensions](https://github.com/bpmn-io/form-js-examples/tree/master/custom-components#add-custom-properties-panel-entries) in our dedicated example. + + +## Plugging everything together + +You can plug your custom modules into the different form-js components as `viewerAdditionalModules` and `editorAdditionalModules`. With the latest release, we also added the `additionalModules` option that allows you to provide extensions to both simultaneously, for example, the renderer. + + +```javascript +import { FormPlayground } from '@bpmn-io/form-js'; + +new FormPlayground({ + container, + schema, + data, + additionalModules: [ + RenderExtension + ], + editorAdditionalModules: [ + PropertiesPanelExtension + ] +}); +``` + +## Wrapping Up + +We'd love to hear your feedback on the new extension capabilities. We are looking forward to seeing what you build upon the new features! + +Did we miss anything? Did you spot a bug, or would you like to suggest an improvement? Reach out to us via [our forums](https://forum.bpmn.io/), tweet us [@bpmn_io](https://twitter.com/bpmn_io), or file an issue you found in [the form-js issue tracker](https://github.com/bpmn-io/form-js/issues). + +Get the latest Forms modeling toolkit pre-packaged or as source code via [npm](https://www.npmjs.com/package/@bpmn-io/form-js) or [unpkg](https://unpkg.com/@bpmn-io/form-js). \ No newline at end of file