diff --git a/src/assets/attachments/blog/2023/006-range-component.png b/src/assets/attachments/blog/2023/006-range-component.png new file mode 100644 index 00000000..5ef1b713 Binary files /dev/null and b/src/assets/attachments/blog/2023/006-range-component.png differ diff --git a/src/blog/2023/006-custom-form-fields.md b/src/blog/2023/006-custom-form-fields.md new file mode 100644 index 00000000..3813eef3 --- /dev/null +++ b/src/blog/2023/006-custom-form-fields.md @@ -0,0 +1,165 @@ +--- + +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/006-range-component.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 about the latest [form-js](https://github.com/bpmn-io/form-js) improvements that adds new extension capabilities to create custom form components. It is easier now to use existing form-js components in your custom form component renderer 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 extenson features to the toolkit in the nature of common bpmn-io extension patterns. + +Check out our example 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 before. 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 } /> +
`; +} +``` + +We also added new options to a form field `config` object. As an example, you can now define the default properties panel entries that should be shown in the form editor. You can also define 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 palette and properties panel will be automatically updated with the new form component and the renderer will take over the rendering of the form component. + + + +Find out more about rendering extensions in our dedicated example. + + + + +## Create a properties panel extension + +We added the ability to extend the properties panel with custom entries. For this 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; + }; + } +} +``` + + + +Find out more about properties panel extensions in our dedicated example. + + + + +## Plugging everything together + +You can plug in 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 at the same time, 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 also looking forward to see 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