|
| 1 | +--- |
| 2 | +id: form-js-concepts |
| 3 | +title: "Concepts" |
| 4 | +description: "Understand the basic concepts of form-js" |
| 5 | +--- |
| 6 | + |
| 7 | +import clsx from "clsx"; |
| 8 | + |
| 9 | +import GHIcon from "@site/src/mdx/GitHubInlineIcon"; |
| 10 | +import FormViewer from "@site/src/mdx/FormViewer"; |
| 11 | +import FormPlaygroundImg from "./img/forms-playground.png"; |
| 12 | + |
| 13 | +import policyReviewForm from "./policyReviewForm.js"; |
| 14 | +import simpleForm from "./simpleForm.js"; |
| 15 | + |
| 16 | +Use form-js, the open-source library that powers Camunda Forms, to embed forms anywhere from vanilla JavaScript to low-code application platforms. With form-js, you can view, visually edit, and simulate forms that are based on pure JSON. |
| 17 | + |
| 18 | +## form-js basics |
| 19 | + |
| 20 | +The form-js project is made of three core libraries: the [form editor](https://github.com/bpmn-io/form-js/tree/develop/packages/form-js-editor) <GHIcon />, the [form viewer](https://github.com/bpmn-io/form-js/tree/develop/packages/form-js-viewer) <GHIcon />, and the [form playground](https://github.com/bpmn-io/form-js/tree/develop/packages/form-js-playground) <GHIcon />. |
| 21 | + |
| 22 | +### Form editor |
| 23 | + |
| 24 | +The [form editor](https://github.com/bpmn-io/form-js/tree/develop/packages/form-js-editor) <GHIcon /> allows to design forms with a drag'n'drop interface, and uses [FEEL expressions](/components/modeler/feel/what-is-feel.md) to execute form logic, such as visibility conditions, in realtime. Learn more about using the form editor in the [getting started guide](/guides/utilizing-forms.md). |
| 25 | + |
| 26 | +The form editor as it is shipped in Camunda 8 actually uses the [form playground](#form-playground), which provides realtime preview and validation functionality. |
| 27 | + |
| 28 | +### Form viewer |
| 29 | + |
| 30 | +The [form viewer](https://github.com/bpmn-io/form-js/tree/develop/packages/form-js-viewer) <GHIcon /> renders a form built using the form editor. It is versatile and can be embedded in any JavaScript application to render a form and capture user interactions. Learn more about embedding the form viewer on the following pages. |
| 31 | + |
| 32 | +See the following example form using the form viewer, and interact with it: |
| 33 | + |
| 34 | +<FormViewer schema={ policyReviewForm } /> |
| 35 | + |
| 36 | +### Form playground |
| 37 | + |
| 38 | +The [form playground](https://github.com/bpmn-io/form-js/tree/develop/packages/form-js-playground) <GHIcon /> is a tool to preview forms, simulate their behavior, and explore form-js in a playful manner. It combines the [editor](#form-editor) and the [viewer](#form-viewer) with mock data input and output panels to test a form and form editor features instantly. |
| 39 | + |
| 40 | +There is also a [Camunda-flavored version of the form playground](https://github.com/camunda/form-playground) <GHIcon />, which closely resembles the form editor experience in Camunda Web and Desktop Modeler, and supports rapid development. |
| 41 | + |
| 42 | +The form playground mainly comprises the following areas: |
| 43 | + |
| 44 | +- The **component palette** to search and add components. |
| 45 | +- The **editor canvas**, allowing to compose a form by dragging components. |
| 46 | +- The **preview pane**, which shows an interactive preview of the form. The preview updates in real-time when a change happens in the editor, properties panel, or mock input data. |
| 47 | +- The **properties panel**, which is used to configure the properties of a component. |
| 48 | +- The **data input panel**, which allows to simulate the form preview using mock input data. |
| 49 | +- The **output panel**, which calculates and shows the current form output in real-time, based on the interactions with the preview. |
| 50 | + |
| 51 | +The input and output panel, together with the preview, come in handy to simulate the behavior of a form, and to validate or debug the configuration of one or multiple components, especially when using expressions extensively. Use the input data panel to simulate process variables, business objects, or static data used in your form. |
| 52 | + |
| 53 | +<img src={FormPlaygroundImg} alt="Camunda Forms playground" /> |
| 54 | + |
| 55 | +<div style={{marginTop: '24px', marginBottom: '8px'}}> |
| 56 | + <a |
| 57 | + className={clsx( |
| 58 | + "button button--outline button--secondary button--lg" |
| 59 | + )} |
| 60 | + href="https://camunda-form-playground.netlify.app/"> |
| 61 | + Try form playground |
| 62 | + </a> |
| 63 | +</div> |
| 64 | + |
| 65 | +Try the form playground yourself directly on the web, no log in needed. |
| 66 | + |
| 67 | +## The form schema |
| 68 | + |
| 69 | +A form is serialized as plain JSON with a simple, flat structure to maximize flexibility and versatility. In the root, a form contains some metadata attributes. The main form is defined by a list of components, where the components carry their layout properties themselves (e.g. which row a component belongs to). This is in contrast to markup languages such as HTML, where the arrangement of the nodes determines the layout. This enables backward compatibility and compatibility with user-defined renderers. |
| 70 | + |
| 71 | +See this simple form schema for example, and the resulting form: |
| 72 | + |
| 73 | +```json |
| 74 | +{ |
| 75 | + "components": [ |
| 76 | + { |
| 77 | + "label": "First name", |
| 78 | + "type": "textfield", |
| 79 | + "layout": { |
| 80 | + "row": "Row_0hqc9xn", |
| 81 | + "columns": null |
| 82 | + }, |
| 83 | + "id": "Field_05l2s7c", |
| 84 | + "key": "firstName" |
| 85 | + }, |
| 86 | + { |
| 87 | + "label": "Last name", |
| 88 | + "type": "textfield", |
| 89 | + "layout": { |
| 90 | + "row": "Row_0hqc9xn", |
| 91 | + "columns": null |
| 92 | + }, |
| 93 | + "id": "Field_0nw7e1c", |
| 94 | + "key": "lastName" |
| 95 | + }, |
| 96 | + { |
| 97 | + "label": "Income", |
| 98 | + "type": "number", |
| 99 | + "layout": { |
| 100 | + "row": "Row_1ggwq2d", |
| 101 | + "columns": 8 |
| 102 | + }, |
| 103 | + "id": "Field_12yshuy", |
| 104 | + "key": "monthlyNetIncome", |
| 105 | + "description": "Monthly net income", |
| 106 | + "appearance": { |
| 107 | + "prefixAdorner": "USD" |
| 108 | + }, |
| 109 | + "increment": "100", |
| 110 | + "validate": { |
| 111 | + "required": true, |
| 112 | + "min": 0 |
| 113 | + } |
| 114 | + } |
| 115 | + ], |
| 116 | + "type": "default", |
| 117 | + "id": "ExampleForm", |
| 118 | + "executionPlatform": "Camunda Cloud", |
| 119 | + "executionPlatformVersion": "8.4.0", |
| 120 | + "exporter": { |
| 121 | + "name": "Camunda Modeler", |
| 122 | + "version": "5.18.0" |
| 123 | + }, |
| 124 | + "schemaVersion": 12 |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +<FormViewer schema={ simpleForm } /> |
| 129 | + |
| 130 | +All form-js packages share the same [JSON schema](https://github.com/bpmn-io/form-js/tree/develop/packages/form-json-schema) <GHIcon /> for forms. |
| 131 | + |
| 132 | +This enables the interoperability of the created forms between the form editor and the viewer and possibly also between custom-made form renderers, or translating from a Camunda Form to another form. Using the form schema, you can write extensions to existing components, while still receiving benefits from updates made to the core form-js libraries. |
| 133 | + |
| 134 | +The schema abstracts the form model from the viewer, and allows you to inject another expression or templating language as an alternative to FEEL, since expressions are simply stored as strings. |
| 135 | + |
| 136 | +The schema is built on top of and validated by [`json-schema@draft-07`](https://json-schema.org/draft-07/json-schema-release-notes.html). |
| 137 | + |
| 138 | +:::tip |
| 139 | +You can use tools like this [JSON Schema Viewer](https://navneethg.github.io/jsonschemaviewer/) to explore the schema visually, or this [tool from Atlassian](https://json-schema.app/view/%23?url=https%3A%2F%2Funpkg.com%2F%40bpmn-io%2Fform-json-schema%401.6.0%2Fresources%2Fschema.json) to validate a form against the schema. |
| 140 | +::: |
| 141 | + |
| 142 | +### Schema variables |
| 143 | + |
| 144 | +Form-js comes with versatile methods to extract the expected input and output variables from a form schema. This makes it easy to validate the input and output of a form, and you can combine it with data validation libraries like [joi](https://github.com/hapijs/joi) <GHIcon /> to ensure type and schema safety. Learn more about schema variables in the [embedding guide](./02-embed-in-javascript.md). |
| 145 | + |
| 146 | +## Examples |
| 147 | + |
| 148 | +Visit the [form-js examples repository](https://github.com/bpmn-io/form-js-examples) <GHIcon /> to explore form-js by playing with the toolkit. |
0 commit comments