How-to: Creating a custom control

On this page, you will learn how to create a custom control for rendering properties of a specific object type. We’ll be doing this in the following steps:

Creating a custom ViewElementBuilder that can be specified on a property.

Using the custom ViewElementBuilder when a specific viewElementType is specified.

Automatically using a specific viewElementType for properties of a specific object type.

Creating a custom ViewElementBuilder

In this section, we’ll be creating a custom ViewElementBuilder for a specific object type, that can be re-used in various rendering pipelines. As an example, we’ll be creating a control for a User object, so that a read-only value will be rendered as the avatar and the display name.

Starting off, we’ll create a custom ViewElementBuilder by extending ViewElementBuilderSupport.

public class UserValueViewElementBuilder extends ViewElementBuilderSupport (1)
{
    @Override
    protected MutableViewElement createElement ( ViewElementBuilderContext builderContext ){
		User user = EntityViewElementUtils.currentPropertyValue( builderContext, User.class ); (2)
		if ( user != null ) {
			return BootstrapUiBuilders.div()
			                   .css( "user-control" )
			                   .add( BootstrapUiBuilders.node( "img" )
			                                            .name( "avatar" )
			                                            .css( "user-avatar" )
			                                            .attribute( "src", user.getAvatar() )
			                                            .add( BootstrapUiBuilders.span()
			                                                                     .css( "user-name" )
			                                                                     .add( BootstrapUiBuilders.text( user.getDisplayName() ) ) )
			                   ).build();
		}
		return BootstrapUiBuilders.text( "" ).build() (3)
	}
}

1	The `ViewElementBuilder` extends `ViewElementBuilderSupport`. `ViewElementBuilderSupport` provides utility methods for creating a `ViewElement` as well as registering additional resources and processing.
2	The property that is being rendered is fetched from the `ViewElementBuilderContext` so that we have access to the properties of the object that is rendered.
3	If there is no value present, a default `ViewElementBuilder` is used.

Using the above setup, we could simply render a User property with the following configuration.

public void configure( EntitiesConfigurationBuilder entities ) { (1)
	entities.withType( Book.class )
	        .properties(
			        props -> props.property( "author" )
			                      .viewElementBuilder( ViewElementMode.FORM_READ, new UserValueViewElementBuilder() ) (2)
	        );
}

1	Entities can be configured by implementing the `EntityConfigurer` interface. This allows us to modify entities, their properties and their views when the `EntityConfiguration` is being built.
2	The created ViewElementBuilder is used when rendering a property.

Rendering a specified type as a custom ViewElement

Once we have our property available, we can register the ViewElementBuilder to be used when a specific view element type is used. We’ll create an EntityViewElementBuilderFactory, which will be used to render the correct ViewElement for each ViewElementMode.

@Component (1)
public class UserViewElementBuilderFactory implements EntityViewElementBuilderFactory
{
	public final static String USER_CONTROL = UserViewElementBuilderFactory.class.getName() + ".userControl"; (2)

	@Override
	public boolean supports( String viewElementType ) {
		return StringUtils.equals( USER_CONTROL, viewElementType ); (2)
	}

	@Override
	@SuppressWarnings("unchecked")
	public ViewElementBuilder createBuilder( EntityPropertyDescriptor entityPropertyDescriptor, ViewElementMode viewElementMode, String viewElementType ) {
		if ( !viewElementMode.isForMultiple() ) { (3)
			if ( isReadOnly( entityPropertyDescriptor ) && ViewElementMode.isValue( viewElementMode ) ) { (4)
				return new UserValueViewElementBuilder();
			}
		}
		return null;
	}

	private boolean isReadOnly( EntityPropertyDescriptor entityPropertyDescriptor ) {
		return !entityPropertyDescriptor.isWritable() && entityPropertyDescriptor.isReadable() && !entityPropertyDescriptor.isHidden();
	}
}

1	The `EntityViewElementBuilderFactory` is automatically picked up as a bean.
2	When a property is rendered with the specified view element type, this `EntityViewElementBuilderFactory` will generate a control in the specific value mode. In this case, the control is prefixed with the fully qualified path of the factory, to ensure a unique view element type is registered.
3	We only want to use the control in a case where a single user is rendered.
4	We only want to use the specified builder when a readonly value is rendered, e.g. as a value in a list, or as a value in a formGroup.

This allows us to refactor the configuration in the previous section to the following.

public void configure( EntitiesConfigurationBuilder entities ) {
	entities.withType( Book.class )
               .properties(
                       props -> props.property( "author" )
                                     .viewElementType( ViewElementMode.CONTROL, UserViewElementBuilderFactory.USER_CONTROL  ) (1)
               );
}

1	Instead of specifying a `ViewElementBuilder`, the view element type can be specified.

Finally, we’ll be creating a ViewElementTypeLookupStrategy, which will automatically use the view element type we’ve just defined when rendering properties of a given object type.

@Order(1) (1)
@Component
public class UserViewElementLookupStrategy implements ViewElementTypeLookupStrategy (2)
{
	@Override
	public String findElementType ( EntityPropertyDescriptor entityPropertyDescriptor, ViewElementMode viewElementMode ){
	Class<?> propertyType = entityPropertyDescriptor.getPropertyType();
	if ( propertyType != null && User.class.isAssignableFrom( propertyType ) ) { (3)
		if ( ViewElementMode.isValue( viewElementMode ) ) {
			return UserViewElementBuilderFactory.USER_CONTROL; (3)
		}
	}
	return null;
}

1	Our component is registered with `Order(1)` to ensure that it is used before the default `ViewElementTypeLookupStrategy`.
2	A `ViewElementTypeLookupStrategy` is created to automatically resolve the view element type for a given property.
3	In this case, we only want to specify the view element type for a property of the object type `User` when it is rendered in a value mode.

This allows us to entirely omit the EntityConfiguration that was defined earlier.

« Creating a custom property Creating a custom control Registering attributes on properties »