UI Events

Whenever a domain object is to be rendered, the framework fires off a number of various events to allow subscribers to influence the visual appearance of that domain object:

  • a CSS class UI event

    to obtain a CSS class to use in any wrapping <div>s and <span>s that render the domain object.

  • an icon UI event

    to obtain an icon (name) for the object (if possible)

  • a layout UI event

    to obtain an alternative layout name with which to render the domain object.

  • a title UI event

    to obtain a title for the object

The framework has a built-in event class (for each UI hint) that is raised by default; for example a TitleUiEvent.Default is raised to obtain a title for the object. Subscribers subscribe through the EventBusService and can use obtain a reference to the domain object from the event. From this they can, if they wish, specify the corresponding UI hint.

This basic model can be influenced in a couple of ways:

  • first, it is also possible to suppress any events from being emitted using a configuration property (a different config property exists each lifecycle hook).

  • second, an element on @DomainObjectLayout annotation (for each UI hook) allows a different subtype event types to be emitted instead

    This allows subscribers to more targeted as to the events that they subscribe to.

The type of this event can be changed using various xxxUiEvent elements of @DomainObjectLayout. This allows subscribers to be more precise as to the domain objects that they will target.

The framework also provides convenience "Doop" and a "Noop" event classes, that provoke these behaviours:

  • if the appropriate DomainObject' element is set to the "Doop" subclass, then this will event will be fired

    this is a convenient way of ensuring an event is fired even if the hook has been disabled globally, but without the hassle of defining a custom event type

  • if set to the "Noop" subclass, then an event will not be fired.

If the domain object implements the corresponding reserved method directly (for example title(), then that will take precedence.

The table below summarises all the UI event hooks:

UI hint

Config property

@DomainObjectLayout override

Framework event types

Reserved method

CSS class

causeway.applib.annotation.domain-object-layout.css-class-ui-event.post-for-default

cssClassUiEvent()

CssClassUiEvent.Default
CssClassUiEvent.Doop
CssClassUiEvent.Noop

cssClass()

Icon Name

causeway.applib.annotation.domain-object-layout.icon-ui-event.post-for-default

iconUiEvent()

IconUiEvent.Default
IconUiEvent.Doop
IconUiEvent.Noop

iconName()

Layout

causeway.applib.annotation.domain-object-layout.layout-ui-event.post-for-default

layoutUiEvent()

LayoutUiEvent.Default
LayoutUiEvent.Doop
LayoutUiEvent.Noop

layout()

Title

causeway.applib.annotation.domain-object-layout.title-ui-event.post-for-default

titleUiEvent()

TitleUiEvent.Default
TitleUiEvent.Doop
TitleUiEvent.Noop

title()

For example:

@DomainObjectLayout(
    iconUiEvent=ToDoItemDto.CssClassUiEvent.class,
    titleUiEvent=ToDoItemDto.TitleUiEvent.class
)
public class ToDoItemDto {
    public static class CssClassUiEvent
        extends org.apache.causeway.applib.events.ui.CssClassUiEvent<ToDoItemDto> { }
    public static class TitleUiEvent
    extends org.apache.causeway.applib.events.ui.TitleUiEvent<ToDoItemDto> { }
    ...
}

Subscribers

Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Service;

@Service
public class SomeSubscriber {
    @EventListener(CssClassUiEvent.class)
    public void on(CssClassUiEvent ev) {
        if(ev.getSource() instanceof ToDoItemDto) {
            ...
        }
    }
}

or can be fine-grained (by subscribing to specific event subtypes):

import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Service;

@Service
public class SomeSubscriber {
    @EventListener(ToDoItemDto.CssClassUiEvent.class)
    public void on(ToDoItemDto.CssClassUiEvent ev) {
        ...
    }
}

The subscriber should then use the appropriate method —  CssClassUiEvent#setCssClass(…​)  — to actually specify the CSS class to be used.