You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/modules/bpm/pages/bpmn/jmix-view-forms.adoc
+26-72Lines changed: 26 additions & 72 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,85 +1,57 @@
1
1
= Jmix View Process Forms
2
2
3
-
When you need a process form with a complex layout and behavior,
4
-
use xref:flow-ui:index.adoc[Jmix views] instead of xref:bpm:input-dialog.adoc[input dialog] forms.
3
+
The xref:bpm:input-dialog.adoc[] forms discussed in the previous section are suitable for simple user interactions, such as data entry. However, Jmix allows you to use any views as process forms. This approach allows for process forms with complex layouts and behaviors tailored to your requirements.
5
4
6
-
[[processform-annotation]]
7
-
== `@ProcessForm` Annotation
8
-
9
-
A view controller should be annotated with the `@ProcessForm` annotation to be used as a process form.
10
-
This annotation has the following attributes:
11
-
12
-
* allowedProcessKeys
13
-
* outcomes
14
-
* params
15
-
* output variables
16
-
17
-
Using of these attributes described below.
18
-
19
-
[WARNING]
20
-
====
21
-
Avoid placing `@ProcessForm` annotation on existing Jmix views that were developed with other purposes.
22
-
Better create new ones from scratch with the help of the wizard or via extending existing views.
23
-
====
5
+
To use a view as a process form, annotate it with `@ProcessForm`.
24
6
7
+
TIP: Avoid using `@ProcessForm` on views designed for other purposes. It is better to create a new view or extend an existing one.
25
8
26
9
[[creating-jmix-view-form]]
27
10
== Creating Jmix View Form
28
11
29
-
First, set a _Jmix view_ form type for the user task or start event in the *BPMN Inspector* panel:
12
+
Select an element on the canvas. Then, in the *BPMN Inspector* panel, set the form type to _Jmix view_.
* By default, process variables of the _Entity_ type are represented in the form as _EntityPicker_ objects.
50
-
In the case when the user must select an entity instance from the list, it is OK.
51
28
52
-
* But if the user wants to have access to all entity's attributes, the _EntityPicker_ component isn't a suitable solution.
53
-
It would be more comfortable to have a form like standard entity detail view.
54
-
The second option allows to generate such a form automatically.
29
+
* _Process form with process variables_ (default) – Process variables of type Entity will be represented in the form using the _EntityPicker_ component. The value of the variable can be selected from a dropdown list.
30
+
* _Process form for entity instance_ – Process variables of type Entity will be represented using the standard entity detail view. Users will be able to see all attributes of the entity.
55
31
56
-
When selecting to create a _Process form for entity instance_, the wizard will ask about the entity class and fetch plan:
32
+
When selecting _Process form for entity instance_, you may need to specify the entity class and configure the fetch plan:
However, by default, the checkbox _Use existing variable_ is on and these details will be hidden.
36
+
NOTE: Some settings may be hidden if an existing variable is used (if the _Use existing variable_ checkbox is checked).
61
37
62
-
After you finish with the entity variable instance setting, the wizard offers to add process variables.
63
-
For example, let's add an `initiator` variable:
38
+
After configuring the entity variable instance, the wizard prompts to add process variables. For example, to add the variable `initiator`:
64
39
65
40
image::jmix-view-forms/add-variable.png[,900]
66
41
67
-
When it is added, you can decide whether to show it in the form or not:
42
+
When it is added, decide whether to display it in the form:
68
43
69
44
image::jmix-view-forms/variable-to-form.png[,670]
70
45
71
-
Further, the wizard offers to define form outcomes.
72
-
By default, `submit` and `reject` outcomes are created.
73
-
You can edit them or add new ones.
46
+
Next, the wizard prompts to specify the outcomes of the form. By default, two outcomes are created: `submit` and `reject`. You can edit these and add more.
74
47
75
48
image::jmix-view-forms/outcomes.png[,650]
76
49
77
-
At last, define messages that will be displayed in the form.
78
-
If there is more than one locale, you'll be able to enter messages for each language.
50
+
Add a message for the form. When localizing the application into multiple languages, you will have the option to add messages for each supported language.
79
51
80
52
image::jmix-view-forms/wizard-messages.png[,650]
81
53
82
-
Here the wizard ends its work and opens the form controller window with generated code:
54
+
After completing the wizard, the controller file with the generated code will open:
83
55
84
56
[source,java]
85
57
----
@@ -137,47 +109,31 @@ public class OrderApprovalForm extends StandardView {
137
109
}
138
110
----
139
111
140
-
141
112
[[process-variables]]
142
113
== Process Variables
143
114
144
-
To pass process variables into the Jmix view form, you have to inject them in the controller.
145
-
For this purpose, place `@ProcessVariable` annotation on injected UI components or regular class fields.
146
-
147
-
It indicates that the value of the process variable will be written to this field when the process form is opened.
148
-
In the case of the UI component, the value of the process variable will be set to the UI component.
149
-
150
-
Normally, the name of the annotated field in the controller matches the name of the process variable.
151
-
If not, use optional `name` attribute of `@ProcessVariable` annotation.
152
-
The value of this attribute must be the process variable name.
115
+
The `@ProcessVariable` annotation can be used to mark injected UI components or regular class fields. This annotation indicates that the value of the process variable will be written to this field when the process form is opened. In the case of a UI component, the variable's value will be set in that component.
To return process variables updated values back to the process,
160
-
you can invoke the <<process-form-context,ProcessFormContext>> with the `saveInjectedProcessVariables()` method.
161
-
In result, the values of annotated fields will be saved as process variables.
162
-
163
-
The wizard implements this behavior by default in click events handlers.
164
-
Or you can do this anywhere in your custom code.
122
+
The `@ProcessVariable` annotation includes an optional `name` attribute, which allows for the explicit specification of the name of the process variable associated with the field. If it is empty, then the process variable name matches the field name.
165
123
124
+
TIP: The `<<process-form-context,ProcessFormContext>>.saveInjectedProcessVariables()` methods enables saving values from annotated fields as process variables when starting the process or completing a user task.
166
125
167
126
[[process-form-context]]
168
127
== ProcessFormContext
169
128
170
-
The `ProcessFormContext` object contains information about a process definition to be started
171
-
(when the form is used for starting the process) or a user task to be completed.
129
+
The `ProcessFormContext` object contains information about the definition of the process being started (when the process is started using a form) or the user task that needs to be completed.
172
130
173
-
You can use `ProcessFormContext` if the process form is opened from the *Start process* and *My tasks* views.
174
-
If you need to open the process form with the injected `ProcessFormContext` programmatically,
175
-
use the <<opening-forms-programmatically,ProcessFormViews>> bean.
131
+
Use `ProcessFormContext` when the process form is opened from the xref:bpm:menu-views/start-process-view.adoc[] and xref:menu-views/my-tasks.adoc[] views. To open a process form with an injected `ProcessFormContext` programmatically, the bean <<opening-forms-programmatically,ProcessFormViews>> should be used.
176
132
177
-
The `ProcessFormContext` object also contains methods for starting the process and task completion.
133
+
The `ProcessFormContext` object also contains methods for starting and completing the process.
178
134
179
135
[[start-form-example]]
180
-
An example of how to start a process:
136
+
Consider the following example of starting a process:
0 commit comments