Where am I? (Navigable trees)

The Wicket viewer provides a secondary navigation scheme that allows users to quickly access domain objects, that are organized in a hierarchical manner.

This hierarchy can be understood as a navigable tree-structure, where the navigable tree-nodes are either domain objects or domain views. Domain objects that take part in such a navigable-tree-structure need to declare their actual navigable parent within this hierarchy using the @PropertyLayout#navigable() annotation.

Screenshots

The following screenshot (from the reference app) shows the navigation links below the top menu bar.

hello grey bg

Domain Code

To declare a domain object’s (or view’s) navigable parent, add a @PropertyLayout(navigable=Navigable.PARENT) annotation to a field (that has an associated getter) or a no-arg method, that returns the parent object:

Company.java
@DomainObject
public class Company { /* ... */ }
Employee.java
@DomainObject
public class Employee {

    @PropertyLayout(navigable=Navigable.PARENT) // annotated field with e.g. lombok provided getter
    @Getter
    Company myCompany;
}
PhoneNumber.java
@DomainObject
public class PhoneNumber {

    @PropertyLayout(navigable=Navigable.PARENT)  // annotated no-arg supplier
    Employee employee(){
        return ...
    }
}

This results in a navigable tree-structure …​

Company > Employee > PhoneNumber

Notes:

  1. Any use of @PropertyLayout(navigable=Navigable.PARENT) with Java interfaces is simply ignored. These do not contribute to the domain meta model.

  2. Any class (abstract or concrete) may at most have one @PropertyLayout annotation, having navigable=Navigable.PARENT 'flag' set (on either a method or a field); otherwise meta-model validation will fail.

  3. The annotated member (method or field), when …​

    1. ... a method: then must be a no-arg method returning a non-primitive type (e.g. a getter)

    2. ... a field: then the field must be of non-primitive type and must also have a getter (as specified by the Java Beans Standard, particularly to allow @PropertyLayout(navigable=Navigable.PARENT) annotations on fields that use the lombok @Getter annotation)

  4. Starting from the current domain-object, we search the object’s class inheritance hierarchy (super class, super super class, …​), until we find the first class that has a @PropertyLayout(navigable=Navigable.PARENT) annotation. That’s the one we use to resolve the current domain-object’s navigable parent.

User Experience

When viewing a domain object that is part of a hierarchical structure, one can easily navigate to any parent of this object. Horizontally arranged text links separated by the 'greater than' symbol (>) are provided below the main menu. (Traditionally called breadcrumbs.)

The navigable tree-structure, as provided by the "where am i" feature, is declared at compile-time (predefined by the programmer), whereas Bookmarked Pages) are populated at runtime only after user interaction.