Extension d3

antora/playbooks/site-deploy.yml

@@ -162,6 +162,9 @@ content:
     - url: .
       start_path: extensions/vw/pdfjs/adoc # vw
       branches: [2.0.0, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 4.0.0-SNAPSHOT]
+    - url: .
+      start_path: extensions/vw/d3/adoc # vw
+      branches: [2.0.0, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 4.0.0-SNAPSHOT]
     - url: .
       start_path: extensions/vw/sse/adoc # vw
       branches: [2.0.0, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 4.0.0-SNAPSHOT]

antora/playbooks/site-verify.yml

@@ -162,6 +162,9 @@ content:
     - url: .
       start_path: extensions/vw/pdfjs/adoc # vw
       branches: HEAD
+    - url: .
+      start_path: extensions/vw/d3/adoc # vw
+      branches: HEAD
     - url: .
       start_path: extensions/vw/sse/adoc # vw
       branches: HEAD

antora/playbooks/site.NEXT.yml

@@ -159,6 +159,9 @@ content:
     - url: .
       start_path: extensions/vw/pdfjs/adoc # vw
       branches: [2.0.0, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 3.5.0]
+    - url: .
+      start_path: extensions/vw/d3/adoc # vw
+      branches: [2.0.0, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 3.5.0]
     - url: .
       start_path: extensions/vw/sse/adoc # vw
       branches: [2.0.0, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 3.5.0]

antora/playbooks/site.yml

@@ -159,6 +159,9 @@ content:
     - url: .
       start_path: extensions/vw/pdfjs/adoc # vw
       branches: HEAD
+    - url: .
+      start_path: extensions/vw/d3/adoc # vw
+      branches: HEAD
     - url: .
       start_path: extensions/vw/sse/adoc # vw
       branches: HEAD

bom/pom.xml

@@ -1024,6 +1024,48 @@ identified
                 <artifactId>causeway-extensions-pdfjs-wicket-ui</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>org.apache.causeway.extensions</groupId>
+                <artifactId>causeway-extensions-d3</artifactId>
+                <version>${project.version}</version>
+                <type>pom</type>
+                <scope>compile</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.apache.causeway.extensions</groupId>
+                <artifactId>causeway-extensions-d3-applib</artifactId>
+                <version>${project.version}</version>
+                <type>jar</type>
+                <scope>compile</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.apache.causeway.extensions</groupId>
+                <artifactId>causeway-extensions-d3-metamodel</artifactId>
+                <version>${project.version}</version>
+                <type>jar</type>
+                <scope>compile</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.apache.causeway.extensions</groupId>
+                <artifactId>causeway-extensions-d3-wicket</artifactId>
+                <version>${project.version}</version>
+                <type>pom</type>
+                <scope>compile</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.apache.causeway.extensions</groupId>
+                <artifactId>causeway-extensions-d3-wicket-integration</artifactId>
+                <version>${project.version}</version>
+                <type>jar</type>
+                <scope>compile</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.apache.causeway.extensions</groupId>
+                <artifactId>causeway-extensions-d3-wicket-ui</artifactId>
+                <version>${project.version}</version>
+                <type>jar</type>
+                <scope>compile</scope>
+            </dependency>
             <dependency>
                 <groupId>org.apache.causeway.extensions</groupId>
                 <artifactId>causeway-extensions-sse</artifactId>

extensions/pom.xml

@@ -95,6 +95,7 @@
 		<module>vw/sse</module>
 		<module>vw/fullcalendar</module>
 		<module>vw/pdfjs</module>
+		<module>vw/d3</module>
 		<module>vw/tabular</module>
 
 	</modules>

extensions/vw/d3/adoc/antora.yml

@@ -0,0 +1,19 @@
+#  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 agreed to in writing,
+#  software distributed under the License is distributed on an
+#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#  KIND, either express or implied.  See the License for the
+#  specific language governing permissions and limitations
+#  under the License.
+
+name: vw
+version: latest

extensions/vw/d3/adoc/modules/d3/nav.adoc

@@ -0,0 +1,4 @@
+
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+include::vw:ROOT:partial$component-nav.adoc[]

extensions/vw/d3/adoc/modules/d3/pages/about.adoc

@@ -0,0 +1,138 @@
+= D3.js
+
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+The D3.js module integrates with the xref:vw:ROOT:about.adoc[Wicket Viewer], rendering a domain property containing a JSON graph structure (nodes and links) as an interactive D3.js force-layout graph using the link:https://d3js.org/[D3.js] library.
+
+Clicking a graph node invokes a configurable domain action whose single `String` parameter receives the clicked node's id.
+
+
+== Setup
+
+=== Dependency Management
+
+In your application's top level `pom.xml`, add a dependency for this module's own bill of materials (BOM):
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.causeway.extensions</groupId>
+            <artifactId>causeway-extensions-d3</artifactId>
+            <scope>import</scope>
+            <type>pom</type>
+            <version>{page-causewayreleaseversion}</version>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+----
+
+=== Dependencies / Imports
+
+In those modules where there are domain objects with properties containing graph data (a JSON string with `nodes` and `links`), add a dependency/import to the applib module:
+
+* add this dependency:
++
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencies>
+    <dependency>
+        <groupId>org.apache.causeway.extensions</groupId>
+        <artifactId>causeway-extensions-d3-applib</artifactId>
+    </dependency>
+</dependencies>
+----
+
+* and `@Import` this module:
++
+[source,java]
+.MyModule.java
+----
+@Configuration
+@Import({
+    CausewayModuleExtD3Applib.class,
+    // ...
+})
+public class MyModule { ... }
+----
+
+In addition, in the webapp module of your application, add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependency>
+    <groupId>org.apache.causeway.extensions</groupId>
+    <artifactId>causeway-extensions-d3-wicket-ui</artifactId>
+</dependency>
+----
+
+And in your application's xref:userguide::modules.adoc#appmanifest[App Manifest], import the extension's implementation module:
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+        CausewayModuleExtD3WicketUi.class,
+        ...
+})
+public class AppManifest {
+}
+----
+
+
+== Usage
+
+To use the extension, annotate a `String` property (returning a JSON graph structure) with the xref:refguide:extensions:index/d3/applib/annotations/D3Graph.adoc[@D3Graph] annotation.
+
+For example:
+
+[source,java]
+----
+@D3Graph(clickAction = "selectNode")    // <.>
+@Property()
+@PropertyLayout(fieldSetId = "content", sequence = "1")
+public String getGraph() {
+    return "{\"nodes\":[{\"id\":\"A\",\"name\":\"Node A\"}],\"links\":[]}";
+}
+
+@Action
+public GraphOwner selectNode(final String nodeId) {
+    // handle node click
+    return this;
+}
+----
+<.> indicates that the property returns a JSON graph structure, and so should be rendered as an interactive D3.js force-layout graph.
+
+The `clickAction` attribute specifies the id of a domain action (on the same object) that will be invoked when a graph node is clicked. The action must accept a single `String` parameter which receives the clicked node's id.
+
+Optionally, you can also provide an implementation of the xref:refguide:extensions:index/d3/applib/spi/D3GraphAdvisor.adoc[] SPI, which advises on the graph data (`graphData`), the dimensions (`initialWidth`/`initialHeight`), the interaction flags (`enableDragging`/`enableZoom`), and the click action id (`clickAction`). The framework provides sensible defaults (800x600, dragging and zoom enabled, no click action).
+
+Advisor-provided graph data is merged into the effective configuration, but for a *property*-level `@D3Graph` the annotated property's value takes precedence; the advisor's `graphData` is used as a fallback (and is the only source of data for a TYPE-level `@D3Graph`, see below).
+
+
+=== TYPE-level `@D3Graph`
+
+`@D3Graph` can also be placed on a domain object (class), in which case the object's default representation is rendered as an interactive D3 graph:
+
+[source,java]
+----
+@D3Graph(clickAction = "selectNode")    // <.>
+public class GraphOwner {
+
+    @Action
+    public GraphOwner selectNode(final String nodeId) {
+        // handle node click
+        return this;
+    }
+}
+----
+<.> indicates that the object page should be rendered as an interactive D3.js force-layout graph.
+
+As there is no annotated property to read the graph data from, the graph data must be supplied by a xref:refguide:extensions:index/d3/applib/spi/D3GraphAdvisor.adoc[D3GraphAdvisor] (via the `graphData` attribute of its `Advice`); if no advisor supplies data, an empty graph is rendered.
+
+NOTE: A TYPE-level `@D3Graph` *replaces* the standard object page rendering (its properties, collections and actions), so it is best suited to domain objects whose primary purpose is the graph itself.

extensions/vw/d3/adoc/modules/d3/partials/module-nav.adoc

@@ -0,0 +1,3 @@
+
+
+** xref:vw:d3:about.adoc[D3.js]

extensions/vw/d3/applib/pom.xml

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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 agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.apache.causeway.extensions</groupId>
+        <artifactId>causeway-extensions-d3</artifactId>
+        <version>4.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>causeway-extensions-d3-applib</artifactId>
+    <name>Apache Causeway Ext - D3 - Applib</name>
+
+    <properties>
+        <jar-plugin.automaticModuleName>org.apache.causeway.extensions.d3.applib</jar-plugin.automaticModuleName>
+        <git-plugin.propertiesDir>org/apache/causeway/extensions/d3/applib</git-plugin.propertiesDir>
+    </properties>
+
+    <dependencies>
+
+        <dependency>
+            <groupId>org.apache.causeway.commons</groupId>
+            <artifactId>causeway-commons</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.causeway.core</groupId>
+            <artifactId>causeway-applib</artifactId>
+        </dependency>
+
+    </dependencies>
+</project>

extensions/vw/d3/applib/src/main/java/org/apache/causeway/extensions/d3/applib/CausewayModuleExtD3Applib.java

@@ -0,0 +1,29 @@
+/*
+ *  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 agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.apache.causeway.extensions.d3.applib;
+
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * @since 2.0 {@index}
+ */
+@Configuration
+public class CausewayModuleExtD3Applib {
+
+}