projectdoc Toolbox

Renders a document graph in a graph language allowing the body to contain arbitrary content (including transclusions).

Categories
Extension
Since
1.0

The Body Graph Macro acts similar to the Graph Macro but allows rendered content in its body. This makes it possible to reuse graph specifications using the Transclusion Macro.

Properties

Document

Specify the document to fetch the list of documents to traverse.

If the value is empty, the document the macro is on is selected.

Property

The name of the property of the document to fetch the list of documents to traverse.

The expected value is either a list of Confluence links or a list of links created by a projectdoc macro (it needs a data attribute named "data-projectdoc-id" on the rendered HTML anchor element). These links need to point to projectdoc documents.

The property may also specify a section containing references to documents.

Implicit Association

Check if this document links to first children.

That is make this document as the root node of the document tree.

Add Labels

Check if the edges should be labelled with the association names.

Selected Columns

If the Property parameter points to a section containing a table, specify the names of the columns to use for implicit associations.

Render Startdot

Adds @startdot at the first line.

Deactivated by default.

This is required by plantUML.

Render Digraph

Wraps the content inside a digraph element with the graph name.

This is required if the generated diagram is complete.

Activated by default.

Render Wrapper

Wraps graph description inside a preformat element.

This is required by plantUML.

Deactivated by default.

Render Text Newline

When checked a simple newline is rendered. Otherwise a XML break (br) is rendered.

Activated by default.

Graph Type

 

No longer supported!

Users need to define the four parameters for rendering the graph description individually.

Use

  1. Render Startdot
  2. Render Digraph
  3. Render Wrapper
  4. Render Text Newline

Specify the type of graph to render. This controls the syntax of the graph notation.

Valid values are

  • dot-plantuml - renders some additional information for the PlantUML Render Macro.
  • dot-condensed - does not render the enclosing digraph element.

It defaults to dot-plantuml. The default can be set with the space property Graph Type.

Property Name for Node

Specify the name of the document property to label the graph nodes.

If not specified, the property name defaults to the Name Property (Name).

URL Property

Name of the document property that stores the URL. Defaults to the page URL.

If no URL should be rendered, then use #none as value.

Style Property / Entity

The name of the property with entity style information for style templates.

Defaults to projectdoc.extension.graph.style.entity.

Style Property / DOT

The name of the property with DOT style information.

Defaults to projectdoc.extension.graph.style.dot.

Type Property

The name of document property storing type information. The type information styles, specified by the property, are applied to the node projectdoc.extension.graph.style.dot automatically.

Defaults to "Type".

Graph Name

Specify the name of the graph.

Defaults to "projectdoc".

Maximum Level

Limit the depth of the nodes to this level.

 

The following example shows the rendering of a graph with its maximum node level set to 2.

Full Graph

 

Reduced Graph

 

Note that the longest path is longer than the maximum level iff there is also a shorter path to the node that is within this limit.

Body

With the body of the macro the rendering of the graph is controlled quite similar to the Graph Macro.

The body of the Body Graph Macro allows rendered content which allows the employment of the Transclusion Macro to reuse graph specifications. Additional content should be added to the body within a preformat (pre) or paragraph (p) element. Otherwise newlines are consumed, rendering the specification in one long line.

 

This syntax is currently experimental and is subject to change.

Comment lines start with a hashmark ('#').

 

Names of nodes and edges select on document properties. If the document properties change, the specification in this macro does not.

Therefore by changing a selecting property of a document, the graph specification needs to be adjusted to reference the new name.

Properties to traverse

Specify the names of the properties to traverse. Each property is required to start on a new line. If you want to add graph attributes, add them separated by a colon.

Syntax Examples
My Property Name
My Property Name : color=green

The property names may refer to sections in which case all links are followed. If only links from a selected table column should be traversed, separate the name of that column with a slash from the property name.

Syntax Examples
My Property Name /  Select Column 1, Select Column 2
My Property Name /  Select Column 1, Select Column 2 : color=green

Each property specifies a subgraph element. To control the name of the graph (which defaults to the property name) use the '>' after the property name.

Syntax Examples
My Property Name > My_Subgraph_Name
My Property Name > My_Subgraph_Name /  Select Column 1 : color=green

Clusters

Nodes are grouped to clusters using the "CLUSTER: " prefix.

The following defines a cluster named "cluster_My Cluster Name" and adds the there nodes "Node1", "Node2", and "Node3" to it.

Syntax Examples
CLUSTER: My Cluster Name : Node1, Node2, Node3 : color=blue; style=filled

Note that the prefix "cluster_" will be prepended automatically in front of the chosen cluster name.

Separate by Semicolons!

 

It is important to separate the styles with semicolons. Otherwise the render engine will probably crash.

Graph Styles

Provide style information to be applied to graphs by the prefix "GRAPH: ". This style information is required on its own line.

The following adds styles to the main graph.

Syntax Example
GRAPH: color=green

Each traversed property creates a new subgraph. Use the name of the property to apply styles specific to this subgraph.

Syntax Example
GRAPH: My Subgraph Name : color=green; fontcolor="#000080"

Separate by Semicolons!

 

It is important to separate the styles with semicolons. Otherwise the render engine will probably crash.

Graph Items

Provide additional items (nodes and edges) to graphs by the prefix "PUT: ".

The following adds a line to the main graph.

Syntax Example
PUT: A -> B

Each traversed property creates a new subgraph. Use the name of the property to add items specific to this subgraph.

Syntax Example
PUT: My Subgraph Name : A -> B

Arrow Styles

Provide style information to be applied to arrows of the graph by lines starting with "ARROW: ".

Syntax Example
ARROW: color=green

Node Styles

Provide style information to be applied to nodes of the graph by lines starting with "NODE: ".

Syntax Example
NODE: My Node Name: color=green label="My Node"

Edge Styles

Provide style information to be applied to edges of the graph by lines starting with "EDGE: ".

Syntax Example
EDGE: My Association Name: color=green label="My Association"

Styles may also be set to selected edges. The following example sets a style to the edge between the first and second node.

Syntax Example
EDGE: Node Name 1 > Node Name 2 : style=blue

The more specific edge directive applies by overriding styles already set. For instance, if there is an EDGE directive that sets the color style with an association name and one that specifies the edge between two nodes, the latter will take precedence.

Pruning

Pruning allows to manually select nodes to prune the traversal.

The following will prune remove all edges that have the given node as a starting node.

Syntax Example
PRUNE: My Node

The following only removes edges with the given label.

Syntax Example
PRUNE: My Node: Association 1, Association 2

To prevent rendering a given node (not only pruning all edges), use the "PREVENT: " directive.

Syntax Example
PREVENT: My Node

Apply Property Styles

Provide style information by properties to be applied to nodes. Specify the name of the property and the style template. The style template may contain placeholders (and typically does).

When a document is traversed, the specified property may point to a document. If it does, the property projectdoc.extension.graph.style.entity provides additional information applied to the template.

Syntax Example
APPLY: My Property Name: style=${style}, color=${color}

For this example the document referenced by the property My Property Name provides a property with name projectdoc.extension.graph.style.entity whose value is set to color=blue, style=dashed (note that the order of the mappings is not relevant).

Per default the first encountered style is applied. There are other strategies to resolve duplicate styles. For instance for certain shapes and styles the color styles may be merged. To select the merge strategy for color styles, use merge-colors as selector.

Syntax Example
APPLY: My Property Name / merge-colors : style=${style}, color=${color}

If the template should only be applied in case of the property matches a given value, use the assignment operator.

Syntax Example
APPLY: My Property Name=Property Value / merge-colors : style=${style}, color=${color}

Multiple values may be connected by OR ('|') or AND ('&'). The operators may not be combined.

Syntax Example
APPLY: My Property Name=Property Value 1|Property Value 2 / merge-colors : style=${style}, color=${color}
APPLY: My Property Name=PV1&PV2&PV3 : style=${style}, color=${color}

Styles may also be applied to Nodes. The following example applies styles to all nodes that have a property with a given value.

Syntax Example
APPLY2NODE: > My Property Name=Property Value : style=${style}, color=${color}

Further examples match on nodes with and without constraints:

Syntax Examples
APPLY2NODE: My Node Name : style=${style}, color=${color}
APPLY2NODE: My Node Name > My Property Name=Property Value : style=${style}, color=${color}

Difference between APPLY and APPLY2NODE

 

In a nutshell the difference between APPLY and APPLY2NODE ist this:

  1. APPLY specifies an association, that is a property on a document, while APPLY2NODE specifies the name of a node that is the name of a document.
  2. Both allow to put one further constraint on the selection. While APPLY allows to specify a value for the specified property, APPLY2NODE allows to demand a value for a property on the specified document.
  3. Styles are applied to the node for the document that provides the association in case of APPLY. Styles are applied to the node of the referenced document in case of APPLY2NODE.

Details

No Recursion Detection

Please note that this macro does not detect recursions in case the macro itself is part of the property value or section body it references.

If you need to specify the graph as part of the section where the table of documents to traverse is also part of, then use the Content Marker Macro and put the table with a unique ID in it. Use this ID as the value to the Property Parameter.

Space Properties

The following space properties are consulted by this macro.

IdentifierShort Description
projectdoc.extension.graph.graph-typeSpecifies the type used for rendering graphs.

Usage Examples

Render Children

Suppose there is a document that describes the business process "Buy Product" by listing each activity associated with this process.

The activities may be selected by a query (for instances using the Display Table Macro) or by list of selected references (for instance using the Tour Macro). Either way, the list of activities associated with the process is rendered something like this:

To render the association of the process (the document that lists these activities) to its activities, use this macro like this:

This will render the graph in DOT syntax:

@startdot
digraph projectdoc {
  subgraph Activity {
    "Buy Product" -> "Determine Requirements" [label="Activity"]
    "Buy Product" -> "Create Candidate List" [label="Activity"]
    "Buy Product" -> "Evaluate Candidates" [label="Activity"]
    "Buy Product" -> "Make Buy Decision" [label="Activity"]
  }
}
@enddot

Using the PlantUML Render Macro will render the graph as an image.

Traverse Properties

The macro traverses the document tree by the properties specified in the body of the macro. Each property value is supposed to contain a list of references to projectdoc documents.

Let's extend the previous example so that each activity is associated with one or more role documents. The property that stores this information is named "Role". Then make the Role property be a significant link for the graph:

For each traversed document (beyond the implicit root that is the process document), the Role property will add additional nodes to the graph. Since we add a style information (blue edges), the graph is rendered like this:

Related macros

Transclusion to Text Macro
Transcludes content from a document marked with the content marker macro and renders it as plain text.
Graph Macro
Renders a document graph in a graph language.