From 31688d583e59924981d329de49a10b014f1ed126 Mon Sep 17 00:00:00 2001 From: Valentin Serra Date: Tue, 30 Apr 2024 21:19:02 +0200 Subject: [PATCH] feat: document expression field in form element library (8.5) (#3633) * chore: improve dynamic list description in form element library * feat: document expression field in form element library * chore: backport expression field documentation to 8.5 --- .../forms-element-library-expression.md | 23 +++++++++++++++++++ .../forms-element-library.md | 8 ++++++- .../modeler/forms/sidebar-schema.js | 1 + optimize_sidebars.js | 4 ++++ static/img/form-icons/form-expression.svg | 3 +++ .../forms-element-library-expression.md | 23 +++++++++++++++++++ .../forms-element-library.md | 8 ++++++- .../modeler/forms/sidebar-schema.js | 1 + versioned_sidebars/version-8.5-sidebars.json | 1 + 9 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/components/modeler/forms/form-element-library/forms-element-library-expression.md create mode 100644 static/img/form-icons/form-expression.svg create mode 100644 versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library-expression.md diff --git a/docs/components/modeler/forms/form-element-library/forms-element-library-expression.md b/docs/components/modeler/forms/form-element-library/forms-element-library-expression.md new file mode 100644 index 0000000000..f4f24988c5 --- /dev/null +++ b/docs/components/modeler/forms/form-element-library/forms-element-library-expression.md @@ -0,0 +1,23 @@ +--- +id: forms-element-library-expression +title: Expression field +description: A form element to compute form state +--- + +An expression field allowing the user to compute new data based on form state. + +![Form Expression Field Symbol](/img/form-icons/form-expression.svg) + +### Configurable properties + +- **Key**: Binds the field to a form variable, refer to [data binding docs](../configuration/forms-config-data-binding.md). +- **Target value**: Defines an [expression](../../feel/language-guide/feel-expressions-introduction.md) to evaluate. +- **Compute on**: Defines when the expression should be evaluated. Either whenever the result changes, or only on form submission. +- **Deactivate if**: [Expression](../../feel/language-guide/feel-expressions-introduction.md) to disable the expression. +- **Columns**: Space the field will use inside its row. **Auto** means it will automatically adjust to available space in the row. Read more about the underlying grid layout in the [Carbon Grid documentation](https://carbondesignsystem.com/guidelines/2x-grid/overview). + +:::info + +The expression field is a simple way to create intermediary data which may be re-used within your form, or further down your process. To effectively use this component, a good understanding of [FEEL](../../feel/language-guide/feel-expressions-introduction.md) is required. + +::: diff --git a/docs/components/modeler/forms/form-element-library/forms-element-library.md b/docs/components/modeler/forms/form-element-library/forms-element-library.md index 7fed2d3666..6ecc1d125f 100644 --- a/docs/components/modeler/forms/form-element-library/forms-element-library.md +++ b/docs/components/modeler/forms/form-element-library/forms-element-library.md @@ -94,7 +94,7 @@ The following form elements are currently available within Camunda Forms: Dynamic List Symbol Dynamic list - Add and remove variable-length entries + Turn sets of form elements into editable lists @@ -109,6 +109,12 @@ The following form elements are currently available within Camunda Forms: Render tabular data + + Expression Symbol + Expression field + Compute intermediary data + + Image Symbol Image view diff --git a/docs/components/modeler/forms/sidebar-schema.js b/docs/components/modeler/forms/sidebar-schema.js index 6ff2cbbc27..83dc5b406e 100644 --- a/docs/components/modeler/forms/sidebar-schema.js +++ b/docs/components/modeler/forms/sidebar-schema.js @@ -23,6 +23,7 @@ module.exports = { lib_dir + "forms-element-library-dynamiclist", lib_dir + "forms-element-library-iframe", lib_dir + "forms-element-library-table", + lib_dir + "forms-element-library-expression", lib_dir + "forms-element-library-image", lib_dir + "forms-element-library-spacer", lib_dir + "forms-element-library-separator", diff --git a/optimize_sidebars.js b/optimize_sidebars.js index 218ed68ff1..32229ead89 100644 --- a/optimize_sidebars.js +++ b/optimize_sidebars.js @@ -720,6 +720,10 @@ module.exports = { "Table", "components/modeler/forms/form-element-library/forms-element-library-table/" ), + docsLink( + "Expression field", + "components/modeler/forms/form-element-library/forms-element-library-expression/" + ), docsLink( "Image view", "components/modeler/forms/form-element-library/forms-element-library-image/" diff --git a/static/img/form-icons/form-expression.svg b/static/img/form-icons/form-expression.svg new file mode 100644 index 0000000000..f499ebd528 --- /dev/null +++ b/static/img/form-icons/form-expression.svg @@ -0,0 +1,3 @@ + + + diff --git a/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library-expression.md b/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library-expression.md new file mode 100644 index 0000000000..f4f24988c5 --- /dev/null +++ b/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library-expression.md @@ -0,0 +1,23 @@ +--- +id: forms-element-library-expression +title: Expression field +description: A form element to compute form state +--- + +An expression field allowing the user to compute new data based on form state. + +![Form Expression Field Symbol](/img/form-icons/form-expression.svg) + +### Configurable properties + +- **Key**: Binds the field to a form variable, refer to [data binding docs](../configuration/forms-config-data-binding.md). +- **Target value**: Defines an [expression](../../feel/language-guide/feel-expressions-introduction.md) to evaluate. +- **Compute on**: Defines when the expression should be evaluated. Either whenever the result changes, or only on form submission. +- **Deactivate if**: [Expression](../../feel/language-guide/feel-expressions-introduction.md) to disable the expression. +- **Columns**: Space the field will use inside its row. **Auto** means it will automatically adjust to available space in the row. Read more about the underlying grid layout in the [Carbon Grid documentation](https://carbondesignsystem.com/guidelines/2x-grid/overview). + +:::info + +The expression field is a simple way to create intermediary data which may be re-used within your form, or further down your process. To effectively use this component, a good understanding of [FEEL](../../feel/language-guide/feel-expressions-introduction.md) is required. + +::: diff --git a/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library.md b/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library.md index 7fed2d3666..6ecc1d125f 100644 --- a/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library.md +++ b/versioned_docs/version-8.5/components/modeler/forms/form-element-library/forms-element-library.md @@ -94,7 +94,7 @@ The following form elements are currently available within Camunda Forms: Dynamic List Symbol Dynamic list - Add and remove variable-length entries + Turn sets of form elements into editable lists @@ -109,6 +109,12 @@ The following form elements are currently available within Camunda Forms: Render tabular data + + Expression Symbol + Expression field + Compute intermediary data + + Image Symbol Image view diff --git a/versioned_docs/version-8.5/components/modeler/forms/sidebar-schema.js b/versioned_docs/version-8.5/components/modeler/forms/sidebar-schema.js index 6ff2cbbc27..83dc5b406e 100644 --- a/versioned_docs/version-8.5/components/modeler/forms/sidebar-schema.js +++ b/versioned_docs/version-8.5/components/modeler/forms/sidebar-schema.js @@ -23,6 +23,7 @@ module.exports = { lib_dir + "forms-element-library-dynamiclist", lib_dir + "forms-element-library-iframe", lib_dir + "forms-element-library-table", + lib_dir + "forms-element-library-expression", lib_dir + "forms-element-library-image", lib_dir + "forms-element-library-spacer", lib_dir + "forms-element-library-separator", diff --git a/versioned_sidebars/version-8.5-sidebars.json b/versioned_sidebars/version-8.5-sidebars.json index 95f91be44c..9abca6798c 100644 --- a/versioned_sidebars/version-8.5-sidebars.json +++ b/versioned_sidebars/version-8.5-sidebars.json @@ -334,6 +334,7 @@ "components/modeler/forms/form-element-library/forms-element-library-dynamiclist", "components/modeler/forms/form-element-library/forms-element-library-iframe", "components/modeler/forms/form-element-library/forms-element-library-table", + "components/modeler/forms/form-element-library/forms-element-library-expression", "components/modeler/forms/form-element-library/forms-element-library-image", "components/modeler/forms/form-element-library/forms-element-library-spacer", "components/modeler/forms/form-element-library/forms-element-library-separator",