# Conditional operations
Conditional Operations (CO) are operations that a user can perform on one or more data records. You can restrict a CO by using conditions, e.g. to make a certain operation available for the admin role only.
The following table lists the different types of conditional operations:
Name | Description |
---|---|
NativeOperations | Permissions of the CoreEngine such as Read, Delete, Edit, etc. |
Templates | Configured templates into which data records with their metadata are generated |
ActionOperations | Logic that is executed |
# Conditions
Conditions determine whether a CO may be executed and displayed based on the data record and the user. The client can use this information to show or hide functions. For example, a user gets the "Edit picture" operation only if the selected image matches the supported mimetypes.
<conditions>
<condition>
<value1 type="field"><!-- default: value -->
<value>status</value>
</value1>
<operator>=</operator><!-- default: '=' -->
<value2>
<value>1</value>
</value2>
</condition>
</conditions>
For extended requirements, conditions can also be defined by using the <sql>
tag. The content of this tag is appended to the WHERE
of the statement of the respective query.
The fields of the respective module can be accessed by name. The variables described below can be used within the <sql>
tag. The Template Engine is used to insert the variables.
<conditions>
<condition>
<sql>
'{$currentUser.role.roleName}' = '4ALLPORTAL Support'
AND type = 'image'
</sql>
</condition>
</conditions>
# Value types
Values can be specified within the <value1>
and <value2>
tags. Example: <value1 type="field">
.
You can use the following value types:
Name | Description |
---|---|
value | The value is taken directly from XML. You can define arrays by using multiple <value> tags. |
field | The field in the database. For example, if the <value> tag contains "status", a comparison is made with the "status" field in the current module. |
permission | The permission of the user for the current record (e.g. read all records, edit only own records ...) |
variable | The value is read from a dictionary stored in memory. |
feature | The value from the feature permissions of the current user. |
preset | The value from the presets of the current user. |
# Comparison operators
You can use the following comparison operators:
long form | short form |
---|---|
equal to | = |
not equal to | ! = |
like | |
not like | |
in | |
not in | |
less than | < |
greater than | > |
less than or equal to | <= |
greater than or equal to | >= |
is | |
is not |
# Logical operators
You can use the following logical operators:
- and
- or
- and not
- or not
# Variables
We currently support the following variables:
{$currentUser.role.roleName}
: the role name of the user{$currentUser}
: the current user as in "contact". All fields are available that are also available in the "contact" table (e.g.{$currentUser.firstname}
)- Specific operations can implement additional variables
Please also refer to the Template Engine documentation for more information.
# Dimensions
You can include special dimensions in a condition by using the <dimensions>
element inside a <value>
element:
<value1 field="price">
<dimensions>
<entry key="locale" class="array">
<value class="null" /> <!-- All values that have no dimension assigned. -->
<value>en_US</value>
</entry>
<entry key="channel" class="array">
<value>print</value>
<value>web</value>
</entry>
</dimensions>
</value1>
# NativeOperations
NativeOperations are determined by the permission management. They are displayed only for the records to which the user has a permission. Possible NativeOperations are:
- Read (
read
) - Delete (
del
) - Edit (
edit
) - Assign (
assign
) create_relation
delete_relation
Details about these permissions can be found here.
# Exceptions
create_relation
applies only to requests for a relation from a subpanel view. It is delivered as soon as you have an "edit" permission on the related bean.delete_relation
applies only to requests for a relation from a subpanel view. It is delivered as soon as you have an "edit" permission on one of the two relation modules.- For requests to the main view,
edit
andassign
are not delivered. delete
is not loaded for a detail view.
# ActionOperations
An ActionOperation or action is configured in the file system and is based on the OperationBase.
Actions are intended to trigger certain logics, i.e., code in the front end or back end.
- With actions, it is possible to implement an operation e.g. that copies a record and adjusts certain fields.
- It is also possible to display a form (Object Renderer) to the user to enter data for the operation.
- Also, dialogs such as an upload can be realized by implementations in the front end. In addition to the parameters described in the OperationBase, the display can also be restricted by using conditions.
You can configure ActionOperations here: <module>/actions/<action-name>.xml
Example:
<action>
<!-- refer to OperationBase -->
<!-- Action specific -->
<method></method><!-- MESSAGEBOX, INSTANT_CALL, FILE_ACCESS, FORM, FORM_SAVE -->
<conditions></conditions><!-- refer to Conditions -->
<classname></classname> <!-- Class for execution in the back end -->
<classloader></classloader><!-- Classloader of the class -->
<renderers>
<renderer>
<!-- refer to ObjectRenderer -->
</renderer>
</renderers>
</action>
Element | Description |
---|---|
<method> | MESSAGEBOX opens a popup with "Yes" and "No" buttons. "Yes" executes the back end implementation of <classname> .INSTANT_CALL executes the back end implementation directly on clicking. FILE_ACCESS opens the FileAccess popup (shows "Download" buttons). FORM opens a form popup. The data from this form will be sent to the back end when confirmed. FORM_SAVE opens a form popup. The data from this form are saved directly to the appropriate object(s). |
<conditions> | The action is only displayed if its conditions apply. |
<classname> | Class which must be loaded via a plugin in the back end. It must also implement the com.cm4ap.ce.vo.condoperation.action.IAction interface. |
<classloader> | Name of the Java classloader loaded into the class named in <classname> . |
<renderers> | Form displayed before the action is executed. Each renderer represents one page of the form. For more information, refer Object Renderer. |
# Action Parameters
The following parameters can be added to an action to produce a progress information toast:
Parameter | Description |
---|---|
showLongLoading | Parameter showLongLoading can be added and set to true or false (default).If set to true, a toast informs about an action taking longer than the defined timeout , counting until the first synchronous response. |
timeout | Parameter timeout defines the time before the toast appears in milliseconds (default: 3000). |
# OperationBase
The following configuration options apply to all COs that can be configured. These can be actions, templates, or other COs.
Example:
<any-co><!-- <action> or <template> -->
<label></label> <!-- translated -->
<info></info> <!-- translated -->
<icon></icon> <!-- icon (StyleManager) -->
<group></group> <!-- Group key -->
<order></order> <!-- Integer: define GUI order by weight -->
<views>
<!-- Define the visibility for each view. -->
<view visible="true|false">subpanel</view>
</views>
<min_beans>0</min_beans> <!-- Minimum beans to show up (-1 is infinite) -->
<max_beans>1</max_beans> <!-- Maximum beans to show up (-1 is infinite) -->
<enabled>true|false</enabled> <!-- If disabled, the CO is ignored -->
</any-co>
Element | Description |
---|---|
<label> | Text that is written on the button. Label keys (e.g. L-FILE-ADD_TO_BASKET ) are translated automatically. |
<info> | Text that appears as a tooltip when you mouse over. Label keys (e.g. L-FILE-ADD_TO_BASKET-INFO ) are translated automatically. |
<icon> | Icon from the icon servlet, which is displayed in front of the label text. |
group | Key name of the group. If two COs have the same group, they are displayed grouped in the GUI. |
group_label | Deprecated: group will be used to generate group label. For example L-FILE-CO-G-COLLECTIONS . Old behavior: Text that is written on the group. Label keys (e.g. L-FILE-ADMIN_ACTIONS) are translated automatically. |
group_info | Deprecated: group will be used to generate group info. For example L-FILE-CO-G-COLLECTIONS-INFO . Old behavior: Text that appears as a tooltip when you mouse over. Label keys (e.g. L-FILE-ADMIN_ACTIONS-INFO ) are translated automatically. |
<order> | Integer weighting for the order in the GUI. Negative values are also allowed. The NativeOperations use the range -11 to -6. The default value is 0. |
<views> | Controls the visibility of the CO per view. A view that is not specified is not delivered to the GUI. If the view is configured as visible="false" , the CO is delivered as not visible. GUI plugins can then react to this without the CO being displayed. Default: If no view is specified, the CO is displayed in all views. |
<min_beans> | If fewer data records are selected in the GUI than configured here, then the CO will not be delivered. The default value is 1. |
<max_beans> | If more data records are selected in the GUI than configured here, then the CO will not be delivered. -1 means there is no restriction. The default value is -1. |
<enabled> | If enabled is set to "false", the CO will not be delivered in any case, as if it did not exist. The default value is "true". |
Conditional operations in the GUI: Actions in the toolbox with configured icons and tooltips
# Conditional Operation Chaining
Conditional operation chaining allows you to execute multiple conditional operations in succession.
When a CO is executed, error code 428
can be returned instead of error code 0
(= OK). 428
is the sign for the front end that another CO must be executed. The operation is returned in the result-object.
Chaining can be used when there are CO preconditions that were not met when the operation was executed. E.g. for a CO that requires a confirmation prompt (e.g. for an operation that deletes records).
# Exemplary procedure
The operation in the back end should expect the confirmed
parameter to determine whether the user has confirmed the execution of the operation. If the operation is executed without this parameter, the back end assumes that the user has not confirmed the operation.
In this case, the back end returns error code 428
. In addition, the operation itself is returned in the result-object. Only this time the method
parameter of the conditional operation is set to a new value confirmation
.
In order for the front end to display a confirmation popup, a CondOperationPlugin must be implemented. It ensures that:
- the confirmation popup is displayed before the execution of all operations that are called with
method=confirmation
- that the
confirmed
parameter is included during execution
By doing this, the back end knows on the second attempt that the user has confirmed the execution of the operation.
# CondOperationPlugin
The CondOperationPlugin
is a plugin that is used to execute extended code when loading or executing COs. On the one hand, it can be used to supplement, replace or even cancel the handling of operations. On the other hand, the operations loaded by the back end can be supplemented with further operations or reduced by certain operations.
The entire processing of COs in the GUI works via this logic. If there is no corresponding plugin for an operation, no code will be executed on click.
This does not mean that for each additional operation something new has to be developed or a new plugin has to be created. But new operation types will probably not find any standard processing.
For some default operation types there are default plugins included in the CoreEngine GUI.
# Examples for conditions
# Compare field with value
<conditions>
<condition>
<value1 type="field"><value>status</value></value1>
<operator>!=</operator>
<value2><value>1</value></value2>
</condition>
</conditions>
# Compare value with value
<conditions> <!-- Always false -->
<condition>
<value1><value>1</value></value1>
<value2><value>0</value></value2>
</condition>
</conditions>
# Compare preset with value
<conditions>
<condition>
<value1 type="preset"><value>contact.can_mail</value></value1>
<value2><value>true</value></value2>
</condition>
</conditions>
# Compare field with preset
<conditions>
<condition>
<value1 type="field"><value>required_power</value></value1>
<operator>less than</operator>
<value2 type="feature"><value>contact.assign_power</value></value2>
</condition>
</conditions>
# Compare NativeOperation with value
<conditions>
<condition>
<value1 type="permission"><value>create</value></value1>
<value2><value>true</value></value2>
</condition>
</conditions>