use %true() and %false() functions; handle special shapes and nesting; update README.md to explain how to combine nesting and special shapes

JeanMarc van Leerdam · JeanMarc van Leerdam · commit 87661bcb33cf · 2025-09-30T07:58:15.000+02:00
diff --git a/README.md b/README.md
@@ -55,11 +55,11 @@ You will need to:
 1. download the latest version of `Archimate.puml`, including the themes folder and store them some place locally
    * `./dist/plantuml/plantuml-stdlib/stdlib/archimate/Archimate.puml`
    * `./dist/plantuml/plantuml-stdlib/stdlib/archimate/themes/` folder plus files
-2. Add a `!global $ARCH_LOCAL = true` to your PlantUML file prior to the include statement 
+2. Add a `!global $ARCH_LOCAL = %true()` to your PlantUML file prior to the include statement 
 
 ```plantuml
 
-!global $ARCH_LOCAL = true
+!global $ARCH_LOCAL = %true()
 !$LOCAL_FOLDER = "[path to the folder that holds Archimate.puml]"
 !include $LOCAL_FOLDER/Archimate.puml
 
@@ -74,16 +74,19 @@ You will need to:
 > [!IMPORTANT]
 > Using `!include` on `https://raw.githubusercontent.com/plantuml-stdlib/Archimate-PlantUML/master/dist/plantuml-stdlib/stdlib/archimate/Archimate.puml`
 > **may** not work, because that file by default relies on the built-in themes, which may not be compatible with the latest version of `Archimate.puml`
-> on `master`._
+> on `master`.
 
 ## Usage
 After you have included `Archimate.puml` you can use the defined macros for ArchiMate elements. 
 
 ### ArchiMate Elements
-The ArchiMate elements are defined in the following pattern:
+The ArchiMate elements are defined in the following pattern, with two mandatory parameters and two optional parameters:
 ```plantuml
-Category_ElementName(nameOfTheElement, "description")
+Category_ElementName(nameOfTheElement, "description", $nest=%false(), $special=$ARCH_SPECIAL_SHAPES)
 ```
+
+Nesting and special shapes are explained further down this page.
+
 For example:  
 * To define a `Stakeholder` element, which is part of `Motivation` category, the syntax will be
     ```plantuml
@@ -167,32 +170,55 @@ For example
 ### Special shapes
 By default, all shapes are rectangular (either with sharp, rounded, or beveled corners) and show a stereotype icon in the
 top right. Some elements can be shown in a different shape, without the stereotype. This is controlled by setting
-`$ARCH_SPECIAL_SHAPES` to `true` (default is `false`). The supported elements have an optional third parameter that allows
-you to override the setting for an individual shape:
+`$ARCH_SPECIAL_SHAPES` to `%true()` (default is `%false()`). The supported elements have an optional named parameter that allows
+you to override the setting for an individual shape.
+
+Shapes that support special shapes are:
+* Business Role
+* Business Service(*)
+* Application Service(*)
+* Technology Node
+* Technology Artifact
+* Technology Service(*)
+* Motivation Stakeholder
+* Motivation Meaning
+* Motivation Value(*)
+
+> [!IMPORTANT]
+> Note: the special shapes marked with (*) do not support nesting other elements within them, so you need to add a 
+> `$nest=%false()` parameter when using these elements with special shapes.
 
 ```plantuml
 @startuml
 
-!global $ARCH_SPECIAL_SHAPES = true
+!global $ARCH_SPECIAL_SHAPES = %true()
 
 !include <archimate/Archimate>
 
-Business_Service(BS, "Business Service") {
-    Business_Service(BSI, "Inner Service", true)
-    Business_Service(BSI2, "Another Inner Service", false)
+Motivation_Stakeholder(MS, "Motivation Stakeholder") {
+    Motivation_Stakeholder(MSI, "Inner Stakeholder", $special=%true())
+    Motivation_Stakeholder(MSI2, "Another Inner Stakeholder", $special=%false())
 }
 Motivation_Meaning(MM, "Motivation Meaning") {
-    Motivation_Meaning(MMI, "Inner Meaning", true)
-    Motivation_Meaning(MMI2, "Another Inner Meaning", false)
+    Motivation_Meaning(MMI, "Inner Meaning", $special=%true())
+    Motivation_Meaning(MMI2, "Another Inner Meaning", $special=%false())
+}
+Motivation_Value(MV, "Motivation Value", $nest=%true()) {
+    Motivation_Value(MVI, "Inner Value", $special=%true())
+    Motivation_Value(MVI2, "Another Inner Value", $special=%false())
+}
+Business_Service(BS, "Business Service", $nest=%true()) {
+    Business_Service(BSI, "Inner Service", $special=%true())
+    Business_Service(BSI2, "Another Inner Service", $special=%false())
 }
 Technology_Node(TN, "Technology Node"){
-    Technology_Node(TNI, "Inner Node", true)
-    Technology_Node(TNI2, "Another Inner Node", false)
+    Technology_Node(TNI, "Inner Node", $special=%true())
+    Technology_Node(TNI2, "Another Inner Node", $special=%false())
 }
 
 Technology_Artifact(TA, "Technology Artifact") {
-    Technology_Artifact(TAI, "Inner Artifact", true)
-    Technology_Artifact(TAI2, "Another Inner Artifact", false)
+    Technology_Artifact(TAI, "Inner Artifact", $special=%true())
+    Technology_Artifact(TAI2, "Another Inner Artifact", $special=%false())
 }
 
 @enduml
@@ -206,7 +232,7 @@ Result:
 Nesting allows grouping components hierarchically, improving diagram clarity. There are no limitations on the number of levels of nesting.
 The implementation allows nesting of any components inside any other components. When nesting, the element will be displayed in its normal shape, with the archimate archetype on the top right corner.
 
-Nesting is automatic, just add the nested elements between curly braces `{ ... }`:
+Nesting is automatic by default, just add the nested elements between curly braces `{ ... }`:
 ```plantuml
 Category_ElementName(nameOfTheElement, "description") {
     Category_ElementName(uniqueName, "description)
@@ -236,6 +262,13 @@ Output:
 
 ![Nesting Example](./images/Example-Nesting.png)
 
+#### Nesting with special shapes
+
+> [!IMPORTANT]
+> As mentioned above, some elements support special shapes. However, when using special shapes, nesting is not always possible using the 
+> special shape. This applies to all `Service` elements, and the `Motivation_Value` element. If you have special shapes active, you have
+> to add a `$nest=%false()` parameter to these elements to avoid errors or unexpected results.
+
 ### Theme Support
 Theme support is enabled and 5 variations are available. All the themes are based on Archimate specifications.
 
diff --git a/dist/plantuml-stdlib/stdlib/archimate/Archimate.puml b/dist/plantuml-stdlib/stdlib/archimate/Archimate.puml
@@ -18,23 +18,23 @@
 ' Styling
 '######################################
 
-!global $ARCH_DEBUG ?= false
-!global $ARCH_LOCAL ?= false
+!global $ARCH_DEBUG ?= %false()
+!global $ARCH_LOCAL ?= %false()
 
-!if ($ARCH_LOCAL == true)
+!if ($ARCH_LOCAL == %true())
     !include themes/shared_style.puml
 !else
     !include <archimate/themes/shared_style>
 !endif
 
-!if ($ARCH_DEBUG == true)
+!if ($ARCH_DEBUG == %true())
     left header "Created using Archimate.puml version ArchimateVersion()"
 !endif
 
 ' Layout
 ' ##################################
 !procedure LAYOUT_AS_SKETCH()
-    !option handwritten true
+    !option handwritten %true()
     <style>
         root {
             BackgroundColor #EEEBDC
@@ -97,7 +97,7 @@
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-actor>> as $alias
 !endprocedure
 !unquoted procedure Business_Role($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true())
     queue "%n()$label%n()" as $alias $ARCH_BUSINESS_FILLCOLOR
   !else
     archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-role>> as $alias
@@ -122,7 +122,7 @@
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-event>> as $alias
 !endprocedure
 !unquoted procedure Business_Service($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true() && $nest == %false())
       rectangle "$label" <<service-special>> as $alias $ARCH_BUSINESS_FILLCOLOR
   !else
       archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-service>> as $alias
@@ -167,7 +167,7 @@
   archimate $ARCH_APPLICATION_FILLCOLOR "$label" <<application-event>> as $alias
 !endprocedure
 !unquoted procedure Application_Service($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true() && $nest == %false())
       rectangle "$label" <<service-special>> as $alias $ARCH_APPLICATION_FILLCOLOR
   !else
       archimate $ARCH_APPLICATION_FILLCOLOR "$label" <<application-service>> as $alias
@@ -179,7 +179,7 @@
 
 'Technology Elements
 !unquoted procedure Technology_Node($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true())
     node "$label" as $alias $ARCH_TECHNOLOGY_FILLCOLOR
   !else
     archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-node>> as $alias
@@ -216,14 +216,14 @@
   archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-event>> as $alias
 !endprocedure
 !unquoted procedure Technology_Service($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true() && $nest == %false())
       rectangle "$label" <<service-special>> as $alias $ARCH_TECHNOLOGY_FILLCOLOR
   !else
       archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-service>> as $alias
   !endif
 !endprocedure
 !unquoted procedure Technology_Artifact($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true())
     file "$label" as $alias $ARCH_TECHNOLOGY_FILLCOLOR
   !else
     archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-artifact>> as $alias
@@ -246,7 +246,7 @@
 
 'Motivation Elements
 !unquoted procedure Motivation_Stakeholder($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true())
     queue "%n()$label%n()" as $alias $ARCH_MOTIVATION_FILLCOLOR
   !else
     archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-stakeholder>> as $alias
@@ -274,14 +274,14 @@
   archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-constraint>> as $alias
 !endprocedure
 !unquoted procedure Motivation_Meaning($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true())
     cloud "$label" as $alias $ARCH_MOTIVATION_FILLCOLOR
   !else
     archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-meaning>> as $alias
   !endif
 !endprocedure
 !unquoted procedure Motivation_Value($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
-  !if ($special == true)
+  !if ($special == %true() && $nest == %false())
     usecase "%n()$label%n()" as $alias $ARCH_MOTIVATION_FILLCOLOR
   !else
     archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-value>> as $alias
diff --git a/dist/plantuml-stdlib/stdlib/archimate/_examples_/example.puml b/dist/plantuml-stdlib/stdlib/archimate/_examples_/example.puml
@@ -1,13 +1,13 @@
 @startuml
 
-!global $ARCH_LOCAL = true
-!global $ARCH_DEBUG = true
+!global $ARCH_LOCAL = %true()
+!global $ARCH_DEBUG = %true()
 
 '!global $ARCH_LINETYPE = curve
 '!global $ARCH_LINETYPE = polyline
 '!global $ARCH_LINETYPE = ortho
 
-!if ($ARCH_LOCAL == false)
+!if ($ARCH_LOCAL == %false())
     !include <archimate/Archimate>
     '!theme archimate-alternate from <archimate/themes>
     '!theme archimate-handwriting from <archimate/themes>
diff --git a/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-alternate.puml b/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-alternate.puml
@@ -16,9 +16,9 @@
 !global $ARCH_RELATIONSHIP_LINECOLOR = "#Black"
 !global $ARCH_RELATIONSHIP_FONTCOLOR = "#Black"
 
-!global $ARCH_LOCAL ?= false
+!global $ARCH_LOCAL ?= %false()
 
-!if ($ARCH_LOCAL == true)
+!if ($ARCH_LOCAL == %true())
     !include shared_style.puml
 !else
     !include <archimate/themes/shared_style>
diff --git a/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-handwriting.puml b/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-handwriting.puml
@@ -5,7 +5,7 @@
 !global $ARCH_DEFAULT_FONT = "Comic Sans MS"
 !global $ARCH_DEFAULT_FONTSIZE = 14
 
-!option handwritten true
+!option handwritten %true()
 
 center footer <font color=red>Warning:</font> Created for discussion, needs to be validated
 
@@ -19,9 +19,9 @@ center footer <font color=red>Warning:</font> Created for discussion, needs to b
     }
 </style>
 
-!global $ARCH_LOCAL ?= false
+!global $ARCH_LOCAL ?= %false()
 
-!if ($ARCH_LOCAL == true)
+!if ($ARCH_LOCAL == %true())
     !include shared_style.puml
 !else
     !include <archimate/themes/shared_style>
diff --git a/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-lowsaturation.puml b/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-lowsaturation.puml
@@ -16,9 +16,9 @@
 !global $ARCH_RELATIONSHIP_LINECOLOR = "#Black"
 !global $ARCH_RELATIONSHIP_FONTCOLOR = "#Black"
 
-!global $ARCH_LOCAL ?= false
+!global $ARCH_LOCAL ?= %false()
 
-!if ($ARCH_LOCAL == true)
+!if ($ARCH_LOCAL == %true())
     !include shared_style.puml
 !else
     !include <archimate/themes/shared_style>
diff --git a/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-saturated.puml b/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-saturated.puml
@@ -16,9 +16,9 @@
 !global $ARCH_RELATIONSHIP_LINECOLOR = "#Black"
 !global $ARCH_RELATIONSHIP_FONTCOLOR = "#Black"
 
-!global $ARCH_LOCAL ?= false
+!global $ARCH_LOCAL ?= %false()
 
-!if ($ARCH_LOCAL == true)
+!if ($ARCH_LOCAL == %true())
     !include shared_style.puml
 !else
     !include <archimate/themes/shared_style>
diff --git a/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-standard.puml b/dist/plantuml-stdlib/stdlib/archimate/themes/puml-theme-archimate-standard.puml
@@ -16,9 +16,9 @@
 !global $ARCH_RELATIONSHIP_LINECOLOR = "#Black"
 !global $ARCH_RELATIONSHIP_FONTCOLOR = "#Black"
 
-!global $ARCH_LOCAL ?= false
+!global $ARCH_LOCAL ?= %false()
 
-!if ($ARCH_LOCAL == true)
+!if ($ARCH_LOCAL == %true())
     !include shared_style.puml
 !else
     !include <archimate/themes/shared_style>
diff --git a/dist/plantuml-stdlib/stdlib/archimate/themes/shared_style.puml b/dist/plantuml-stdlib/stdlib/archimate/themes/shared_style.puml
@@ -44,7 +44,7 @@ skinparam lineType $ARCH_LINETYPE
 ' $ARCH_SPECIAL_SHAPES drives the usage of special shapes for some elements.
 ' Note that we only use plantuml shapes that support nesting
 ' This means that we do not use actor, queue (for role and stakeholder), or usecase (for value)
-!global $ARCH_SPECIAL_SHAPES ?= false
+!global $ARCH_SPECIAL_SHAPES ?= %false()
 
 <style>
     archimate {
diff --git a/samples/SpecialShapes.puml b/samples/SpecialShapes.puml
@@ -1,10 +1,10 @@
 @startuml
 
-!global $ARCH_DEBUG = false
-!global $ARCH_LOCAL = false
-!global $ARCH_SPECIAL_SHAPES = true
+!global $ARCH_DEBUG = %false()
+!global $ARCH_LOCAL = %true()
+!global $ARCH_SPECIAL_SHAPES = %true()
 
-!if ($ARCH_LOCAL == false)
+!if ($ARCH_LOCAL == %false())
     !include <archimate/Archimate>
     '!theme archimate-alternate from <archimate/themes>
     '!theme archimate-handwriting from <archimate/themes>
@@ -23,22 +23,34 @@
     '!theme archimate-standard from $LOCAL_FOLDER/themes
 !endif
 
-Business_Service(BS, "Business Service") {
-    Business_Service(BSI, "Inner Service", true)
-    Business_Service(BSI2, "Another Inner Service", false)
+
+Motivation_Stakeholder(MS, "Motivation Stakeholder") {
+    Motivation_Stakeholder(MSI, "Inner Stakeholder", $special=%true())
+    Motivation_Stakeholder(MSI2, "Another Inner Stakeholder", $special=%false())
 }
 Motivation_Meaning(MM, "Motivation Meaning") {
-    Motivation_Meaning(MMI, "Inner Meaning", true)
-    Motivation_Meaning(MMI2, "Another Inner Meaning", false)
+    Motivation_Meaning(MMI, "Inner Meaning", $special=%true())
+    Motivation_Meaning(MMI2, "Another Inner Meaning", $special=%false())
+}
+Motivation_Value(MV, "Motivation Value", $nest=%true()) {
+    Motivation_Value(MVI, "Inner Value", $special=%true())
+    Motivation_Value(MVI2, "Another Inner Value", $special=%false())
+}
+Business_Service(BS, "Business Service", $nest=%true()) {
+    Business_Service(BSI, "Inner Service", $special=%true())
+    Business_Service(BSI2, "Another Inner Service", $special=%false())
 }
 Technology_Node(TN, "Technology Node"){
-    Technology_Node(TNI, "Inner Node", true)
-    Technology_Node(TNI2, "Another Inner Node", false)
+    Technology_Node(TNI, "Inner Node", $special=%true())
+    Technology_Node(TNI2, "Another Inner Node", $special=%false())
 }
 
 Technology_Artifact(TA, "Technology Artifact") {
-    Technology_Artifact(TAI, "Inner Artifact", true)
-    Technology_Artifact(TAI2, "Another Inner Artifact", false)
+    Technology_Artifact(TAI, "Inner Artifact", $special=%true())
+    Technology_Artifact(TAI2, "Another Inner Artifact", $special=%false())
 }
 
+MS -[hidden]- BS
+MM -[hidden]- TN
+MV -[hidden]- TA
 @enduml
