Differences

This shows you the differences between two versions of the page.

--- devel:documentation:application_configuration:dev:dynamic-forms [2019/02/04 11:38]
tomiskar [Regex]
+++ devel:documentation:application_configuration:dev:dynamic-forms [2021/02/10 18:20] (current)
tomiskar [Dynamic forms (eav)]
@@ Line 1: / Line 1: @@
 ====== Dynamic forms (eav) ======
-{{tag> configuration eav form}}
+{{tag> configuration eav form attachment}}
-Dynamic forms are used for:
-  * extending standard entity attributes with custom, project specific attributes,
-  * dynamic configurations - e.g. system connector configurations.
-Dynamic forms are supported for selected entities:
-  * ''SysSystem'' - linked to the systems
-  * ''IdmIdentity'' - identities
-  * ''IdmIdentityRole'' - assigned roles to identities (respectively assigned to identity contracts)
-  * ''IdmIdentityContract'' - Contractual relationships
-  * ''IdmRole'' - roles
-  * ''IdmTreeNode'' - tree structure items.
-  * ''IdmForm'' - [[#common_forms|common forms]]
-  * ''VsAccountFormValue'' - virtual system attributes
 Dynamic form instances (values) are saved in the individual tables according to the entity which they are linked to => which is their owner (e.g. the entity ''IdmIdentityFormValue'', ''IdmRoleFormValue''). Form values are not saved, if ''null'' value (by persistent type) is given => filled values are saved only.
 <note>
-**''FormService'' service for working with the extended attributes on the back-end.** **''FormInstance''** utility is useful on BE - contains value transformation to maps by attributes etc..
+**''FormService'' service for working with the extended attributes on the back-end.** **''FormInstance''** utility is useful on BE - contains value transformation to maps by attributes etc.. Use this service in your custom module, benefits:
+  * single autowired service for work with definitions, attributes and values
+  * cache ''core:form-definition-cache'' for loading form definitions (with attributes) is effective here.
 </note>
 <note>
@@ Line 27: / Line 15: @@
 <note important>Saving form values for the form definition work as **PATCH**. When attribute value has to be deleted, then form value with **null** has to be given (use it even for multi valued attributes).</note>
+<note>If single attribute is saved (''FormService#saveAttribute''), then event ''EAV\_SAVE'' is not published. Save all attributes (''FormService#saveValues''), if publishing event ''EAV_SAVE'' for owner is needed.</note>
 Dynamic form attribute supports data types (''persistentType''):
   * ''CHAR'' - one character
-  * ''TEXT'' -  strings (long text). Not indexed - ''SHORTTEXT'' usage is preferred.
+  * ''TEXT'' -  strings (long text). Searching by ''TEXT'' is not supported,  column is not indexed - **''SHORTTEXT'' usage is preferred (+ indexed)**.
   * ''SHORTTEXT'' - strings (2000 chars). Indexed.
   * ''INT'' - integer
@@ Line 40: / Line 30: @@
   * ''BYTEARRAY'' - byte[]
   * ''UUID'' - uuid identifier. Indexed.
-  * ''ATTACHMENT'' - attachment (~binary file). Read more about [[..:..:modules_rpt:dev:attachment_manager|attachments]].
+  * ''ATTACHMENT'' - attachment (~binary file). Read more about [[#attachments|attachments]].
+  * ''CODELIST'' - referenced code list - persists items "code" into short text. Uses face type as code list code.
+  * ''ENUMERATION'' referenced frontend enumeration - persists items "code" into short text. Uses face type as enumeration name.
@@ Line 56: / Line 48: @@
   * ''validationMessage'' - custom message, when some validation fails, [[#validation|read more]].
-Dynamic form attribute can be rendered differently on frontend. Face type (faceType) property is used for choosing frontend renderer. Default renderer is chosen by persistent type (e.g. UUID → UUID).
+Dynamic form attributes can be rendered differently on frontend. Face type (faceType) property is used for choosing frontend renderer. The default renderer is chosen by persistent type (e.g. UUID → UUID).
-Renderer is frontend component, superclass component ''AbstractFormAttributeRenderer'' is used for all renderer implementations. Renderer is responsible for ''IdmFormValue <=> input value'' transformation.
+Renderer is a frontend component, superclass component ''AbstractFormAttributeRenderer'' is used for all renderer implementations. Renderer is responsible for ''IdmFormValue <=> input value'' transformation.
 Renderers are registered in module's ''component-descriptor.js'' as single component with attributes:
@@ Line 69: / Line 61: @@
 All [[https://github.com/bcvsolutions/CzechIdMng/tree/develop/Realization/frontend/czechidm-core#component-descriptor|component descriptor]] features are supported. Read tutorial, [[tutorial:dev:how_to_create_eav_face_type|how to create custom form attribute renderer]].
+Custom configuration can be added to registered renderers (@since CzechIdM 10.8.0) - use ''AbstractFormAttributeRenderer'' on backend to define additional renderer properties.
 ===== Adding the support of extended attributes for a new entity =====
@@ Line 89: / Line 83: @@
 On the FE, there is an agenda of forms - their definition and attributes. Each definition can contain zero or more attributes. To maintain the integrity, an interface [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-api/src/main/java/eu/bcvsolutions/idm/core/api/entity/UnmodifiableEntity.java|UnmodifiableEntity]] has been created, which allows adding a flag that the entity has been created by the system and cannot be modified (or some of its attributes) and deleted (this logic now needs to be implemented manually into the relevant controllers), for example in [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/java/eu/bcvsolutions/idm/core/eav/rest/impl/IdmFormAttributeController.java|IdmFormAttributeController]].
-It is necessary to be cautious when editing individual form attributes as the logic linked to this form can be rendered non-functional.
 <note important>Data migration, when attribute's ''persistentType'' or ''confidential'' is changed is not supported now.</note>
-===== Common forms =====
-Common forms is used for saving internal dynamic forms for:
-- report filters
-- long running task properties (comming soon)
-- authorization policiy properties (comming soon)
-Form has to have form definition and owner, which can be an entity implementing ''FormableEntity'' interface. One owner can have more forms. When owner is deleted, then all forms have to be deleted to - override owner's service delete method properly. Form can be shared between owners - e.g. report filter can be used as input (properties) for long running task - this is the main reason, why common forms exists, don't use this common forms for storing extended attributes mentioned above (e.g. they will not be shown on frontend).
 ===== Localization =====
-For form attributes is possible add localization into cs.json and en.json for each module.
+<note important>Beware, **form type, form code and attribute code** is used for composing the key for localization and in the string ** all special characters (white spaces, dots, colons etc.) will by replaced by dash** (''spinal-case'' or ''kebab-case'' on frontend).</note>
-<note important>Beware, **form type, form code and attribute code** is used for compose key for localization and in the string **will by replaced all special characters (white spaces, dots, colons etc.) by dash** (''spinal-case'' or ''kebab-case'' on frontend).</note>
-<note tip>New tab on form definition detail can be used for creating localization.</note>
 Example form code **eu.bcvsolutions.idm.acc.entity.SysSystem** will be transformed into **eu-bcvsolutions-idm-acc-entity-syssystem**
@@ Line 116: / Line 96: @@
 ===== Validation =====
+{{tag>validation}}
-For form attribute values is possible to configure prepared validations. Validation are evaluated, when form with extended attributes is saved and sent to backend. Simple validations as ''required'', ''min'', ''max'' are evaluated on frontend after value is changed.
+For form attribute values is possible to configure prepared validations. Validation are evaluated (**on the backend**), when form with extended attributes is saved and sent to backend. Simple validations as ''required'', ''min'', ''max'' are evaluated on frontend after value is changed.
+<note important>Validations are suported for single attribute values only for now (feature request [[https://redmine.czechidm.com/issues/1874|#1874]]).</note>
 === Required ===
@@ Line 135: / Line 118: @@
 <note info>Min and max validation is supported for numeric ''DOUBLE'', ''INT'', ''LONG'' persistent types.</note>
-==== Regex ====
+=== Regex ===
 Value has to match given regular expression ([[https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html|java pattern]] is used).
@@ Line 148: / Line 131: @@
 </note>
-==== Validation message ====
+{{ :devel:documentation:application_configuration:dev:validation.png |}}
+=== Validation message ===
 Custom validation message. If message is not defined, then default message by invalid validation type will be shown.
 <note tip>Can contain localization key (e.g. ''core:validationError.invalid.unique''). Parameters ''min'', ''max'', ''regex'', ''unique'', ''required'' is available for localization message.</note>
 ===== Code lists =====
-Code list can be defined and used on frontend forms -> defines options for the select box (e.g. used on role detail for the ''environment'' attribute). Code lists items could have additional extended attributes.
-Code list works as decorator only. When whole code list is deleted, then the only impact is raw item codes will be rendered on frontend => when code list or code list item is not found, then raw value (item's code) is shown instead.
 <note tip>Use ''CodeListManager'' for creating and providing code lists and items through application on backend (e.g. available for scripts, which could be used in provisioning).</note>
@@ Line 169: / Line 152: @@
 ===== Authorization policies support =====
-Identity form values can be secured by authorization policies - see how to [[..:..:security:dev:authorization#secure_identity_form_extended_attribute_values|configure authorization policies]], when some identity extended attributes have to be secured.
+Identity form values can be secured by authorization policies when some identity extended attributes have to be secured - see how in [[..:..:security:dev:authorization#secure_identity_form_extended_attribute_values|configure authorization policies]].
+<note tip>Authorization policies only support identity extended attribute values. Support for other entities can be added in the future.</note>
-<note tip>Only identity extended attribute values support authorization policies. Support for other entities can be added in future.</note>
 ===== Future development =====
   * Form value data migration, when persistent type is changed.
-  * [[https://redmine.czechidm.com/issues/1140|#1140]] Add module into form definition table - now is module resolved dynamically by owner, but this cannot be overriden by module - e.g. when reg module adds new form for identity, localization is searched by owner in core module => and cannot be found.
+  * Attachment renderer: support multiple files, validation support (now is validation on input)
+  * Created deep copy, when form values are copied => attachment is linked to two form values and is removed, when the first one is deleted.
+  * [[https://redmine.czechidm.com/issues/1874|#1874]]: Support unique validation for multivalued eav attributes