Skip to content

Styling

Jump to bottom Edit New page
Stefan Ferstl edited this page Dec 28, 2023 · 23 revisions
Dependency graph with custom styles

Starting with version 2.0.0, the depgraph-maven-plugin offers a variety of styling options. Custom styles are defined in a JSON configuration file, which can be used in each goal of the depgraph-maven-plugin.

Integrating a Custom Style Configuration

A custom style configuration can be integrated by pointing the customStyleConfiguration property to the location of the custom style configuration file.

mvn depgraph:graph -DcustomStyleConfiguration=/path/to/my/custom/configuration.json

The custom configuration file can either be located somewhere on the file system or on the classpath. To put a style configuration file onto the classpath, you need to add a plugin dependency containing the configuration file:

<plugin>
  <groupId>com.github.ferstl</groupId>
  <artifactId>depgraph-maven-plugin</artifactId>
  <dependencies>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>style-artifact</artifactId>
      <version>1.0</version>
    </dependency>
  <dependencies>
</plugin>

Additionally, you need to prefix the style configuration location with classpath:

mvn depgraph:graph -DcustomStyleConfiguration=classpath:my-style-configuration.json

As with any other properties, you can also define the style configuration files directly in the plugin's <configuration> section in the POM file.

A custom style configuration will be merged with the built-in defaults. To print the the actually used configuration, you can run each goal with printStyleConfiguration set to true:

mvn depgraph:graph -DprintStyleConfiguration=true

The Style Configuration File

The style configuration file defines 5 styling elements:

  • General style for the graph
  • Default style for nodes
  • Default style for edges
  • Styles for different combinations of node properties
  • Styles for different edge resolutions
  • Styles for edges depending on the scope of the target dependency

Each of these elements is optional. If they are not defined a default will be used. The built-in defaults are defined here.

Building Blocks

The building blocks of the style configuration are attributes describing fonts, nodes and edges in the dependency graph.

Fonts

Attribute Since Value
name 2.0.0 Name of the font: See http://www.graphviz.org/doc/info/attrs.html#d:fontname
size 2.0.0 Font size in points: http://www.graphviz.org/doc/info/attrs.html#a:fontsize
color 2.0.0 Font color: See http://www.graphviz.org/doc/info/attrs.html#d:color

Graph

Attribute Since Value
rankdir 2.2.0 Direction of the graph: See http://www.graphviz.org/doc/info/attrs.html#k:rankdir

Nodes

Attribute Since Value
type (mandatory!) 2.0.0 Either box , ellipse or polygon. Note that this attribute needs to be defined.
sides 2.0.0 Only relevant for type polygon. Defines the number of the polygon's sides.
color 2.0.0 Outline color: See http://www.graphviz.org/doc/info/attrs.html#d:color (note: to set text color, do so inside default-font)
fill-color 2.0.0 Fill color: See http://www.graphviz.org/doc/info/attrs.html#d:fillcolor
style 2.0.0 Style of the node: See http://www.graphviz.org/doc/info/attrs.html#d:style
default-font 2.0.0 Default font used for text in the node.
group-id-font 2.0.0 Font to be used for the dependency's group ID.
artifact-id-font 2.0.0 Font to be used for the dependency's artifact ID.
version-font 2.0.0 Font to be used for the dependency's version.
scope-font 2.0.0 Font to be used for the dependency's scope.
optional-font 3.2.0 Font to be used for the dependency's optional indicator.

Edges

Attribute Since Value
style 2.0.0 Style of the edge: See http://www.graphviz.org/doc/info/attrs.html#d:style .
color 2.0.0 Color of the edge: See See http://www.graphviz.org/doc/info/attrs.html#d:color .
font 2.0.0 Font to be used for labels on the edge.

The Styling Elements

graph: The general style for the graph

The graph element defines general styling options for the whole graph. Currently it does only support the rankdir option.

default-node: Default style for nodes

The default-node element defines how a node in the dependency graph should generally look like.

"default-node" : { /* Attributes as described in the "Nodes" chapter */ }

default-edge: Default Style for Edges

The default-edge element defines how an edge in the dependency graph should generally look like.

"default-node" : { /* Attributes as described in the "Edges" chapter */ }

node-styles: Styles for Different Combinations of Node Properties

The node-styles element allows styling a node based on these attributes:

  • groupId
  • artifactId
  • scope
  • type
  • version
  • classifier (since version 3.1)
  • true|false for optional dependencies (since version 3.2)

The element contains a list of "style key"/"node style" pairs:

"node-styles" : {
  <style-key-1> : { /* Attributes as described in the "Nodes" chapter */ },
  <style-key-2> : { /* Attributes as described in the "Nodes" chapter */ },
  ...
}

The style key is a comma-separated string in the form of <groupId>,<artifactId>,<scope>,<type>,<version>,<classifier>, where commas at the end can be omitted. For example, the style key com.github.ferstl,,test will match all test scope dependencies with groupId com.github.ferstl.

To find a matching style for a dependency, the list of node styles will be traversed from top to bottom and the first matching style will be used. So it is recommended to start the configuration with the most specific styles.

For groupId, artifactId version and classifier there is wildcard support, e.g. com.github.ferstl* will match all dependencies with a groupId starting with com.github.ferstl. ,,,,*-SNAPSHOT will match all SNAPSHOT dependencies.

edge-resolution-styles: Styles for Different Edge Resolutions

The edge-resolution-styles element allows styling a dependency edge based on the edge's resolution. An edge can have one of these four resolutions:

  • included: A regular dependency edge. The target dependency will be included.

  • parent: A dependency edge leading from a parent POM to a module (Since 3.2.0).

  • omitted-for-duplicate: The target dependency is omitted since it is included by another dependency edge

  • omitted-for-conflict: The target dependency is omitted since its version is conflicting with another version of the same dependency.

    "edge-resolution-styles" : { : { /* Attributes as described in the "Edges" chapter */ }, ... }

edge-scope-styles: Edge styles depending target dependency's scope

The edge-resolution-styles element allows styling a dependency edge based on its target dependency's scope. This element has only an effect for included edges (see above).

"edge-scope-styles" : {
  <scope> : { /* Attributes as described in the "Edges" chapter */ },
  ...
}

In an aggregated graph, a dependency may occur in different scopes (in case the mergeScopes option is set to true). In this case, the most significant scope wins. This is the order of scopes from most to least significant: compile > provided > runtime > test > system . The import scope is not in the list because it is only used in dependencyManagement and will never occur on a dependency.

Add a custom footer
Clone this wiki locally