Managing Dynamic Attributes

You can manage dynamic attributes in the Administration > Dynamic attributes screen. The screen has a list of categories on the left and attributes belonging to the selected category on the right.

After making changes in the dynamic attributes configuration, click Apply changes button.

Dynamic attributes screen displays actions for exporting the selected categories as ZIP or JSON and importing them to the system.

Creating Category

Before adding a dynamic attribute for an entity create a category for it. Set a name and select an entity the category is related to.

Is default checkbox indicates that this category will be automatically selected for a new instance if the entity implements the Categorized interface.

If the entity does not implement Categorized, the checkbox value is not used, and you can create either a single category for the entity or multiple categories - all their attributes will be displayed according to the visibility settings.

The Localization tab is shown on the category editor screen if the application supports more than one language. It enables setting the localized values of the category name for each available locale.

On the Attributes location tab, you can set the location of each dynamic attribute inside the DynamicAttributesPanel.

Specify the number of columns in the Columns count drop-down list. To change the position of an attribute, drag it from the attribute list to the needed column and the needed line. You can add empty cells or change the order of the attributes. After making the changes, click the Save configuration button.

Creating Attribute

General Settings

On the General tab of the Category attribute editor, you can set a name, system code, description, value type, the default value of the attribute, and the validation script.

For all value types, except Boolean, you can set up the width in the Form element in pixels or as a percentage. If the Width field is empty, its assumed value is 100%.

For all value types, except Boolean, the selected Is collection checkbox allows you to create multi-valued dynamic attributes of the chosen value type.

For the value types Double, Fixed-point number, and Integer, the following fields are available:

Minimum value - the entered attribute value will be checked that it is greater than or equal to the specified minimum value.
Maximum value - the entered attribute value will be checked that it is less than or equal to the specified maximum value.

For the Fixed-point number value type, you can specify a format pattern in the Number format pattern field. Set the pattern according to the rules described in DecimalFormat.

For all value types, you can specify a Groovy script in the Validation script field to validate the entered value. If Groovy validation fails, the script should return an error message. Otherwise, the script should return nothing or may return null. The checked value is available in the script in the value variable. The error message uses a Groovy string. You can use the $value key in the message to generate the result.

For example:

if (!value.startsWith("correctValue")) return "the value '\${value}' is incorrect"

For the Enumeration value type, you can set a list of named values in the Enumeration field via the list editor. Each enumeration value can be localized to the languages, available in the application.

For String, Double, Entity, Fixed-point number and Integer data types, the checkbox Lookup field is available. If this checkbox is set, you can select the attribute value from the drop-down list. The list of valid values can be configured on the Calculated values and options tab. For the Entity data type Where and Join clauses are configured.

Calculated Values and Options

On the Calculated values and options tab, you can specify which attributes the current attribute depends on. When changing the value of one of these attributes, either the script for calculating the attribute value or the script for calculating the list of possible values will be recalculated.

The Groovy script must return a new parameter value. The following variables are passed to the script:

entity - the currently edited entity.
dynamicAttributes - a map where a key is the attribute code, a value is the value of the dynamic attribute.

Example of a recalculation script using the EntityValues class:

Example of a recalculation script using the dynamicAttributes map:

if (dynamicAttributes['PassengerNumberofseats'] > 9) return 'Bus' else return 'Passenger'

Each time the value of one of the attributes from the Attributes depends on list is changed, the script will be executed.

If the script is defined, the attribute input field will be non-editable.

Recalculation works only with the formLayout and dynamicAttributesPanel UI components.

If the Lookup field checkbox is set on the General tab, you can select the type of the options loader from the Options type list.

Available option loader types: Groovy, SQL, JPQL (only for the Entity data type).

The Groovy options loader loads a list of values using the Groovy script. The entity variable is passed to the script where you can access the attributes of the entity including dynamic attributes. An example script for an attribute of String type:
The SQL options loader loads a list of values using the SQL script. You can access the entity id using the ${entity} variable. To access entity parameters, use the ${entity.<field>} construction, where field is the name of the entity parameter. The + prefix is used to access the dynamic attributes of the entity, such as ${entity.+<field>}. In the example, we access the entity and the dynamic attribute PassengerTypeofcar:
```
select LAST_NAME from SAMPLE_DRIVER
where CAR_TYPE = ${entity.+PassengerTypeofcar}
```
The JPQL option loader applies only to a dynamic attribute of the Entity type. JPQL conditions are specified in the Join clause and Where clause fields. You can use {entity} and {entity.<field>} variables in JPQL parameters.

A value of the Join clause field is added to the from query clause. It should begin with a comma, join, or left join.

Dynamic attributes values in the script are available by the entity variable: ${entity.+<dynamicAttrCode>}, where <dynamicAttrCode> - code of the corresponding dynamic attribute.

The {E} placeholder should be used as an alias of the entity being extracted. On execution of the query, it will be replaced with a real alias specified in the query.

For example:
```
join {E}.seller s
```
A value of the Where clause field is added to the where query clause using and condition. The where word is not needed, as it will be added automatically.

Dynamic attributes values in the script are also available by the entity variable. For example:

Localization

The Localization tab is shown if the application supports more than one language. Localization is supported for all types of dynamic attributes.

Visibility

You can define screens where a dynamic attribute should be displayed by setting visibility. By default, the attribute is not shown.

You should add dynamicAttributes facet to the screen to be able to choose the screen in the Visibility tab.

In addition to the screen, you can also specify a component in which the attribute should appear. For example, screens where several Form components show the fields of the same entity.

If the attribute is marked as visible on a screen, it will automatically appear in all forms and tables displaying entities of the corresponding type on the screen.

In case an entity implements the Categorized interface, you can use DynamicAttributesPanel.

Access to dynamic attributes can also be restricted by resource roles. Security settings for dynamic attributes are similar to those for regular attributes.