CUBA Component - Default Values

This application component lets you configure all kind of default values for entity attributes at runtime for better & faster UX... Let your application be the butler of your users - not the other way around!

Table of Contents

• Installation
• Supported DBMS
• Using the application component
• Default Value Configuration
  • Default Value Types
    • Static Value
    • Dynamic Value
    • Session Attribute
    • Script

Installation

1. default-values is available in the CUBA marketplace
2. Select a version of the add-on which is compatible with the platform version used in your project:

Platform Version	Add-on Version
7.2.x	0.2.x
7.1.x	0.1.x

The latest version is:

Add custom application component to your project:

• Artifact group: de.diedavids.cuba.defaultvalues
• Artifact name: defaultvalues-global
• Version: add-on version

dependencies {
  appComponent("de.diedavids.cuba.defaultvalues:defaultvalues-global:*addon-version*")
}

CHANGELOG

Information on changes that happen through the different versions of the application component can be found in the CHANGELOG. The Changelog also contains information about breaking changes and tips on how to resolve them.

Supported DBMS

The following databases are supported by this application component:

• HSQLDB
• PostgreSQL
• MySQL

All other DBMS systems are also possible to work with by the fact that CUBA studio generates the corresponding init / update scripts within the application.

Using the application component

Example usage

To see this application component in action, check out this example: cuba-example-using-default-values. It contains all examples of all the screenshots.

Creation of Entities with configured Default Values

Default Value Configuration

Default Values can be configured for entities via Administration > Entity Default Values. It contains a list of all Entities that are registered in the application.

Selecting one Entity opens the Details screen that shows the all attributes of the entity that fulfill this criteria:

• attribute is persistent
• attribute is not annotated with @SystemLevel or are part of System level Interfaces (like createTs e.g.)
• attribute is not a 1:N or M:N association

Default Value Types

There are multiple types of default values that can be configured for an entity attribute.

Static Value

A static value is used when a globally pre-configured value should be used for an entity attribute as the default value.

Examples:

• always set customer type to REGULAR
• always set the Group association of a User to Employees Group

Dynamic Value

Dynamic values compared to static values are evaluated at the time when the instance is created. Those values are dependent on the environment.

Examples:

• current date for the attribute orderDate of an order
• current user for a association from a customer to the User via the attribute accountManager
• locale of the current user for an attribute with a locale type

There are different dynamic value options for different datatypes. The application component itself defines the following dynamic value options:

• User
  • current user
  • current / substituted user
• Date
  • Today
• LocalDate
  • Yesterday
  • Today
  • Tomorrow

In case the datatype of the entity attribute has no options for dynamic values, it is not possible to select this option.

Custom Dynamic Values

It is also possible to create application specific dynamic value options. The application component defines an interface DynamicValueProvider that has to be implemented by a custom dynamic value.

The new dynamic value option needs to be a Spring bean in the global module of the application.

An example can be found in the example application: CustomerTypeFavoriteValueProvider

package com.company.ceudv;

import com.company.ceudv.entity.CustomerType;
import de.diedavids.cuba.defaultvalues.dynamicvalue.DynamicValueProvider;
import org.springframework.stereotype.Component;

@Component("ceudv_CustomerTypeFavoriteValueProvider")
public class CustomerTypeFavoriteValueProvider implements DynamicValueProvider<CustomerType> {

    @Override
    public String getCode() {
        return "customerTypeFavorite";
    }

    @Override
    public Class<CustomerType> getReturnType() {
        return CustomerType.class;
    }

    @Override
    public CustomerType get() {
        return CustomerType.favorite();
    }
}

The interface requires the following methods to be implemented:

• getCode - return a unique code / name of this dynamic value provider
• getReturnType - the type that this dynamic value is applicable for
• get - execution of the logic to return the default value

Additionally a translation value has be set in the main message pack of the web module:

dynamicValueProvider.customerTypeFavorite = Favorite Customer Type

• dynamicValueProvider. - prefix for translation of dynamic value providers
• customerTypeFavorite - the code of the dynamic value provider

With that, the dynamic value appears in the default value configuration UI and can be selected for all entity attributes that have the datatype CustomerType.

Session Attribute

A session attribute can also be placed into a entity attribute as a default value.

Examples:

• Preferred City for a new Customer based on the Access group the current user is in
• Default Group for a new User defined by the current local admin in multi tenant application

Session attributes are a good option, if user specific options should be leveraged when assigning a default value.

The session attribute concept of CUBA integrates the whole user group hierarchy into the value that is placed into the session.

More information on session attributes can be found in the CUBA docs: Session attributes.

NOTE: in the configuration UI the datatypes of the session attributes are not checked against the datatype of the entity attribute. If the datatypes do not match, the value will not be bound.

Another usage of a session attribute based default value is when a session attribute is programmatically assigned before the new entity is created.

For example it is possible to use this variant if a user globally for its current user session (until next logout) defines that (s)he now works on the asian area of the business. This would e.g. set the default country to China in the session. With a configured session attribute default value for a new customers country is now China.

Script

The last option is a script based default value. This option allows to define a groovy script, that programmatically determines the default value at the time when a new entity instance is created.

This option gives the most flexibility of all options and with a script all above mentioned options can also be achieved.

That being said, it requires the ability to write code in order to leverage that possibility.

The following attribute are available in the script:

• dataManager - DataManager instance for Database access from CUBA (com.haulmont.cuba.core.global.DataManager)
• beanLocator - Provides access to all managed beans from CUBA (com.haulmont.cuba.core.global.BeanLocator)
• timeSource - Global time source interface from CUBA (com.haulmont.cuba.core.global.TimeSource)

NOTE: The return type has to match the datatype of the entity attribute. If no value is returned, the Groovy evaluator will treat that execution as false