You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/02/23 09:31:57 UTC
[isis] 04/04: ISIS-2444: brings in hook pages for
@DomainObjectLayout
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit a81437eeb40eabcb3c2616ec06f147d46c89e584
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Feb 23 09:31:32 2021 +0000
ISIS-2444: brings in hook pages for @DomainObjectLayout
---
...s.adoc => DomainObjectLayout_011-cssClass.adoc} | 16 +--
...adoc => DomainObjectLayout_012-cssClassFa.adoc} | 17 +--
...doc => DomainObjectLayout_013-describedAs.adoc} | 16 +--
...amed.adoc => DomainObjectLayout_014-named.adoc} | 36 +++--
...doc => DomainObjectLayout_015-bookmarking.adoc} | 16 +--
...aged.adoc => DomainObjectLayout_016-paged.adoc} | 11 +-
.../hooks/DomainObjectLayout_019-ui-events.adoc | 151 +++++++++++++++++++++
.../hooks/DomainObject_011-domain-events.adoc | 2 +-
...adoc => DomainObject_012-lifecycle-events.adoc} | 8 +-
.../DomainObjectLayout/cssClassUiEvent.adoc | 101 --------------
.../DomainObjectLayout/iconUiEvent.adoc | 101 --------------
.../DomainObjectLayout/layoutUiEvent.adoc | 105 --------------
.../DomainObjectLayout/plural.adoc | 22 ---
.../DomainObjectLayout/titleUiEvent.adoc | 101 --------------
14 files changed, 191 insertions(+), 512 deletions(-)
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClass.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_011-cssClass.adoc
similarity index 61%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClass.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_011-cssClass.adoc
index a5b1f9e..53ffed6 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClass.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_011-cssClass.adoc
@@ -1,12 +1,11 @@
-[#cssClass]
-= `cssClass()`
+=== CSS Styling
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-The `cssClass` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.
+The xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClass[cssClass] element can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.
xref:refguide:config:application-specific/application-css.adoc[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
For example:
@@ -22,15 +21,6 @@ public class ToDoItem { /* ... */ }
[NOTE]
====
-The similar xref:system:generated:index/applib/annotation/DomainObjectLayout.adoc#cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
+The similar xref:system:generated:index/applib/annotation/DomainObjectLayout.adoc#cssClassFa[`@DomainObjectLayout#cssClassFa()`] element is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
====
-== See also
-
-This attribute can also be applied to:
-
-* xref:system:generated:index/applib/annotation/ActionLayout.adoc#cssClass[actions]
-* xref:system:generated:index/applib/annotation/PropertyLayout.adoc#cssClass[properties],
-* xref:system:generated:index/applib/annotation/CollectionLayout.adoc#cssClass[collections]
-* xref:system:generated:index/applib/annotation/ParameterLayout.adoc#cssClass[parameters].
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClassFa.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_012-cssClassFa.adoc
similarity index 64%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClassFa.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_012-cssClassFa.adoc
index f5430f9..cf9a806 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClassFa.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_012-cssClassFa.adoc
@@ -1,12 +1,11 @@
-[#cssClassFa]
-= `cssClassFa()`
-r
+=== Font Awesome Icons
+
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-The `cssClassFa` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
+The xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassFa[cssClassFa] element is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
If necessary the icon specified can be overridden by a particular object instance using the xref:refguide:applib-methods:reserved.adoc#iconName[`iconName()`] method.
@@ -26,16 +25,10 @@ There can be multiple "fa-" classes, eg to mirror or rotate the icon.
There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list.
The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
-The related `cssClassFaPosition` attribute is currently unused for domain objects; the icon is always rendered to the left.
+The related xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassFaPosition[cssClassFaPosition] element is currently unused for domain objects; the icon is always rendered to the left.
[TIP]
====
-The similar xref:system:generated:index/applib/annotation/DomainObjectLayout.adoc#cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
+The similar xref:system:generated:index/applib/annotation/DomainObjectLayout.adoc#cssClass[@DomainObjectLayout#cssClass()] element is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
====
-== See also
-
-These attributes can also be applied to:
-
-* xref:system:generated:index/applib/annotation/ActionLayout.adoc#cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/describedAs.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_013-describedAs.adoc
similarity index 66%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/describedAs.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_013-describedAs.adoc
index a5fd0f9..d07e950 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/describedAs.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_013-describedAs.adoc
@@ -1,11 +1,10 @@
-[#describedAs]
-= `describedAs()`
+=== Descriptions
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-The `describedAs` attribute is used to provide a short description of the domain object to the user.
+The xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#describedAs[describedAs] element is used to provide a short description of the domain object to the user.
In the xref:vw:ROOT:about.adoc[Wicket viewer] it is displayed as a 'tool tip'.
For example:
@@ -22,14 +21,3 @@ public class ProspectiveSale {
}
----
-
-
-== See also
-
-The attribute can also be specified for:
-
-* xref:system:generated:index/applib/annotation/CollectionLayout.adoc#describedAs[collections]
-* xref:system:generated:index/applib/annotation/PropertyLayout.adoc#describedAs[properties]
-* xref:system:generated:index/applib/annotation/ActionLayout.adoc#describedAs[actions]
-* xref:system:generated:index/applib/annotation/ParameterLayout.adoc#describedAs[parameters] and
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/named.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_014-named.adoc
similarity index 59%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/named.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_014-named.adoc
index f496fe2..70fa9a4 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/named.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_014-named.adoc
@@ -1,11 +1,10 @@
-[#named]
-= `named()`
+=== Names
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-The `named` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code.
+The xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#named[named] element explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code.
[TIP]
====
@@ -25,19 +24,26 @@ public class CustomerImpl implements Customer{
}
----
-It's also possible to specify a xref:system:generated:index/applib/annotation/DomainObjectLayout.adoc#plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
-====
+==== Plural form
-== See also
+When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
+By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
-The attribute can also be specified for:
+For irregular plurals it's possible to specify a plural form using the xref:system:generated:index/applib/annotation/DomainObjectLayout.adoc#plural[plural] element.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(plural="Children")
+public class Child {
+ // ...
+}
+----
+
+
+==== i18n
+
+The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
-* xref:system:generated:index/applib/annotation/ActionLayout.adoc#named[actions]
-* xref:system:generated:index/applib/annotation/CollectionLayout.adoc#named[collections]
-* xref:system:generated:index/applib/annotation/PropertyLayout.adoc#named[properties]
-* xref:system:generated:index/applib/annotation/ParameterLayout.adoc#named[parameters]
-* xref:system:generated:index/applib/annotation/DomainServiceLayout.adoc#named[domain services].
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/bookmarking.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_015-bookmarking.adoc
similarity index 77%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/bookmarking.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_015-bookmarking.adoc
index b84ee5c..db2b658 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/bookmarking.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_015-bookmarking.adoc
@@ -1,22 +1,16 @@
-[#bookmarking]
-= `bookmarking()`
+=== Bookmarks
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-The `bookmarking` attribute indicates that an entity is automatically bookmarked.
-This attribute is also supported for xref:system:generated:index/applib/annotation/ActionLayout.adoc#bookmarking[domain objects].
+The xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#bookmarking[bookmarking] element indicates that an entity is automatically bookmarked.
In the xref:vw:ROOT:about.adoc[Wicket Viewer], a link to a bookmarked object is shown in the bookmarks panel:
image::reference-annotations/DomainObjectLayout/bookmarking.png[width="720px"]
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:vw:ROOT:about.adoc[Wicket viewer] UI (specifically, pre 1.8.0).
-====
For example:
@@ -35,10 +29,6 @@ For example:
image::reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px"]
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:vw:ROOT:about.adoc[Wicket viewer] UI (specifically, pre 1.8.0).
-====
For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark, but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark _but only if_ its parent `Property` has already been bookmarked.
@@ -64,5 +54,3 @@ public abstract class Unit {
The nesting can be done to any level.
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/paged.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_016-paged.adoc
similarity index 84%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/paged.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_016-paged.adoc
index f8bec55..c45de2f 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/paged.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_016-paged.adoc
@@ -1,12 +1,10 @@
-[#paged]
-= `paged()`
+= Paging
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-
-The `paged` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation.
+The xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#paged[paged] element specifies the number of rows to display in a standalone collection, as returned from an action invocation.
[WARNING]
====
@@ -28,8 +26,3 @@ public class Order {
It is also possible to specify a global default for the page size of standalone collections, using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object-layout.paged[`isis.applib.annotation.domain-object-layout.paged`] configuration property.
-== See also
-
-This attribute can also be applied to:
-
-* xref:system:generated:index/applib/annotation/CollectionLayout.adoc#paged[collections]
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_019-ui-events.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_019-ui-events.adoc
new file mode 100644
index 0000000..efad71b
--- /dev/null
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObjectLayout_019-ui-events.adoc
@@ -0,0 +1,151 @@
+=== UI Events
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
+:page-partial:
+
+
+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 xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`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 xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[@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 xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[@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 xref:refguide:applib:index/annotation/DomainObject.adoc[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 xref:refguide:applib-methods:reserved.adoc[reserved method] directly (for example xref:refguide:applib-methods:reserved.adoc#title[title()], then that will take precedence.
+
+The table below summarises all the UI event hooks:
+
+[cols="2a,5a,5a,4a,3a"]
+|===
+| UI hint
+| Config property
+| @DomainObjectLayout override
+| Framework event types
+| Reserved method
+
+| CSS class
+|xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object-layout.css-class-ui-event.post-for-default[isis.applib.annotation.domain-object-layout.css-class-ui-event.post-for-default]
+| xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#cssClassUiEvent[cssClassUiEvent]
+m| CssClassUiEvent.Default +
+CssClassUiEvent.Doop +
+CssClassUiEvent.Noop
+|xref:refguide:applib-methods:reserved.adoc#cssClass[cssClass()]
+
+| Icon Name
+|xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object-layout.icon-ui-event.post-for-default[isis.applib.annotation.domain-object-layout.icon-ui-event.post-for-default]
+| xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#iconUiEvent[iconUiEvent]
+m| IconUiEvent.Default +
+IconUiEvent.Doop +
+IconUiEvent.Noop
+|xref:refguide:applib-methods:reserved.adoc#iconName[iconName()]
+
+| Layout
+|xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object-layout.layout-ui-event.post-for-default[isis.applib.annotation.domain-object-layout.layout-ui-event.post-for-default]
+| xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#layoutUiEvent[layoutUiEvent]
+m| LayoutUiEvent.Default +
+LayoutUiEvent.Doop +
+LayoutUiEvent.Noop
+|xref:refguide:applib-methods:reserved.adoc#layout[layout()]
+
+| Title
+|xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object-layout.title-ui-event.post-for-default[isis.applib.annotation.domain-object-layout.title-ui-event.post-for-default]
+| xref:refguide:applib:index/annotation/DomainObjectLayout.adoc#titleUiEvent[titleUiEvent]
+m| TitleUiEvent.Default +
+TitleUiEvent.Doop +
+TitleUiEvent.Noop
+|xref:refguide:applib-methods:reserved.adoc#title[title()]
+
+|===
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ iconUiEvent=ToDoItemDto.CssClassUiEvent.class,
+ titleUiEvent=ToDoItemDto.TitleUiEvent.class
+)
+public class ToDoItemDto {
+ public static class CssClassUiEvent
+ extends org.apache.isis.applib.events.ui.CssClassUiEvent<ToDoItemDto> { }
+ public static class TitleUiEvent
+ extends org.apache.isis.applib.events.ui.TitleUiEvent<ToDoItemDto> { }
+ ...
+}
+----
+
+==== Subscribers
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+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):
+
+[source,java]
+----
+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.
+
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_011-domain-events.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_011-domain-events.adoc
index 7064dff..d0a982d 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_011-domain-events.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_011-domain-events.adoc
@@ -2,7 +2,7 @@
Whenever an member of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
-For each of the three types of members (action, property and collection), the xref:refguide:applib:index/annotation/DomainObject.adoc[DomainObject] provides an element that defines a common event domain class to be fired whenever interating with members of that type.
+For each of the three types of members (action, property and collection), the xref:refguide:applib:index/annotation/DomainObject.adoc[DomainObject] provides an element that defines a common event domain class to be fired whenever interacting with members of that type.
This default event type can be overridden with a more specific event type if necessary.
[cols="3a,6a,7a"]
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_012-_lifecycle-events.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_012-lifecycle-events.adoc
similarity index 95%
rename from antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_012-_lifecycle-events.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_012-lifecycle-events.adoc
index 89d0964..bc89005 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_012-_lifecycle-events.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/DomainObject_012-lifecycle-events.adoc
@@ -3,8 +3,9 @@
Whenever the framework interacts with a domain entity, lifecycle events are fired.
These are:
-* instantiated through xref:refguide:applib:index/services/factory/FactoryService.adoc[`FactoryService`]
+* instantiated
+
+through xref:refguide:applib:index/services/factory/FactoryService.adoc[`FactoryService`].
An event is also fired for view models
* persisting
@@ -31,15 +32,14 @@ an already persistent entity has just been saved (``UPDATE``d) to the database
+
an already persistent entity is about to be removed (``DELETE``d) from the database
-
+The framework has a built-in event class (for each lifecycle hint) that is raised by default; for example a `ObjectUpdatingEvent.Default` is raised when an object is about to be updated.
Subscribers subscribe through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[`EventBusService`] and can use the event to obtain a reference to the object just created.
-The subscriber could then, for example, update the object, eg looking up state from some external datastore.
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 xref:refguide:applib:index/annotation/DomainObject.adoc[DomainObject] annotation (for each lifecycle hook) allows a different subtype event types to be emitted instead
+* second, an element on xref:refguide:applib:index/annotation/DomainObject.adoc[DomainObject] annotation (for each lifecycle hook) allows a different event subtype to be emitted instead
+
This allows subscribers to more targeted as to the events that they subscribe to.
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClassUiEvent.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClassUiEvent.adoc
deleted file mode 100644
index fd8ddb1..0000000
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/cssClassUiEvent.adoc
+++ /dev/null
@@ -1,101 +0,0 @@
-[#cssClassUiEvent]
-= `cssClassUiEvent()`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use in any wrapping ``<div>``s and ``<span>``s that render the domain object.
-This is as an alternative to implementing xref:refguide:applib-methods:reserved.adoc#cssClass[`cssClass()`] reserved method.
-(If `cssClass()` is present, then it will take precedence).
-
-Subscribers subscribe through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
-From this they can, if they wish, specify a CSS class for the domain object using the event's API.
-
-By default the event raised is `CssClassUiEvent.Default`.
-For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `cssClassUiEvent` attribute is to allows a custom subclass to be emitted instead.
-A similar attribute is available for titles and icons.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- iconUiEvent=ToDoItemDto.CssClassUiEvent.class
-)
-public class ToDoItemDto {
- public static class CssClassUiEvent
- extends org.apache.isis.applib.events.ui.CssClassUiEvent<ToDoItemDto> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe to events posted through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`].
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-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):
-
-[source,java]
-----
-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 `CssClassUiEvent#setCssClass(...)` to actually specify the CSS class to be used.
-
-== Default, Doop and Noop events
-
-If the `cssClassUiEvent` attribute is not explicitly specified (is left as its default value, `CssClassUiEvent.Default`), then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.cssClassUiEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `cssClassUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `CssClassUiEvent.Doop` as such a subclass, so setting the `cssClassUiEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `CssClassUiEvent.Noop`; if `cssClassUiEvent` attribute is set to this class, then no event will be posted.
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically either by calling the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] API directly.
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/iconUiEvent.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/iconUiEvent.adoc
deleted file mode 100644
index 1f9d7b6..0000000
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/iconUiEvent.adoc
+++ /dev/null
@@ -1,101 +0,0 @@
-[#iconUiEvent]
-= `iconUiEvent()`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the object (if possible).
-This is as an alternative to implementing xref:refguide:applib-methods:reserved.adoc#iconName[`iconName()`] reserved method.
-(If `iconName()` is present, then it will take precedence).
-
-Subscribers subscribe through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
-From this they can, if they wish, specify an icon name for the domain object using the event's API.
-
-By default the event raised is `IconUiEvent.Default`.
-For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `iconUiEvent` attribute is to allows a custom subclass to be emitted instead.
-A similar attribute is available for titles and CSS classes.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- iconUiEvent=ToDoItemDto.IconUiEvent.class
-)
-public class ToDoItemDto {
- public static class IconUiEvent
- extends org.apache.isis.applib.events.ui.IconUiEvent<ToDoItemDto> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe to events posted through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`].
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(IconUiEvent.class)
- public void on(IconUiEvent ev) {
- if(ev.getSource() instanceof ToDoItemDto) {
- ...
- }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(ToDoItemDto.IconUiEvent.class)
- public void on(ToDoItemDto.IconUiEvent ev) {
- ...
- }
-}
-----
-
-The subscriber should then use `IconUiEvent#setIconName(...)` to actually specify the icon name to be used.
-
-== Default, Doop and Noop events
-
-If the `iconUiEvent` attribute is not explicitly specified (is left as its default value, `IconUiEvent.Default`), then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.iconUiEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `iconUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `IconUiEvent.Doop` as such a subclass, so setting the `iconUiEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `IconUiEvent.Noop`; if `iconUiEvent` attribute is set to this class, then no event will be posted.
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically by calling the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] API directly.
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/layoutUiEvent.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/layoutUiEvent.adoc
deleted file mode 100644
index 5ebbc38..0000000
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/layoutUiEvent.adoc
+++ /dev/null
@@ -1,105 +0,0 @@
-[#layoutUiEvent]
-= `layoutUiEvent()`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-Whenever a domain object is to be rendered, the framework fires off an layout UI event to obtain an alternative layout name with which to render the domain object.
-This is as an alternative to implementing xref:refguide:applib-methods:reserved.adoc#layout[`layout()`] reserved method.
-(If `layout()` is present, then it will take precedence).
-
-Subscribers subscribe through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
-From this they can, if they wish, specify a CSS class for the domain object using the event's API.
-
-By default the event raised is `LayoutUiEvent.Default`.
-For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- // ...
-}
-----
-
-The purpose of the `layoutUiEvent` attribute is to allows a custom subclass to be emitted instead.
-A similar attribute is available for titles and icons.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- iconUiEvent=ToDoItemDto.LayoutUiEvent.class
-)
-public class ToDoItemDto {
-
- public static class LayoutUiEvent extends
- org.apache.isis.applib.events.ui.LayoutUiEvent<ToDoItemDto> { }
-
- // ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe to events posted through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`].
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(LayoutUiEvent.class)
- public void on(LayoutUiEvent ev) {
- if(ev.getSource() instanceof ToDoItemDto) {
- ...
- }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListner(ToDoItemDto.LayoutUiEvent.class)
- public void on(ToDoItemDto.LayoutUiEvent ev) {
- ...
- }
-}
-----
-
-The subscriber should then use `LayoutUiEvent#setLayout(...)` to actually specify the CSS class to be used.
-
-== Default, Doop and Noop events
-
-If the `layoutUiEvent` attribute is not explicitly specified (is left as its default value, `LayoutUiEvent.Default`), then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.layoutUiEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `layoutUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `LayoutUiEvent.Doop` as such a subclass, so setting the `layoutUiEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `LayoutUiEvent.Noop`; if `layoutUiEvent` attribute is set to this class, then no event will be posted.
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically by calling the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] API directly.
-
-
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/plural.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/plural.adoc
deleted file mode 100644
index 1b59f84..0000000
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/plural.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[#plural]
-= `plural()`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
-By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
-The `plural` attribute allows the plural form of the class name to be specified explicitly.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(plural="Children")
-public class Child {
- // ...
-}
-----
-
-
diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/titleUiEvent.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/titleUiEvent.adoc
deleted file mode 100644
index e065ad6..0000000
--- a/antora/components/refguide-index/modules/applib/pages/index/annotation/hooks/not-currently-referenced/DomainObjectLayout/titleUiEvent.adoc
+++ /dev/null
@@ -1,101 +0,0 @@
-[#titleUiEvent]
-= `titleUiEvent()`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:refguide:applib-methods:reserved.adoc#title[`title()`] reserved method, or using the xref:system:generated:index/applib/annotation/Title.adoc[`@Title`] annotation, within the class itself.
-(If either `title()` or `@Title` are present, then they will take precedence).
-
-Subscribers subscribe through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
-From this they can, if they wish, specify a title for the domain object using the event's API.
-
-By default the event raised is `TitleUiEvent.Default`.
-For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `titleUiEvent` attribute is to allows a custom subclass to be emitted instead.
-A similar attribute is available for icon names and CSS classes.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- titleUiEvent=ToDoItemDto.TitleUiEvent.class
-)
-public class ToDoItemDto {
- public static class TitleUiEvent
- extends org.apache.isis.applib.events.ui.TitleUiEvent<ToDoItemDto> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe to events posted through the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`].
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(TitleUiEvent.class)
- public void on(TitleUiEvent ev) {
- if(ev.getSource() instanceof ToDoItemDto) {
- ...
- }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(ToDoItemDto.TitleUiEvent.class)
- public void on(ToDoItemDto.TitleUiEvent ev) {
- ...
- }
-}
-----
-
-The subscriber should then use either `TitleUiEvent#setTranslatableTitle(...)` or `TitleUiEvent#setTitle(...)` to actually specify the title to be used.
-
-== Default, Doop and Noop events
-
-If the `titleUiEvent` attribute is not explicitly specified (is left as its default value, `TitleUiEvent.Default`), then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.titleUiEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `titleUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `TitleUiEvent.Doop` as such a subclass, so setting the `titleUiEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `TitleUiEvent.Noop`; if `titleUiEvent` attribute is set to this class, thn no event will be posted.
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically either by calling the xref:system:generated:index/applib/services/eventbus/EventBusService.adoc[`EventBusService`] API directly, or as a result of calling the xref:system:generated:index/applib/services/title/TitleService.adoc[`TitleService`]'s `titleOf(...)` method.
-
-