You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by ah...@apache.org on 2020/02/11 05:22:57 UTC
[isis] branch master updated: ISIS-2275: improving layout docs
This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 0e3c0e5 ISIS-2275: improving layout docs
0e3c0e5 is described below
commit 0e3c0e56a65a1795f38a1f22777e0afb9f07adf5
Author: Andi Huber <ah...@apache.org>
AuthorDate: Tue Feb 11 06:22:47 2020 +0100
ISIS-2275: improving layout docs
---
.../isis/applib/services/layout/LayoutService.java | 38 +++++++++++++++-------
.../adoc/modules/ROOT/pages/layout/file-based.adoc | 4 +--
2 files changed, 29 insertions(+), 13 deletions(-)
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java b/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
index ce40087..7b2f77f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
@@ -24,45 +24,61 @@ import org.apache.isis.applib.services.menu.MenuBarsService;
public interface LayoutService {
+ /**
+ * Mode of operation when downloading a layout file (while prototyping). It affects the way the file's
+ * content is assembled. Once a layout file is in place, its layout data takes precedence over any
+ * conflicting layout data from annotations.
+ */
enum Style {
/**
* The current layout for the domain class.
- * <p/>
* <p>
* If a <code>layout.xml</code> exists, then the grid returned will correspond to that
- * grid, having been {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}. If there is no <code>layout.xml</code> file, then the grid returned will be the
+ * grid, having been {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}.
+ * If there is no <code>layout.xml</code> file, then the grid returned will be the
* {@link org.apache.isis.applib.services.grid.GridService#defaultGridFor(Class) default grid},
* also {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}.
- * </p>
*/
CURRENT,
+
/**
* As per {@link #NORMALIZED}, but also with all (non-null) facets for all
* properties/collections/actions also included included in the grid.
- * <p/>
* <p>
* The intention here is that any layout metadata annotations can be removed from the code.
- * </p>
+ * <ul>
+ * <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
+ * <li>{@code @MemberOrder}: <b>serialized as XML</b></li>
+ * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>serialized as XML</b></li>
+ * </ul>
*/
COMPLETE,
+
/**
* Default, whereby missing properties/collections/actions are added to regions,
* and unused/empty regions are removed/trimmed.
- * <p/>
* <p>
- * It should be possible to remove any {@link MemberOrder} annotation but
- * any layout annotations would need to be retained.
- * </p>
+ * It should be possible to remove any {@link MemberOrder} and {@link MemberGroupLayout} annotation but
+ * any property/collection/action layout annotations would need to be retained.
+ * <ul>
+ * <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
+ * <li>{@code @MemberOrder}: <b>serialized as XML</b></li>
+ * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
+ * </ul>
*/
NORMALIZED,
+
/**
* As per {@link #NORMALIZED}, but with no properties/collections/actions.
- * <p/>
* <p>
* The intention here is for layout annotations that "bind" the properties/collections/actions
* to the regions to be retained.
- * </p>
+ * <ul>
+ * <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
+ * <li>{@code @MemberOrder}: <b>ignored</b></li>
+ * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
+ * </ul>
*/
MINIMAL
}
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc b/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
index aa9134c..aef81c1 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
@@ -48,7 +48,7 @@ If no layout has been specified (or if the specified layout cannot be found), th
Finally, if this can't be found, then the framework will search for a file named `Xxx.layout.fallback.xml`.
If present, this will be used instead.
-The "fallback" layout this therefore allows libraries that provide a domain entities/view models (for example, the (non-ASF) link:https://platform.incode.org[Incode Platform] modules) to define the UI of these objects using a layout file, while still allowing the consuming application to override that layout if it so requires.
+The "fallback" layout therefore allows libraries that provide domain objects (for example, the (non-ASF) link:https://platform.incode.org[Incode Platform] modules) to define the UI of these objects using a layout file, while still allowing the consuming application to override that layout if it so requires.
@@ -61,7 +61,7 @@ The layout file distinguishes between two types of element:
+
The rows and columns are closely modelled on link:http://getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:vw:ROOT:about.adoc[Wicket viewer]).
-* those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
+* those that define common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
More information about these classes can be found in xref:refguide:applib-cm:classes/layout.adoc[the reference guide]. More information on Bootstrap 3's grid system can be found link:http://getbootstrap.com/css/#grid[here].