Extending linkki

Faktor-IPS Extension

linkki is often used in conjunction with Faktor-IPS. The module linkki-ips-vaadin8 provides some useful functionalities for this combination.

To use the extension simply include the following Maven dependency:

<dependency>
    <groupId>org.linkki-framework</groupId>
    <artifactId>linkki-ips-vaadin8</artifactId>
</dependency>

Fields for Faktor-IPS Data Types

A new UI component annotation @UIDecimalField supports the Faktor-IPS data type Decimal. It is quite similar to @UIDoubleField but supports Decimal instead of Double.

Other Faktor-IPS-specific fields - for example a Money field - may follow.

Faktor-IPS Model Validation

Validating a Faktor-IPS object yields messages for the validation framework on the business layer. linkki uses its own validation message implementation in the UI layer. To convert these messages from Faktor-IPS to linkki, the Faktor-IPS extension provides a MessageConverter. Objects are converted according to the following table:

Faktor-IPS linkki Notes

org.faktorips.runtime.Message

org.linkki.core.binding.validation.message.Message

org.faktorips.runtime.MessageList

org.linkki.core.binding.validation.message.MessageList

org.faktorips.runtime.ObjectProperty

org.linkki.core.binding.validation.message.ObjectProperty

The MessageConverter currently does not map the index field

org.faktorips.runtime.IMarker

org.linkki.ips.messages.ValidationMarkerWrapper

linkki only uses the isRequiredInformationMissing() method

Calling the Faktor-IPS validation method and converting the messages should be done directly in a ValidationService, which is then provided to the BindingManager.

A minimal validation service using lambda notation
() -> MessageConverter.convert(ipsModelObject.validate(new ValidationContext(UiFramework.getLocale())));

When the function above is called by linkki, the Faktor-IPS object is validated according to the defined validation rules. Rules can add messages to the returned MessageList, potentially referencing specific fields using ObjectProperty.

These messages are then converted, and displayed to the user. Messages referring to an ObjectProperty bound by linkki to a UI field, are shown in the UI accordingly. It is possible to define further styling.

Faktor-IPS Property Dispatcher

A special PropetyDispatcher called IpsPropertyDispatcher could be used in a binding context to get some information from the Faktor-IPS model when using appropriate model binding.

In case you do not specify a label for a UI component in your PMO the dispatcher tries to retrieve the label from the underlying model object. That means, if your underlying model object is generated by Faktor-IPS and the associated bound model attribute is a Faktor-IPS attribute, it returns the label of this Faktor-IPS attribute.

To include the IpsPropertyDispatcher as a custom dispatcher in the BindingContext, the IpsPropertyDispatcherFactory can be provided to the constructor of the DefaultBindingManager. If you already have a custom PropertyDispatcherFactory you could simply instantiate the IpsPropertyDispatcher in your subclass using the factory method IpsPropertyDispatcher#createIpsPropertyDispatcher.

Using IpsPropertyDispatcherFactory
BindingManager bindingManager = new DefaultBindingManager(validationService,
        PropertyBehaviorProvider.NO_BEHAVIOR_PROVIDER, new IpsPropertyDispatcherFactory());

PROPERTY Constants as Model Attributes

Faktor-IPS generates constants for defined attributes containing their name. These values can be used as the modelAttribute to easily create bound UI components.

If the used property is removed from the Faktor-IPS model while still being referenced from an annotation, a compilation error is generated. This would not be the case if hardcoded strings were used.

Excerpt of a class generated by Faktor-IPS
public static final String PROPERTY_STRING = "string";

@IpsAttribute(name = "string", kind = AttributeKind.CHANGEABLE, valueSetKind = ValueSetKind.AllValues)
public String getString() {
    return string;
}
Using the class above as a model object
@ModelObject
private final IpsModelObject modelObject;

@UITextField(position = 0, modelAttribute = IpsModelObject.PROPERTY_STRING)
public void getString() {
    // model binding
}