Merge pull request #352 from kirchsth/feature/350_boundaries_descr_sp…

…rite #350 All boundaries supports descriptions and sprites too
plantuml-stdlib · May 4, 2024 · dcadafc · dcadafc
2 parents 3207be9 + 096629c
commit dcadafc
Show file tree

Hide file tree

Showing 7 changed files with 88 additions and 61 deletions.
diff --git a/C4.puml b/C4.puml
@@ -34,6 +34,9 @@ rectangle C4VersionDetailsArea <<legendArea>> [
 !$BOUNDARY_COLOR ?= "#444444"
 !$BOUNDARY_BG_COLOR ?= "transparent"
 !$BOUNDARY_BORDER_STYLE ?= "dashed"
+' boundary symbols written in the same line, typically only 50% of the size in element
+!$BOUNDARY_IMAGE_SIZE_FACTOR ?= 0.5
+!$BOUNDARY_DESCR_MAX_CHAR_WIDTH ?= 35
 
 !$LEGEND_TITLE_COLOR ?= "#000000"
 !$LEGEND_FONT_COLOR ?= "#FFFFFF"
@@ -608,13 +611,13 @@ $elementSkin
 !endfunction
 
 ' element symbols typically 4 times too big in legend
-!function $smallVersionSprite($sprite)
+!function $smallVersionSprite($sprite, $imageScale = $LEGEND_IMAGE_SIZE_FACTOR)
   ' ,scale= ... has to be first (...,color=black,scale=0.25... is invalid too)
   !if (%strpos($sprite, "=") < 0)
     !if (%substr($sprite, 0, 4) == "img:")
-      !$smallSprite = $sprite + "{scale=" + $LEGEND_IMAGE_SIZE_FACTOR + "}"
+      !$smallSprite = $sprite + "{scale=" + $imageScale + "}"
     !else
-      !$smallSprite = $sprite + ",scale=" + $LEGEND_IMAGE_SIZE_FACTOR
+      !$smallSprite = $sprite + ",scale=" + $imageScale
     !endif
   !else
     !$smallSprite = $sprite
@@ -1386,22 +1389,22 @@ $getLegendArea($alias, $hideStereotype, $details)
 ' Boundaries
 ' ##################################
 
-!unquoted procedure UpdateBoundaryStyle($elementName="", $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $type="", $legendText="", $borderStyle="", $borderThickness="")
+!unquoted procedure UpdateBoundaryStyle($elementName="", $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $type="", $legendText="", $borderStyle="", $borderThickness="", $sprite="", $legendSprite="")
   !if ($elementName != "")
     !$elementBoundary = $elementName + '_boundary'
-    UpdateElementStyle($elementBoundary, $bgColor, $fontColor, $borderColor, $shadowing, $shape, "", $type, $legendText, "", $borderStyle, $borderThickness)
+    UpdateElementStyle($elementBoundary, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $type, $legendText, $legendSprite, $borderStyle, $borderThickness)
   !else
-    UpdateElementStyle("boundary", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "", $type, $legendText, "", $borderStyle, $borderThickness)
+    UpdateElementStyle("boundary", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $type, $legendText, $legendSprite, $borderStyle, $borderThickness)
     ' simulate color inheritance
-    UpdateBoundaryStyle("enterprise", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "Enterprise", "", $borderStyle, $borderThickness)
-    UpdateBoundaryStyle("system", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "System", "", $borderStyle, $borderThickness)
-    UpdateBoundaryStyle("container", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "Container", "", $borderStyle, $borderThickness)
+    UpdateBoundaryStyle("enterprise", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "Enterprise", "", $borderStyle, $borderThickness, $sprite, $legendSprite)
+    UpdateBoundaryStyle("system", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "System", "", $borderStyle, $borderThickness, $sprite, $legendSprite)
+    UpdateBoundaryStyle("container", $bgColor, $fontColor, $borderColor, $shadowing, $shape, "Container", "", $borderStyle, $borderThickness, $sprite, $legendSprite)
   !endif
 !endprocedure
 
-!unquoted procedure AddBoundaryTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $type="", $legendText="", $borderStyle="", $borderThickness="")
+!unquoted procedure AddBoundaryTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $type="", $legendText="", $borderStyle="", $borderThickness="", $sprite="", $legendSprite="")
     !$tagBoundary = $tagStereo + '_boundary'
-    AddElementTag($tagBoundary, $bgColor, $fontColor, $borderColor, $shadowing, $shape, "", $type, $legendText, "", $borderStyle, $borderThickness)
+    AddElementTag($tagBoundary, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $type, $legendText, $legendSprite, $borderStyle, $borderThickness)
 !endprocedure
 
 ' add _boundary to all tags that short tag version can be used
@@ -1423,20 +1426,28 @@ $getLegendArea($alias, $hideStereotype, $details)
   !return $boundaryTags
 !endfunction
 
-!function $getBoundary($label, $type)
-  !if ($type == "")
-    !return '== ' + $breakLabel($label)
+!function $getBoundary($label, $type, $descr, $sprite)
+  !$line = '== '
+  !if ($sprite != "")
+    ' add sprite in label line that it is more compact
+    !$line = $line + $getSprite($smallVersionSprite($sprite, $BOUNDARY_IMAGE_SIZE_FACTOR)) + ' '
+  !endif
+  !$line = $line + $breakLabel($label)
+  !if ($type != "")
+    !$line = $line + '\n<size:' + $TECHN_FONT_SIZE + '>[' + $type + ']</size>'
   !endif
-  !if (type != "")
-    !return '== ' + $breakLabel($label) + '\n<size:' + $TECHN_FONT_SIZE + '>[' + $type + ']</size>'
+  !if ($descr != "")
+    !$line = $line + '\n\n' + $breakDescr($descr, $BOUNDARY_DESCR_MAX_CHAR_WIDTH)
   !endif
+  !return $line
 !endfunction
 
-!unquoted procedure Boundary($alias, $label, $type="", $tags="", $link="")
+!unquoted procedure Boundary($alias, $label, $type="", $tags="", $link="", $descr = "")
 !$boundaryTags = $addBoundaryPostfix($tags)
-' nodes $type reuses $techn definition of $boundaryTags
+' boundary $type reuses $techn definition of $boundaryTags
 !$type=$toElementArg($type, $boundaryTags, "ElementTagTechn", "boundary")
-rectangle "$getBoundary($label, $type)" $toStereos("boundary", $boundaryTags) as $alias $getLink($link)
+!$sprite=$toElementArg("", $boundaryTags, "ElementTagSprite", "boundary")
+rectangle "$getBoundary($label, $type, $descr, $sprite)" $toStereos("boundary", $boundaryTags) as $alias $getLink($link)
 !endprocedure
 
 ' Boundary Styling

diff --git a/C4_Container.puml b/C4_Container.puml
@@ -40,8 +40,8 @@ UpdateBoundaryStyle("container", $bgColor=$CONTAINER_BOUNDARY_BG_COLOR, $fontCol
   $addElementTagInclReuse("external_container", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite, $borderStyle, $borderThickness)
 !endprocedure
 
-!unquoted procedure UpdateContainerBoundaryStyle($bgColor=$CONTAINER_BOUNDARY_BG_COLOR, $fontColor=$CONTAINER_BOUNDARY_COLOR, $borderColor=$CONTAINER_BOUNDARY_COLOR, $shadowing="", $shape="", $type="Container", $legendText="", $borderStyle="", $borderThickness="")
-  UpdateBoundaryStyle("container", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness)
+!unquoted procedure UpdateContainerBoundaryStyle($bgColor=$CONTAINER_BOUNDARY_BG_COLOR, $fontColor=$CONTAINER_BOUNDARY_COLOR, $borderColor=$CONTAINER_BOUNDARY_COLOR, $shadowing="", $shape="", $type="Container", $legendText="", $borderStyle="", $borderThickness="", $sprite="", $legendSprite="")
+  UpdateBoundaryStyle("container", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness, $sprite, $legendSprite)
 !endprocedure
 
 ' Layout
@@ -92,12 +92,12 @@ endlegend
 ' Boundaries
 ' ##################################
 
-!unquoted procedure Container_Boundary($alias, $label, $tags="", $link="")
+!unquoted procedure Container_Boundary($alias, $label, $tags="", $link="", $descr = "")
   !if ($tags != "")
     !$allTags = $tags + '+container'
   !else
     !$allTags = 'container'
   !endif
   ' $type defined via $tag style
-  Boundary($alias, $label, "", $allTags, $link)
+  Boundary($alias, $label, "", $allTags, $link, $descr)
 !endprocedure
diff --git a/C4_Context.puml b/C4_Context.puml
@@ -62,11 +62,11 @@ UpdateBoundaryStyle("enterprise", $bgColor=$ENTERPRISE_BOUNDARY_BG_COLOR, $fontC
   $addElementTagInclReuse("external_system", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $type, $legendText, $legendSprite, $borderStyle, $borderThickness)
 !endprocedure
 
-!unquoted procedure UpdateEnterpriseBoundaryStyle($bgColor=$ENTERPRISE_BOUNDARY_BG_COLOR, $fontColor=$ENTERPRISE_BOUNDARY_COLOR, $borderColor=$ENTERPRISE_BOUNDARY_COLOR, $shadowing="", $shape="", $type="Enterprise", $legendText="", $borderStyle="", $borderThickness="")
-  UpdateBoundaryStyle("enterprise", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness)
+!unquoted procedure UpdateEnterpriseBoundaryStyle($bgColor=$ENTERPRISE_BOUNDARY_BG_COLOR, $fontColor=$ENTERPRISE_BOUNDARY_COLOR, $borderColor=$ENTERPRISE_BOUNDARY_COLOR, $shadowing="", $shape="", $type="Enterprise", $legendText="", $borderStyle="", $borderThickness="", $sprite="", $legendSprite="")
+  UpdateBoundaryStyle("enterprise", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness, $sprite, $legendSprite)
 !endprocedure
-!unquoted procedure UpdateSystemBoundaryStyle($bgColor=$SYSTEM_BOUNDARY_BG_COLOR, $fontColor=$SYSTEM_BOUNDARY_COLOR, $borderColor=$SYSTEM_BOUNDARY_COLOR, $shadowing="", $shape="", $type="System", $legendText="", $borderStyle="", $borderThickness="")
-  UpdateBoundaryStyle("system", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness)
+!unquoted procedure UpdateSystemBoundaryStyle($bgColor=$SYSTEM_BOUNDARY_BG_COLOR, $fontColor=$SYSTEM_BOUNDARY_COLOR, $borderColor=$SYSTEM_BOUNDARY_COLOR, $shadowing="", $shape="", $type="System", $legendText="", $borderStyle="", $borderThickness="", $sprite="", $legendSprite="")
+  UpdateBoundaryStyle("system", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness, $sprite, $legendSprite)
 !endprocedure
 
 ' Sprites
@@ -413,22 +413,22 @@ rectangle "$getPerson($label, $type, $descr, $sprite)$getProps()" $toStereos("ex
 ' Boundaries
 ' ##################################
 
-!unquoted procedure Enterprise_Boundary($alias, $label, $tags="", $link="")
+!unquoted procedure Enterprise_Boundary($alias, $label, $tags="", $link="", $descr = "")
   !if ($tags != "")
     !$allTags = $tags + '+enterprise'
   !else
     !$allTags = 'enterprise'
   !endif
   ' $type defined via $tag style
-  Boundary($alias, $label, "", $allTags, $link)
+  Boundary($alias, $label, "", $allTags, $link, $descr)
 !endprocedure
 
-!unquoted procedure System_Boundary($alias, $label, $tags="", $link="")
+!unquoted procedure System_Boundary($alias, $label, $tags="", $link="", $descr = "")
   !if ($tags != "")
     !$allTags = $tags + '+system'
   !else
     !$allTags = 'system'
   !endif
   ' $type defined via $tag style
-  Boundary($alias, $label, "", $allTags, $link)
+  Boundary($alias, $label, "", $allTags, $link, $descr)
 !endprocedure
diff --git a/C4_Sequence.puml b/C4_Sequence.puml
@@ -1,4 +1,4 @@
-' convert it with additional command line argument -DRELATIVE_INCLUDE="relative/absolute" to use locally
+' convert it with additional command line argument -DRELATIVE_INCLUDE="relative/absolute" to use locally
 !if %variable_exists("RELATIVE_INCLUDE")
   !include ./C4_Component.puml
 !else
@@ -192,7 +192,6 @@ sequenceDiagram {
   !return $breakWithNewline($text, $lineStart, $lineEnd, $REL_TECHN_MAX_CHAR_WIDTH)
 !endfunction
 
-' description is not displayed (size too big, line breaks not supported)
 ' properties are not displayed in sequence diagram (size would be too big)
 ' $breakLabel() not required by participant
 !procedure $getParticipant($elementType, $alias, $label, $techn, $descr, $sprite, $tags, $link)
@@ -324,55 +323,64 @@ $calcDescr
 ' alias ignored
 ' $breakLabel() not required by participant
 
-!unquoted procedure Boundary($alias, $label, $type="", $tags="", $link="")
+!unquoted procedure Boundary($alias, $label, $type="", $tags="", $link="", $descr = "")
 !$boundaryTags = $addBoundaryPostfix($tags)
-' nodes $type reuses $techn definition of $boundaryTags
+' boundary $type reuses $techn definition of $boundaryTags
 !$type=$toElementArg($type, $boundaryTags, "ElementTagTechn", "boundary")
+!$sprite=$toElementArg("", $boundaryTags, "ElementTagSprite", "boundary")
+!$labelSprite=""
+!if ($sprite != "")
+  ' add sprite in label line that it is more compact
+  !$labelSprite = $getSprite($smallVersionSprite($sprite, $BOUNDARY_IMAGE_SIZE_FACTOR)) + ' '
+!endif
 !if ($link != "")
   !$usedNewLine = ']]\n== [[' + $link + ' '
-  !$labelType = '== [[' + $link + ' ' + $breakText($label, $usedNewLine) + ']]'
+  !$labelType = '== [[' + $link + ' ' + $labelSprite + $breakText($label, $usedNewLine) + ']]'
 !else
   !$usedNewLine = '\n== '
-  !$labelType = $breakText($label, $usedNewLine)
+  !$labelType = $labelSprite + $breakText($label, $usedNewLine)
 !endif
 !if (type != "")
     !$labelType = $labelType + '\n<size:' + $TECHN_FONT_SIZE + '>[' + $type + ']</size>'
 !endif
+!if ($display_element_description == %true() && $descr != "")
+    !$labelType = $labelType + '\n\n' + $breakDescr($descr, $BOUNDARY_DESCR_MAX_CHAR_WIDTH)
+!endif
 box "$labelType" $toStereos("boundary", $boundaryTags)
 !endprocedure
 
 !procedure Boundary_End()
 end box
 !endprocedure
 
-!unquoted procedure Enterprise_Boundary($alias, $label, $tags="", $link="")
+!unquoted procedure Enterprise_Boundary($alias, $label, $tags="", $link="", $descr = "")
   !if ($tags != "")
     !$allTags = $tags + '+enterprise'
   !else
     !$allTags = 'enterprise'
   !endif
   ' $type defined via $tag style
-  Boundary($alias, $label, "", $allTags, $link)
+  Boundary($alias, $label, "", $allTags, $link, $descr)
 !endprocedure
 
-!unquoted procedure System_Boundary($alias, $label, $tags="", $link="")
+!unquoted procedure System_Boundary($alias, $label, $tags="", $link="", $descr = "")
   !if ($tags != "")
     !$allTags = $tags + '+system'
   !else
     !$allTags = 'system'
   !endif
   ' $type defined via $tag style
-  Boundary($alias, $label, "", $allTags, $link)
+  Boundary($alias, $label, "", $allTags, $link, $descr)
 !endprocedure
 
-!unquoted procedure Container_Boundary($alias, $label, $tags="", $link="")
+!unquoted procedure Container_Boundary($alias, $label, $tags="", $link="", $descr = "")
   !if ($tags != "")
     !$allTags = $tags + '+container'
   !else
     !$allTags = 'container'
   !endif
   ' $type defined via $tag style
-  Boundary($alias, $label, "", $allTags, $link)
+  Boundary($alias, $label, "", $allTags, $link, $descr)
 !endprocedure
 
 ' Relationship (redefinition)

diff --git a/README.md b/README.md
@@ -241,9 +241,9 @@ SHOW_LEGEND()
     - `System_Ext(alias, label, ?descr, ?sprite, ?tags, ?link, ?type, ?baseShape)`
     - `SystemDb_Ext(alias, label, ?descr, ?sprite, ?tags, ?link, ?type)`
     - `SystemQueue_Ext(alias, label, ?descr, ?sprite, ?tags, ?link, ?type)`
-    - `Boundary(alias, label, ?type, ?tags, ?link)`
-    - `Enterprise_Boundary(alias, label, ?tags, ?link)`
-    - `System_Boundary(alias, label, ?tags, ?link)`
+    - `Boundary(alias, label, ?type, ?tags, ?link, ?descr)`
+    - `Enterprise_Boundary(alias, label, ?tags, ?link, ?descr)`
+    - `System_Boundary(alias, label, ?tags, ?link, ?descr)`
   - Sprites:
     - `person`
     - `person2`
@@ -262,7 +262,7 @@ SHOW_LEGEND()
     - `Container_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, ?link, ?baseShape)`
     - `ContainerDb_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, ?link)`
     - `ContainerQueue_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, ?link)`
-    - `Container_Boundary(alias, label, ?tags, ?link)`
+    - `Container_Boundary(alias, label, ?tags, ?link, ?descr)`
 
 ### Component diagram
 
@@ -600,13 +600,13 @@ Additional tags/stereotypes can be added to the existing element stereotypes (co
   Introduces a new element tag. The styles of the tagged elements are updated and the tag is displayed in the calculated legend.
 - `AddRelTag(tagStereo, ?textColor, ?lineColor, ?lineStyle, ?sprite, ?techn, ?legendText, ?legendSprite, ?lineThickness)`:
   Introduces a new Relationship tag. The styles of the tagged relationships are updated and the tag is displayed in the calculated legend.
-- `AddBoundaryTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness, ?borderStyle, ?borderThickness)`:
+- `AddBoundaryTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness, ?borderStyle, ?borderThickness, ?sprite, ?legendSprite)`:
   Introduces a new Boundary tag. The styles of the tagged boundaries are updated and the tag is displayed in the calculated legend.
 - `UpdateElementStyle(elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite, ?borderStyle, ?borderThickness)`:
   This call updates the default style of the elements (component, ...) and creates no additional legend entry.
 - `UpdateRelStyle(textColor, lineColor)`:
   This call updates the default relationship colors and creates no additional legend entry.
-- `UpdateBoundaryStyle(?elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness)`:
+- `UpdateBoundaryStyle(?elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness, ?sprite, ?legendSprite)`:
   This call updates the default style of the existing boundaries and creates no additional legend entry.
   If the element name is "" then it updates generic, enterprise, system and container boundary style in on call.
 - `RoundedBoxShape()`: This call returns the name of the rounded box shape and can be used as ?shape argument.
@@ -650,9 +650,9 @@ Following calls introduces new element tags with element specific default colors
 
 Like the element specific tag definitions exist boundary specific calls with their default colors **and type**:
 
-- `UpdateContainerBoundaryStyle(?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness)`
-- `UpdateSystemBoundaryStyle(?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness)`
-- `UpdateEnterpriseBoundaryStyle(?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness)`
+- `UpdateContainerBoundaryStyle(?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness, ?sprite, ?legendSprite)`
+- `UpdateSystemBoundaryStyle(?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness, ?sprite, ?legendSprite)`
+- `UpdateEnterpriseBoundaryStyle(?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?type, ?legendText, ?borderStyle, ?borderThickness, ?sprite, ?legendSprite)`
 
 ### Comments