Merge pull request #58 from jeanmarc-contrib/master

Reintroduce special shapes for some ArchiMate elements

Author: Potherca

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
@@ -164,12 +167,89 @@ For example
 | Grouping       | ![Grouping](./images/Example-Grouping.png)            |
 | Other_Grouping | ![Other_Grouping](./images/Example-OtherGrouping.png) |
 
+### 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 named parameter that allows
+you to override the setting for an individual shape.
+
+Shapes that support special shapes are:
+* Business Actor<sup>*</sup>
+* Business Role
+* Business Service<sup>*</sup>
+* Business Product
+* Application Service<sup>*</sup>
+* Technology Node
+* Technology Artifact
+* Technology Service<sup>*</sup>
+* Motivation Stakeholder
+* Motivation Meaning
+* Motivation Value<sup>*</sup>
+* Strategy Value Stream
+    
+> [!IMPORTANT]
+> The special shapes marked with <sup>*</sup> do not support nesting other elements within them, so you need to add a 
+> `$nest=%true()` parameter when nesting using these elements with special shapes.
+
+```plantuml
+@startuml
+
+!global $ARCH_SPECIAL_SHAPES = %true()
+
+!include <archimate/Archimate>
+
+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", $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())
+}
+Strategy_ValueStream(SV, "Strategy Value Stream", $nest=%true()) {
+    Strategy_ValueStream(SVI, "Inner Value Stream", $special=%true())
+    Strategy_ValueStream(SVI2, "Another Inner Value Stream", $special=%false())
+}
+
+Business_Actor(BA, "Business Actor", $nest=%true()) {
+    Business_Actor(BAI, "Inner Actor", $special=%true())
+    Business_Actor(BAI2, "Another Inner Actor", $special=%false())
+}
+Business_Service(BS, "Business Service", $nest=%true()) {
+    Business_Service(BSI, "Inner Service", $special=%true())
+    Business_Service(BSI2, "Another Inner Service", $special=%false())
+}
+Business_Product(BP, "Business Product", $nest=%true()) {
+    Business_Product(BPI, "Inner Product", $special=%true())
+    Business_Product(BPI2, "Another Inner Product", $special=%false())
+}
+
+Technology_Node(TN, "Technology Node"){
+    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", $special=%true())
+    Technology_Artifact(TAI2, "Another Inner Artifact", $special=%false())
+}
+
+@enduml
+```
+
+Result:
+
+![Special Shapes for some types](./images/SpecialShapes.png)
 
 ### Nesting of Components
 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)
@@ -199,6 +279,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, the `Motivation_Value` element, and the `Business_Actor` element. If you have
+> special shapes active, you have to add a `$nest=%true()` 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.
 

dist/plantuml-stdlib/stdlib/archimate/Archimate.puml

@@ -3,7 +3,7 @@
 ' Version
 '######################################
 !function ArchimateVersion()
-  !$archimateVersion  =  "3.2.0"
+  !$archimateVersion  =  "3.2.1"
   !return $archimateVersion
 !endfunction
 
@@ -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
@@ -88,16 +88,28 @@
 !unquoted procedure Strategy_CourseOfAction($alias, $label, $nest=0)
   archimate $ARCH_STRATEGY_FILLCOLOR "$label" <<strategy-courseofaction>> as $alias
 !endprocedure
-!unquoted procedure Strategy_ValueStream($alias, $label, $nest=0)
-  archimate $ARCH_STRATEGY_FILLCOLOR "$label" <<strategy-valuestream>> as $alias
+!unquoted procedure Strategy_ValueStream($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true())
+      process "$label" as $alias $ARCH_STRATEGY_FILLCOLOR
+  !else
+      archimate $ARCH_STRATEGY_FILLCOLOR "$label" <<strategy-valuestream>> as $alias
+  !endif
 !endprocedure
 
 'Business Elements
-!unquoted procedure Business_Actor($alias, $label, $nest=0)
-  archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-actor>> as $alias
-!endprocedure
-!unquoted procedure Business_Role($alias, $label, $nest=0)
-  archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-role>> as $alias
+!unquoted procedure Business_Actor($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true() && $nest == %false())
+      actor "$label" as $alias $ARCH_BUSINESS_FILLCOLOR
+  !else
+      archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-actor>> as $alias
+  !endif
+!endprocedure
+!unquoted procedure Business_Role($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true())
+    queue "%n()$label%n()" as $alias $ARCH_BUSINESS_FILLCOLOR
+  !else
+    archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-role>> as $alias
+  !endif
 !endprocedure
 !unquoted procedure Business_Collaboration($alias, $label, $nest=0)
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-collaboration>> as $alias
@@ -117,8 +129,12 @@
 !unquoted procedure Business_Event($alias, $label, $nest=0)
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-event>> as $alias
 !endprocedure
-!unquoted procedure Business_Service($alias, $label, $nest=0)
-  archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-service>> as $alias
+!unquoted procedure Business_Service($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true() && $nest == %false())
+      rectangle "$label" <<service-special>> as $alias $ARCH_BUSINESS_FILLCOLOR
+  !else
+      archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-service>> as $alias
+  !endif
 !endprocedure
 !unquoted procedure Business_Object($alias, $label, $nest=0)
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-object>> as $alias
@@ -129,8 +145,12 @@
 !unquoted procedure Business_Representation($alias, $label, $nest=0)
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-representation>> as $alias
 !endprocedure
-!unquoted procedure Business_Product($alias, $label, $nest=0)
-  archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-product>> as $alias
+!unquoted procedure Business_Product($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true())
+    frame "%n()$label%n()" as $alias $ARCH_BUSINESS_FILLCOLOR
+  !else
+    archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-product>> as $alias
+  !endif
 !endprocedure
 !unquoted procedure Business_Location($alias, $label, $nest=0)
   archimate $ARCH_BUSINESS_FILLCOLOR "$label" <<business-location>> as $alias
@@ -158,16 +178,24 @@
 !unquoted procedure Application_Event($alias, $label, $nest=0)
   archimate $ARCH_APPLICATION_FILLCOLOR "$label" <<application-event>> as $alias
 !endprocedure
-!unquoted procedure Application_Service($alias, $label, $nest=0)
-  archimate $ARCH_APPLICATION_FILLCOLOR "$label" <<application-service>> as $alias
+!unquoted procedure Application_Service($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true() && $nest == %false())
+      rectangle "$label" <<service-special>> as $alias $ARCH_APPLICATION_FILLCOLOR
+  !else
+      archimate $ARCH_APPLICATION_FILLCOLOR "$label" <<application-service>> as $alias
+  !endif
 !endprocedure
 !unquoted procedure Application_DataObject($alias, $label, $nest=0)
   archimate $ARCH_APPLICATION_FILLCOLOR "$label" <<application-dataobject>> as $alias
 !endprocedure
 
 'Technology Elements
-!unquoted procedure Technology_Node($alias, $label, $nest=0)
-  archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-node>> as $alias
+!unquoted procedure Technology_Node($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true())
+    node "$label" as $alias $ARCH_TECHNOLOGY_FILLCOLOR
+  !else
+    archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-node>> as $alias
+  !endif
 !endprocedure
 !unquoted procedure Technology_Device($alias, $label, $nest=0)
   archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-device>> as $alias
@@ -199,11 +227,19 @@
 !unquoted procedure Technology_Event($alias, $label, $nest=0)
   archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-event>> as $alias
 !endprocedure
-!unquoted procedure Technology_Service($alias, $label, $nest=0)
-  archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-service>> as $alias
+!unquoted procedure Technology_Service($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !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)
-  archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-artifact>> as $alias
+!unquoted procedure Technology_Artifact($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true())
+    file "$label" as $alias $ARCH_TECHNOLOGY_FILLCOLOR
+  !else
+    archimate $ARCH_TECHNOLOGY_FILLCOLOR "$label" <<technology-artifact>> as $alias
+  !endif
 !endprocedure
 
 'Physical Elements
@@ -221,8 +257,12 @@
 !endprocedure
 
 'Motivation Elements
-!unquoted procedure Motivation_Stakeholder($alias, $label, $nest=0)
-  archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-stakeholder>> as $alias
+!unquoted procedure Motivation_Stakeholder($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !if ($special == %true())
+    queue "%n()$label%n()" as $alias $ARCH_MOTIVATION_FILLCOLOR
+  !else
+    archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-stakeholder>> as $alias
+  !endif
 !endprocedure
 !unquoted procedure Motivation_Driver($alias, $label, $nest=0)
   archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-driver>> as $alias
@@ -245,11 +285,19 @@
 !unquoted procedure Motivation_Constraint($alias, $label, $nest=0)
   archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-constraint>> as $alias
 !endprocedure
-!unquoted procedure Motivation_Meaning($alias, $label, $nest=0)
-  archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-meaning>> as $alias
-!endprocedure
-!unquoted procedure Motivation_Value($alias, $label, $nest=0)
-  archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-value>> as $alias
+!unquoted procedure Motivation_Meaning($alias, $label, $nest=0, $special = $ARCH_SPECIAL_SHAPES)
+  !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() && $nest == %false())
+    usecase "%n()$label%n()" as $alias $ARCH_MOTIVATION_FILLCOLOR
+  !else
+    archimate $ARCH_MOTIVATION_FILLCOLOR "$label" <<motivation-value>> as $alias
+  !endif
 !endprocedure
 
 'Implementation Elements

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>

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>

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>