... |
... |
@@ -1,45 +1,48 @@ |
1 |
1 |
{{content/}} |
2 |
2 |
|
3 |
|
-== Interface IPluginFormPrePersist == |
|
3 |
+== Interface: IPluginFormPrePersist == |
4 |
4 |
|
5 |
|
-{{figure image="plugin_prepersist_en.png"}} |
6 |
|
-Position of pre-persist plugins in {{formcycle/}}'s program flow. They are run before submitted forms are saved. |
|
5 |
+{{figure image="plugin_prepersist.png" width="500"}} |
|
6 |
+Placement of the PrePersist plugin in the {{formcycle/}} process chain. |
7 |
7 |
{{/figure}} |
8 |
8 |
|
9 |
|
-=== Use cases === |
|
9 |
+=== Uses === |
10 |
10 |
|
11 |
|
-Allows you to add a custom check whether submitted forms are to be saved, or rejected. When a submitted form is rejected, it will not be processed any further. |
|
11 |
+Provides a way to build in a custom check if data should be saved. |
12 |
12 |
|
|
13 |
+If not, then an abort of further data processing can be caused at this point. |
|
14 |
+ |
13 |
13 |
{{warning}} |
14 |
|
-When multiple pre-persist plugins are installed, their order of execution is arbitrary. You should not rely on a certain fixed order. |
|
16 |
+When using multiple Form PrePersists implementations, the order in which they are executed is not fixed. The order may therefore be different each time. |
15 |
15 |
{{/warning}} |
16 |
16 |
|
17 |
17 |
{{warning}} |
18 |
|
-Pre-persist plugins are run for all forms of the client they belong to, or for all existing forms when installed as a system plugin. We recommend you check whether the plugin should be executed for the current form, for example by defining a [[plugin property>>doc:Main.PluginDevelopment.BundleProperties]] containing a list of allowed forms. |
|
20 |
+The //Form-PrePersistors// are basically executed before each form call in the respective application area (system or client plug-in) in which they were installed. It is recommended to first check in the implementation logic whether the //PrePersistierer// should be executed for the respective form processing. This can be made configurable, for example, by using //Bundle-Properties//. |
19 |
19 |
{{/warning}} |
20 |
20 |
|
21 |
|
-=== Method signature === |
|
23 |
+=== Method signatures === |
22 |
22 |
|
23 |
|
-{{code language="java"}} |
24 |
|
-IPluginFormPrePersistRetVal execute(IPluginFormPrePersistParams params) throws FCPluginException |
25 |
|
-{{/code}} |
|
25 |
+{{panel title="{{code language='java'~}~}IPluginFormPrePersistRetVal execute(IPluginFormPrePersistParams params) throws FCPluginException{{/code~}~}" triggerable="true" fullwidth="true"}} |
26 |
26 |
|
27 |
|
-== Parameters == |
|
27 |
+**Transfer value. |
|
28 |
+The //IPluginFormPrePersistParams// type provides access to the //IFormRequestContext// interface with the **getFormRequestContext()** method and thus to the following properties: |
|
29 |
+* **getCurrentUser():** the current user. |
|
30 |
+* **getUserContext():** the current user context, for example to be able to perform database operations |
|
31 |
+* **getProject():** the current project |
|
32 |
+* **getMandant():** the current client |
|
33 |
+* **getTask():** the current task |
|
34 |
+* **getFormVersion():** the current version of the form with access to all contained form elements |
|
35 |
+* **getLocale():** information about the currently selected language and region |
|
36 |
+* **getSessionAttributeMap():** a map with the current session parameters |
|
37 |
+* **getFrontendServer():** access to the frontend server object if called via frontend server |
28 |
28 |
|
29 |
|
-An object of type //IPluginFormPrePersistParams// will be passed to the execute method, providing access to an object of type //IFormRequestContext//. A form request context provides you with access to many properties of the submitted form, including: |
|
39 |
+**Return values:** |
30 |
30 |
|
31 |
|
-* the current project (//getProjekt()//) |
32 |
|
-* the current client ((//getMandant()//) |
33 |
|
-* the current form record (//getVorgang()//) |
34 |
|
-* the current version of the form with all form fields (//getFormVersion()//) |
35 |
|
-* session attributes (//getSessionAttributes()//) |
36 |
|
-* current user context that can be used for accessing the database(//getUserContext()//) |
|
41 |
+The return value must be of type //IPluginFormPrePersistRetVal//. |
|
42 |
+A reference implementation is provided by the class //PluginGenericFormProcessingRetVal//. On initialisation, this expects a boolean value. |
|
43 |
+: //true// |
|
44 |
+:: Further processing in {{formcycle case="dat"/}} is continued. |
|
45 |
+: //false// |
|
46 |
+:: Further processing in {{formcycle case="dat"/}} is aborted. |
37 |
37 |
|
38 |
|
-== Return value == |
39 |
|
- |
40 |
|
-The execute method must return an object implementing {{jpath path="de.xima.fc.interfaces.plugin.retval.form.IPluginFormPrePersistRetVal"/}}. |
41 |
|
- |
42 |
|
-The class {{jpath path="de.xima.fc.interfaces.plugin.retval.form.IPluginFormPrePersistRetVal"/}} provides a reference implementation. Its constructor expects a boolean flag //continueProcessing//: |
43 |
|
- |
44 |
|
-* {{litem title="true"}}The form will be accepted and processed further.{{/litem}} |
45 |
|
-* {{litem title="false"}}The form will not be saved and all further processing stops.{{/litem}} |
|
48 |
+{{/panel}} |