Setup and Configuration

This section describes how to include the Wicket viewer’s module and set its configuration properties.

Maven pom.xml

Dependency Management

If your application inherits from the Apache Causeway starter app (org.apache.causeway.app:causeway-app-starter-parent) then that will define the version automatically:

pom.xml
<parent>
    <groupId>org.apache.causeway.app</groupId>
    <artifactId>causeway-app-starter-parent</artifactId>
    <version>2.1.0</version>
    <relativePath/>
</parent>

Alternatively, import the core BOM. This is usually done in the top-level parent pom of your application:

pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.causeway.core</groupId>
            <artifactId>causeway-core</artifactId>
            <version>2.1.0</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Dependency

In the webapp module of your application, add the following dependency:

pom.xml
<dependencies>
    <dependency>
        <groupId>org.apache.causeway.mavendeps</groupId>
        <artifactId>causeway-mavendeps-webapp</artifactId>
        <type>pom</type>
    </dependency>
</dependencies>

Note that this transitively includes the Wicket viewer module (org.apache.causeway.viewer:causeway-viewer-wicket-viewer in your app).

Update AppManifest

In your application’s AppManifest (top-level Spring @Configuration used to bootstrap the app), import the module for the Wicket viewer:

AppManifest.java
@Configuration
@Import({
        ...
        CausewayModuleViewerWicketViewer.class,
        ...
})
public class AppManifest {
}

Note that this transitively references the CausewayModuleViewerCommonXxx modules.

Configuration Properties

The Configuration Guide includes a section for the Wicket viewer.

The Wicket Viewer also honours the config properties common to all viewers, in common section.

Application Identity

Configuration properties that identify the application, in the sign-in page, welcome and about pages:

Customization:

Application versioning

If the causeway.viewer.common.application.version configuration property is present, then this will be shown in the footer on every page as well as on the about page.

Maintaining this configuration property manually could be error prone, so an alternative approach is to configure your build system to generate a version identifier automatically.

For example, the version 20181115.2011.EST-1862.8d8e1c16 consists of four parts:

  • the date of the build

  • the time of the build (to the nearest minute)

  • the branch

  • the git shaId

This can be computed using a simple script, for example:

DATE=$(date +%Y%m%d.%H%M)
BRANCH=$(echo $GIT_BRANCH | sed 's|^rel/||g' | sed 's|[.]|_|g' | awk -F/ '{ print $NF }')
GIT_SHORT_COMMIT=$(echo $GIT_COMMIT | cut -c1-8)
APPLICATION_VERSION=$DATE.$BRANCH.$GIT_SHORT_COMMIT

where $GIT_BRANCH and $GIT_COMMIT are provided by the CI server/build environment.

This environment variable can be passed into the (Maven) build using a system property, for example:

mvn -DapplicationVersion=$APPLICATION_VERSION clean install

Suppose we now provide a file application-version.properties is in the same package as the app manifest file, but in the src/main/resources directory:

application-version.properties
causeway.viewer.common.application.version=$\{applicationVersion}

then Maven will automatically interpolate the actual revision when this file is copied over to the build (ie target/classes) directory.

The last step is for Spring Boot to also load this file. One way to do this is using the Spring @PropertySource annotation on the top-level "app manifest":

@Configuration
@Import({
        // ...
        CausewayModuleViewerWicketViewer.class,

        // ...
})
@PropertySource("classpath:application-version.properties")     (1)
public class AppManifest {
}
1 picks up the additional configuration property.

Sign-in, Sign-up and Remember Me

Configuration properties that influence the behaviour and appearance of the sign-in page.

Configuration properties that influence the appearance of the header and footer panels:

  • causeway.viewer.common.credit

    For example:

    application.yml
    causeway:
  viewer:
    common:
      credit:
        - url:  https://causeway.apache.org
          image: images/apache-causeway/causeway-logo-65x48.png
          name: Apache Causeway

Up to three credits can be provided.

See also the bookmarks and breadcrumbs and themes configuration properties, because these also control UI elements that appear on the header/footer panels.

Presentation

These configuration properties that effect the overall presentation and appearance of the viewer:

And these configuration properties provide defaults for annotations that also will effect the overall presentation and appearance of the viewer:

Bookmarks and Breadcrumbs

These configuration properties enable or disable the mechanisms for locating previously accessed objects.

Themes

These configuration properties control the switching of themes.

The Wicket viewer uses Bootstrap styles and components (courtesy of the Wicket Bootstrap integration). You can also develop and install a custom themes (eg to fit your company’s look-n-feel/interface guidelines); see the extending chapter for further details.

Date Formatting & Date Picker

These configuration properties influence the way in which date/times are rendered and can be selected using the date/time pickers:

Debugging

These configuration properties can assist with debugging the behaviour of the Wicket viewer itself:

Feature Toggles

These configuration properties are used to enable/disable features that are either on the way to becoming the default behaviour (but can temporarily be disabled) or conversely for features that are to be removed (but can temporarily be left as enabled).