Customizing entity views

The following section gives an overview of common customizations for generated entity views.

Customizing the EntityViewFactoryBuilderInitializer

Changing entity names, property names or other labels

All entity names, property names and labels can be customized using message sources. For an explanation of the different message codes used, see the relevant appendix. More information can be found in the Customizing existing entities section.

See also the section on building-views/form-view.adoc#configuring-form-text for common customizations.

Setting page title or changing page layout

Setting a page title can be done by adding the corresponding message code. All default views automatically add a page title (optionally with sub text) if the corresponding message code resolves a non-empty string.

See the message codes appendix for a list of relevant message codes.

Changing the page layout

Entity views use a PageContentStructure for the base structure of the web page. The PageContentStructure is available as a request scoped bean, but can also be retrieved from the EntityViewRequest.

See the AdminWebModule reference documentation for a basic explanation of PageContentStructure.

Modifying the page layout for all (or a selection of) views

If you want to modify page layout for multiple views at runtime, you can subscribe to the EntityPageStructureRenderedEvent. This event is published during the postRender() phase and gives you context of the view that is being rendered, allowing you to make changes outside regular EntityViewProcessor implementations.

SingleEntityPageStructureViewProcessor and ListPageStructureViewProcessor are the view processors responsible for building the basic page structure and publishing the event.

Specifying a custom template

Every default view uses a specific (Thymeleaf) template that renders the ViewElement list created by the view. If you want control over the rendering through a separate template you can specify a different template using the template() method on the EntityViewFactoryBuilder.

EntityViewProcessor

Modifying a default view can be done by registering an EntityViewProcessor for that view. This API allows you to modify the ViewElement collection that should be generated. This is a useful hook to add for example custom form elements that you wish to add and process. If can also be used to reorganize the layout of the form from backend code using the ContainerViewElementUtils.

Using a custom EntityViewFactory

Full control can be done by registering a custom EntityViewFactory implementation.

Selecting properties

The properties that are rendered on a view can be customized using the showProperties method whilst customizing the view on an EntityConfiguration. showProperties takes only strings as it’s parameters, which can either be preconfigured selectors, property names or a combination of both.

Table 1. Listing of property selectors
Selector	Description
`.`	Keep all of the previously configured property rules.
`*`	Show all properties present in the property registry, after applying the default filter of the registry.
`**`	Show all properties present in the property registry, without applying the default filter of the registry.
`:readable`	Show all the properties that are readable.
`:writable`	Show all the properties that are writable.
`propertyName`	Show the property with name `propertyName`.
`~propertyName`	Do not show the property with name `propertyName`.

Example property selection

public void configure( EntitiesConfigurationBuilder entities ) {
    entities.withType( Book.class )
                 .createFormView( fvb -> fvb.showProperties( ".", "~publisher" ) ) (1)
                 .updateFormView( fvb -> fvb.showProperties( ".", "lastModified" ) ) (2)
                 .listView( lvb -> lvb.showProperties( "title", "author" ) ); (3)
}

1	Renders the previous property configuration but removes the `publisher` property.
2	Renders the previous property configuration and adds the `lastModified` property
3	Renders only the `title` and `author` properties.

Nested properties

Property names can also be a selection of nested properties. To select a nested property you can use the . notation e.g. author.name. When rendering a nested property, EntityModule renders it as an embedded object by rendering a fieldSet around your property.

You can only render the properties of the nested property by selecting them e.g. author.*.

Example nested property selection

public void configure( EntitiesConfigurationBuilder entities ) {
    entities.withType( Book.class )
                 .createFormView( fvb -> fvb.showProperties( "title", "author" ) ) (1)
                 .updateFormView( fvb -> fvb.showProperties( "title", "author.*" ) ) (2)
}

1	Renders the title property along with the author as an embedded object
2	Renders the title property along with the author properties (Without the fieldset)

Configuring views

Existing views can be modified or new ones registered using an EntityViewFactoryBuilder or EntityListViewFactoryBuilder. You usually don’t create these manually but get a builder for the corresponding view from the configuration or association builder.

The builders provide common properties that will configure one or more EntityViewProcessor instances on the view factory. They also allow you to modify the processor collection directly by adding or removing processors, or by post-processing the entire EntityViewProcessorRegistry.

Example adding an EntityViewProcessor to the default list view

configuration.withType( MyEntity.class )
             .listView( lvb -> lvb.viewProcessor( myProcessor ) );

The following chapters provide some more details on how to configure the default view types.