Option to hide unused default tags in the legend

[0n3d3r3r]

When you create custom element tags they start appearing in the legend provided you use SHOW_LEGEND() in the last line of the diagram, which is very useful.

However, sometimes we may be only using these custom element tags (e.g.: "fallback") and none of the default ones (e.g.: "system", "container", "external_container", etc.), but they would keep showing up in the legend even if not used at all.

One way to correct that would be if the SHOW_LEGEND procedure had an additional parameter to instruct it to hide all default tags that are not being used. Something like this, perhaps:

SHOW_LEGEND($hideStereotype="true", $hideUnusedDefaultTag="true")

If it's to complex to determine which default elements are not being used, the other way to implement this would be to have a procedure like the following to cancel individual default elements in the legend ahead of the SHOW_LEGEND call:

HideInLegend($DefaultTagToHide)

That would be a little more manual and prone to involuntary errors, but better than having to code the legend table yourself every time you create a diagram with custom elements.

A third alternative is to create a procedure similar to UpdateElementStyle that changes the name of the default element instead of its style, so you can treat a default stereotype like it's a new custom element:

UpdateElementName($elementName, $newElementName)

This is probably the hardest to implement, but would also render a consistent legend table. Usage example:

UpdateElementName(container, $newElementName="main_container")

There may be other ways to achieve this, but I think it's worth to give it a try and make it at least manageable, since those default elements displayed there in the legend create noise or confusion for the audience if they're not actually used across the diagram.

Thanks.

P.S.: Sorry if I'm using incorrect syntax to get the point across; just started learning the inner workings of this by looking at the Include files.

[kirchsth]

However, sometimes we may be only using these custom element tags (e.g.: "fallback") and none of the default ones (e.g.: "system", "container", "external_container", etc.), but they would keep showing up in the legend even if not used at all.

Can you add a sample? You should only see legend of used elements (If you use only tagged elements then the legend displays the untagged element too). E.g. if you use no person you should see no person.

HideInLegend($DefaultTagToHide)

depending on the diagram type different DefaultLegendEntries() are defined, If you reset it with DefaultLegendEntries("") they are not displayed anymore. But like in following sample I think it's more confusing if the base classes are not displayed anymore

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

' orig in C4_Container.puml
' SetDefaultLegendEntries("person\nsystem\ncontainer\nexternal_person\nexternal_system\nexternal_container")
SetDefaultLegendEntries("")

AddElementTag(tagged, $fontColor=red)

Container(c1, Container 1, tech)
Container(c2, Container 2, tech, $tags="tagged")
Person(p1, p2)
Person(p2, p2, $tags="tagged")

SHOW_LEGEND()
@enduml

UpdateElementName(container, $newElementName="main_container")

If you know that you have only "tagged container" and "tagged persons" you could define combined tags

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

' orig in C4_Container.puml
' SetDefaultLegendEntries("person\nsystem\ncontainer\nexternal_person\nexternal_system\nexternal_container")
SetDefaultLegendEntries("")

AddElementTag("tagged container", $fontColor=red, $bgColor=$CONTAINER_BG_COLOR)
AddElementTag("tagged person", $fontColor=red, $bgColor=$PERSON_BG_COLOR)

Container(c2, Container 2, tech, $tags="tagged container")
Person(p2, p2, $tags="tagged person")

SHOW_LEGEND()
@enduml

[kirchsth]

@0n3d3r3r I think I found an automatic hide implementation, can you please check #158
and please don't forget to add the non working sample

However, sometimes we may be only using these custom element tags (e.g.: "fallback") and none of the default ones (e.g.: "system", "container", "external_container", etc.), but they would keep showing up in the legend even if not used at all.

Thank you and best regards
Helmut

[0n3d3r3r]

Hi @kirchsth!

An example of what I was saying, where I'm not using the default stereotype "container" anywhere in the code but it still appears in the legend:

@startuml
!include <C4/C4_Deployment>
skinparam Ranksep 200
AddElementTag("main container", $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$CONTAINER_BORDER_COLOR, $bgColor=$CONTAINER_BG_COLOR)
AddElementTag("fallback container", $fontColor=White, $borderColor=DarkGray, $bgColor=Silver)
AddRelTag("fallback connectivity", $textColor=LightGray, $lineColor=LightGray)
Deployment_Node(site_a, "Site A", "Deployment Node: Location") {
   Deployment_Node(server_1a, "Server 1A", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_a, "Run-time Environment A", "Deployment Node: JVM 14") {
         Container(app_a, "Application (Main)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="main container")
      }
   }
   Deployment_Node(server_2a, "Server 2A", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_a, "Database (Main)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="main container")
   }
}
Deployment_Node(site_b, "Site B", "Deployment Node: Location") {
   Deployment_Node(server_1b, "Server 1B", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_b, "Run-time Environment B", "Deployment Node: JVM 14") {
         Container(app_b, "Application (Fallback)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="fallback container")
      }
   }   
   Deployment_Node(server_2b, "Server 2B", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_b, "Database (Fallback)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="fallback container")
   }
}
Rel_D(app_a, db_a, "Reads/Writes data", "JDBC")
Rel_D(app_b, db_a, "Reads/Writes data", "JDBC")
Rel_(db_a, db_b, "Replicates asynchronously", "TCP 5432", ".R.>")
Rel_D(app_a, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
Rel_D(app_b, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
SHOW_LEGEND()
@enduml

What you mention on your first answer though looks like a good workaround for me in the meantime, because if I add the "SetDefaultLegendEntries" line, it will manually remove the obsolete default elements from the legend, provided I know which ones I'm actually using or not before hand (I'm using the "node" one, but not the "container" one):

@startuml
!include <C4/C4_Deployment>
skinparam Ranksep 200
AddElementTag("main container", $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$CONTAINER_BORDER_COLOR, $bgColor=$CONTAINER_BG_COLOR)
AddElementTag("fallback container", $fontColor=White, $borderColor=DarkGray, $bgColor=Silver)
AddRelTag("fallback connectivity", $textColor=LightGray, $lineColor=LightGray)
'
' Added line here...
SetDefaultLegendEntries("node")
'
Deployment_Node(site_a, "Site A", "Deployment Node: Location") {
   Deployment_Node(server_1a, "Server 1A", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_a, "Run-time Environment A", "Deployment Node: JVM 14") {
         Container(app_a, "Application (Main)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="main container")
      }
   }
   Deployment_Node(server_2a, "Server 2A", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_a, "Database (Main)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="main container")
   }
}
Deployment_Node(site_b, "Site B", "Deployment Node: Location") {
   Deployment_Node(server_1b, "Server 1B", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_b, "Run-time Environment B", "Deployment Node: JVM 14") {
         Container(app_b, "Application (Fallback)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="fallback container")
      }
   }   
   Deployment_Node(server_2b, "Server 2B", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_b, "Database (Fallback)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="fallback container")
   }
}
Rel_D(app_a, db_a, "Reads/Writes data", "JDBC")
Rel_D(app_b, db_a, "Reads/Writes data", "JDBC")
Rel_(db_a, db_b, "Replicates asynchronously", "TCP 5432", ".R.>")
Rel_D(app_a, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
Rel_D(app_b, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
SHOW_LEGEND()
@enduml

If that pull request you opened (#158) can take care of automatically hiding obsolete default elements in the legend, then that would be the fix for this.

Thanks!

[kirchsth]

@0n3d3r3r: thank you. Each Container..() call uses internal the "container" stereotype and therefore it's correct that it is displayed based on the the current implementation (I thought your diagrams have an additional e.g. "person" legend entry). With then MR #158 the obsolete container entry is it removed too (you could use my branch in the meantime).

BR Helmut

@startuml
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Deployment.puml

skinparam Ranksep 200
AddElementTag("main container", $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$CONTAINER_BORDER_COLOR, $bgColor=$CONTAINER_BG_COLOR)
AddElementTag("fallback container", $fontColor=White, $borderColor=DarkGray, $bgColor=Silver)
AddRelTag("fallback connectivity", $textColor=LightGray, $lineColor=LightGray)
'
' Added line here...
' SetDefaultLegendEntries("node")
'
Deployment_Node(site_a, "Site A", "Deployment Node: Location") {
   Deployment_Node(server_1a, "Server 1A", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_a, "Run-time Environment A", "Deployment Node: JVM 14") {
         Container(app_a, "Application (Main)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="main container")
      }
   }
   Deployment_Node(server_2a, "Server 2A", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_a, "Database (Main)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="main container")
   }
}
Deployment_Node(site_b, "Site B", "Deployment Node: Location") {
   Deployment_Node(server_1b, "Server 1B", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_b, "Run-time Environment B", "Deployment Node: JVM 14") {
         Container(app_b, "Application (Fallback)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="fallback container")
      }
   }   
   Deployment_Node(server_2b, "Server 2B", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_b, "Database (Fallback)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="fallback container")
   }
}
Rel_D(app_a, db_a, "Reads/Writes data", "JDBC")
Rel_D(app_b, db_a, "Reads/Writes data", "JDBC")
Rel_(db_a, db_b, "Replicates asynchronously", "TCP 5432", ".R.>")
Rel_D(app_a, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
Rel_D(app_b, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
SHOW_LEGEND()
@enduml

[kirchsth]

@0n3d3r3r: with #160 the realtion styles supports dashed lines too

@startuml
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Deployment.puml

skinparam Ranksep 200
AddElementTag("main container", $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$CONTAINER_BORDER_COLOR, $bgColor=$CONTAINER_BG_COLOR)
AddElementTag("fallback container", $fontColor=White, $borderColor=DarkGray, $bgColor=Silver)
AddRelTag("fallback connectivity", $textColor=LightGray, $lineColor=LightGray)

AddRelTag("async", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR, $lineStyle = DashedLine())

'
' Added line here...
' SetDefaultLegendEntries("node")
'
Deployment_Node(site_a, "Site A", "Deployment Node: Location") {
   Deployment_Node(server_1a, "Server 1A", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_a, "Run-time Environment A", "Deployment Node: JVM 14") {
         Container(app_a, "Application (Main)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="main container")
      }
   }
   Deployment_Node(server_2a, "Server 2A", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_a, "Database (Main)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="main container")
   }
}
Deployment_Node(site_b, "Site B", "Deployment Node: Location") {
   Deployment_Node(server_1b, "Server 1B", "Deployment Node: CentOS 8.0") {
      Deployment_Node(re_b, "Run-time Environment B", "Deployment Node: JVM 14") {
         Container(app_b, "Application (Fallback)", "Container: Java/Spring Cloud", "Responsible for order processing", $tags="fallback container")
      }
   }   
   Deployment_Node(server_2b, "Server 2B", "Deployment Node: CentOS 8.0") {
      ContainerDb(db_b, "Database (Fallback)", "Container: PostgreSQL Database", "Responsible for hosting the application repository", $tags="fallback container")
   }
}
Rel_D(app_a, db_a, "Reads/Writes data", "JDBC")
Rel_D(app_b, db_a, "Reads/Writes data", "JDBC")
Rel_R(db_a, db_b, "Replicates asynchronously", "TCP 5432", $tags = "async")
Rel_D(app_a, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
Rel_D(app_b, db_b, "Reads/Writes data", "JDBC", $tags="fallback connectivity")
SHOW_LEGEND()
@enduml

[0n3d3r3r]

Great! I can use that in the meantime. Also, thanks for noticing my replication line style workaround and referencing the corresponding pull request. I'm sure it's going to be useful to depict async or non-transactional flows at the very least.

I hope both features are able to make the cut for the PlantUML 2021.8 stdlib release ;)

Best regards.

[kirchsth]

@Potherca : I think it's time for a new release (as soon we have it we could merge it into PlantUML stdlib too)

[Potherca]

Fixed in #158