Customizing entity views
The following section gives an overview of common customizations for generated entity views.
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.
See also the section on configuring form controls 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.
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
.
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.
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. |
|
Show all the properties that are readable |
|
Show all the properties that are writable |
|
Show the property with name |
|
Do not show the property with name |
public void configure( EntitiesConfigurationBuilder configuration ) {
configuration.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. |
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
.
configuration.withType( MyEntity.class )
.listView( lvb -> lvb.viewProcessor( myProcessor ) );
The following chapters provide some more details on how to configure the default view types.