From fa3a1ae9a3bf5278f0e5362d3d40d077755661e8 Mon Sep 17 00:00:00 2001 From: KIRCHSTH Date: Fri, 18 Dec 2020 20:35:13 +0100 Subject: [PATCH] #97 Context Diagram supports selectable default person sprites --- C4_Context.puml | 97 +++++++++++++++++++++++++++++++++++-- LayoutOptions.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++- README.md | 21 ++++++-- 3 files changed, 231 insertions(+), 9 deletions(-) diff --git a/C4_Context.puml b/C4_Context.puml index d15e73a..9148713 100644 --- a/C4_Context.puml +++ b/C4_Context.puml @@ -46,6 +46,9 @@ skinparam rectangle<> { BorderColor #8A8A8A } +' Sprites +' ################################## + sprite $person [48x48/16] { 000000000000000000000000000000000000000000000000 000000000000000000000000000000000000000000000000 @@ -97,6 +100,67 @@ sprite $person [48x48/16] { 000000000000000000000000000000000000000000000000 } +sprite $personC4 [48x48/16] { +0000000000000000000049BCCA7200000000000000000000 +0000000000000000006EFFFFFFFFB3000000000000000000 +00000000000000001CFFFFFFFFFFFF700000000000000000 +0000000000000001EFFFFFFFFFFFFFF80000000000000000 +000000000000000CFFFFFFFFFFFFFFFF6000000000000000 +000000000000007FFFFFFFFFFFFFFFFFF100000000000000 +00000000000001FFFFFFFFFFFFFFFFFFF900000000000000 +00000000000006FFFFFFFFFFFFFFFFFFFF00000000000000 +0000000000000BFFFFFFFFFFFFFFFFFFFF40000000000000 +0000000000000EFFFFFFFFFFFFFFFFFFFF70000000000000 +0000000000000FFFFFFFFFFFFFFFFFFFFF80000000000000 +0000000000000FFFFFFFFFFFFFFFFFFFFF80000000000000 +0000000000000DFFFFFFFFFFFFFFFFFFFF60000000000000 +0000000000000AFFFFFFFFFFFFFFFFFFFF40000000000000 +00000000000006FFFFFFFFFFFFFFFFFFFE00000000000000 +00000000000000EFFFFFFFFFFFFFFFFFF800000000000000 +000000000000007FFFFFFFFFFFFFFFFFF100000000000000 +000000000000000BFFFFFFFFFFFFFFFF5000000000000000 +0000000000000001DFFFFFFFFFFFFFF70000000000000000 +00000000000000000BFFFFFFFFFFFF500000000000000000 +0000000000000000005DFFFFFFFFA1000000000000000000 +0000000000000000000037ABB96100000000000000000000 +000000000002578888300000000005888864100000000000 +0000000007DFFFFFFFFD9643347BFFFFFFFFFB4000000000 +00000004EFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB10000000 +0000007FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD2000000 +000006FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE100000 +00003FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB00000 +0000BFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF50000 +0003FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD0000 +0009FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF2000 +000DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF6000 +000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF8000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA000 +000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF8000 +000DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF6000 +0009FFFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFFF2000 +0003FFFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFFD0000 +0000BFFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFF50000 +00003FFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFB00000 +000006FFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFE100000 +0000007FFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFD2000000 +00000004EFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFB10000000 +0000000007DF8FFFFFFFFFFFFFFFFFFFFFF8FB4000000000 +000000000002578888888888888888888864100000000000 +} + +sprite $person3D [64x64/16z] { +rTH9iYif38LX2_NIhVrljnAP8717u3VpF_yETdQt7-XNQyGYmWZ_We5KfLBbzZL7KQ4HYp9yn-dIY3GNLE0xpbFp5R5yCu35PpMWSin1fMkivYzGEl_rX8Cl +0w9mUZmFtjhmbTBflwUhuZLGNfX4pZpBtRV5Nn4V_W6HD-UpC6ixyih3u-3JunUUS3Gz7NeHgeM5p_DFFLFLzV1y_F-fUwOPytVNlocNMVIy_yT_O3OvAvw_ +lNDWS_pk_Nl35KyzXmeHYqpDn6fuUdg6gJ1rsRk_l9P9HzpIpLsLYRYg3wYQHz8HD_LmCrNfbhYqkTd9GF7oVM5aLr43UDl7wUgzBcJyVtTJYpwG0LlUCehV +XI5T8KUeUlG1JzlwovZVkxnJGyGctKUC0TeUx-eZCm-6rXfSrZp6GFh6Qvg5-qpXghcNhlO_85nzzTvkSAFLkssk0APRn3h0022nPf7m-URD_tal5A1PL0T_ +GAQFuRq1Ugov9N_qCVpCgN4yUzsU_vYqzU_dtlEhLxJLPvRVN_yrGt_nyib3tPvOSuxL_wLvukxvyqSV6cj_wR5v1I73uZ6FjOn8sNtvqytZO-wn_G90itGp +z_VOxEAqumqjm-rzTJgt1fyuD4JIo8ntPMOO8pQ0pxw-rHxP-vjbBzo4YR2rZSVnkVQ8Fl3VLUTH7tIv_7B-Ti2yJ_GwxbfbS_mSgB_0KXDzfDE1cURf-uMQ +OEbTiCS3JxsVw1j8IzXjuSEWLcO06_l3_Nx_0m +} + ' Layout ' ################################## @@ -111,21 +175,46 @@ legend right endlegend !endprocedure +!global $defaultPerson = "person" + +!procedure PERSON_SPRITE_NONE() + !$defaultPerson = "" +!endprocedure + +!procedure PERSON_SPRITE_ACTIVE() + !$defaultPerson = "person" +!endprocedure + +!procedure PERSON_SPRITE_C4() + !$defaultPerson = "personC4" +!endprocedure + +!procedure PERSON_SPRITE_3D() + !$defaultPerson = "person3D" +!endprocedure + +!procedure PERSON_SPRITE($person) + !$defaultPerson = $person +!endprocedure + ' Elements ' ################################## !function $getPerson($label, $descr, $sprite) +!if ($sprite == "") && ($defaultPerson!="") + !$sprite = $defaultPerson +!endif !if ($descr == "") && ($sprite == "") -!return '<$person>\n=='+$label + !return '=='+$label !endif !if ($descr == "") && ($sprite != "") -!return '<$'+$sprite+'>\n=='+$label + !return '<$'+$sprite+'>\n=='+$label !endif !if ($descr != "") && ($sprite == "") -!return '<$person>\n=='+$label+'\n\n '+$descr + !return '=='+$label+'\n\n '+$descr !endif !if ($descr != "") && ($sprite != "") -!return '<$'+$sprite+'>\n=='+$label+'\n\n '+$descr + !return '<$'+$sprite+'>\n=='+$label+'\n\n '+$descr !endif !endfunction diff --git a/LayoutOptions.md b/LayoutOptions.md index ec984e4..a2026b3 100644 --- a/LayoutOptions.md +++ b/LayoutOptions.md @@ -89,7 +89,7 @@ One thing which is often ignored is the fact, that these software architecture s Without any proof * if they are technically possible -* if they can fullfil all requirements +* if they can fulfill all requirements * if they keep what they promise More often these sketches are used by many people as facts and are manifested into their documentations. @@ -140,3 +140,123 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS") ![HIDE_STEREOTYPE Sample](https://www.plantuml.com/plantuml/png/NL1DIyD05BplhrZheIdKX8edJuqrMC5gQ5B5KzWcJxkmN-o-DHJnl_j2gnNtCl1ctfkPdGSK7gDMV7b_MpHLNQoBf_grB7Wbj5F0pgHfLUo0xn1TkCuoB_hqNU8kRcC0trg3O31jhSv4vwKm7ogwc2skBaeb36vM3vaI205fr2n8BQG1dpgoPEoVPp9Xh0GVh4b4fwMPyb4-e0pe1Le_ch1g7n1qSsEZwOJV9-rioiU7gEC9_sIStgzBqiEs4SxHdHVOyjmv9Lk1qfeHZHRdKvvNPVfOrBJYWL-cCxvwNWnShfJj0nyQ1ewMKpqdIAAZGabUlEub8dYEKeCYhq3Plexf4ZoGTESe8vAjGVsqEiNQ1DeaNDPrMP5g4FsofpDtW1IZXm7UlDL_L-PWElhCRm00 "HIDE_STEREOTYPE Sample") +## PERSON_SPRITE_NONE(), PERSON_SPRITE_ACTIVE(), PERSON_SPRITE_C4(), PERSON_SPRITE_3D() or PERSON_SPRITE($person) + +With the macros `PERSON_SPRITE_NONE()`, `PERSON_SPRITE_ACTIVE()`, `PERSON_SPRITE_C4()`, `PERSON_SPRITE_3D()` and `PERSON_SPRITE($person)` it is possible to easily change the person related default sprite. `PERSON_SPRITE_ACTIVE()` is the default. + +- **PERSON_SPRITE_NONE()**: deactivates the default sprite +- **PERSON_SPRITE_ACTIVE()**: (re-)activates the default sprite +- **PERSON_SPRITE_C4()**, **PERSON_SPRITE_3D()**: activates one of the other prepared sprites +- **PERSON_SPRITE($person)**: activates a customer specific sprite as default sprite + +**Using PERSON_SPRITE_ACTIVE()** + +```csharp +@startuml PERSON_SPRITE_ACTIVE Sample +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +/' Not needed because this is the default '/ +PERSON_SPRITE_ACTIVE() + +Person(admin, "Administrator") +System_Boundary(c1, 'Sample') { + Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines") +} +System(twitter, "Twitter") + +Rel(admin, web_app, "Uses", "HTTPS") +Rel(web_app, twitter, "Gets tweets from", "HTTPS") +@enduml +``` + +![PERSON_SPRITE_ACTIVE Sample](http://www.plantuml.com/plantuml/png/RL1DYzim4BthLqpJWnt8scpfgQTrZMaNkgc9lTkZaQr98z27aCQOKFhVEoPfqaDzUNZUnppDKo8PQRO6skRGVTyFNNjuxfkXglldjmOwQOD1yKwxoSmAuKGKqgUoZ78fVcewpUESC4xU4Jeg9c_BOAHRynuIAQF7ilxuqAwZrvTlfPM9CF9egDaXjSDO1DOAKMQmzmGEKQ624IV9kK0ddK0dHWI5HpaRWgmK_skQRuLeCIRlSgciTZlOL2lgH56IZvkjwCwytGwV_UoKZETyUjn1TdbWjeLV0lYxzSeN70SP0kVym16g48oU96dlDZogt--WwjfYt_HiYGWVYaTuUQjNhZB6BmdMkt1p3toK85bYkRtcNT0lcWWZaBPeU5VYRh-lxNAwa9npbJ4f3cZ-lkfUwpMna_5htxSTgrRHZRt7V45A_8ih7AEt_rgUq2a-_ny0 "PERSON_SPRITE_ACTIVE Sample") + + +**Using PERSON_SPRITE_NONE()** + +```csharp +@startuml PERSON_SPRITE_NONE Sample +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +PERSON_SPRITE_NONE() + +Person(admin, "Administrator") +System_Boundary(c1, 'Sample') { + Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines") +} +System(twitter, "Twitter") + +Rel(admin, web_app, "Uses", "HTTPS") +Rel(web_app, twitter, "Gets tweets from", "HTTPS") +@enduml +``` + +![PERSON_SPRITE_NONE Sample](http://www.plantuml.com/plantuml/png/PL1DYwD04BtxAsgpXnX8b2nxsbDSaTs5ZP5eTe_IQisaeJ-QxX89m_ptAKac6HWlXLNluxtU1HAUHgsWAexreMphwlYdAThoK1PG2-qKHb-awTKu89o9NFYHfbvCoREayzYD0Nrl3Q6XfBSwTKgOMMqJQ52oI_FlcsfUdVP_Koq2eUTLcpD3I8C-SOoDei_MyOgtw8CriHYqD6jOPFEKWRmWwnUhgBwmd6v_sj4Cmb_YVhk6vJNnSWKl4V1tDuedx5hX7ElynmuovvJi1Kbh5hpAlwuXgwkaB1gcU8HloHRs__BvbYbbfm1pqG1aWLiwmH0zAfBi1SqaYNi1IOsAlG9dUxsbY-bwP9qRZ8_H4TLxgqUiKs0cpzzDKzMCca7twqFc5rBWNvp7axVw8sM7Pk3tV0C0 "PERSON_SPRITE_NONE Sample") + +**Using PERSON_SPRITE_C4()** + +```csharp +@startuml PERSON_SPRITE_C4 Sample +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +PERSON_SPRITE_C4() + +Person(admin, "Administrator") +System_Boundary(c1, 'Sample') { + Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines") +} +System(twitter, "Twitter") + +Rel(admin, web_app, "Uses", "HTTPS") +Rel(web_app, twitter, "Gets tweets from", "HTTPS") +@enduml +``` + +![PERSON_SPRITE_C4 Sample](http://www.plantuml.com/plantuml/png/NL1DIyD04BtdLupnq0JQX4fFdXf3KS7MqAHw39jajGlxiUnE24NyxyvIjM8kGsRUntkxziWSZaf2jTdNpxkshlQFpQOjLr0pPIMFheJkvJXmE29QVvldZatPky3Zs8sUkzvev1gptgZSIgQ3riBZ84MNbwj55LQ7xLEkc4VkQDMMn612SvTPmaRHV-CafHrttkY43KheESH5cCAZOsXSd4RrYSHKUsT6FJ1tIlhb76RdlBCKFYAWxzSccNZNCcj9vvLtK5WhHSzG61tJghoUGr5NsMxJ4CLnkCcMi7qfmwsGqamUGaqFQ80wMaOGDKeKv0ND991Q0Gh59NbvolRvdIx1yv5qph0GFDfp-TFg4klWYKdpeMcgEau3w1Bw8dFFqTCl3-FD6VMNikPw2A_v1G00 "PERSON_SPRITE_C4 Sample") + +**Using PERSON_SPRITE_3D()** + +```csharp +@startuml PERSON_SPRITE_3D Sample +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +PERSON_SPRITE_3D() + +Person(admin, "Administrator") +System_Boundary(c1, 'Sample') { + Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines") +} +System(twitter, "Twitter") + +Rel(admin, web_app, "Uses", "HTTPS") +Rel(web_app, twitter, "Gets tweets from", "HTTPS") +@enduml +``` + +![PERSON_SPRITE_3D Sample](http://www.plantuml.com/plantuml/png/NL1DRzf04BtxLqpf0IE1BTgUUi9rKLkfK0kRvcYjxKbOQJzMksDPACf_pwmW4CMNaUTzl3Ux2IGyZLf1jJtK__PjNHt-DDlswq-eXNOAaq_Iz6eS44v4BdpFSo-cx4dIQUp6WBwtXj1GrbkTEoLCz5e56fJiylBRgeghu-vlhaKWzBngIrO8QT1dZhb9yZ4uNV0EVR0c5OEMPWcp8auPo0koVhP8wZERwVQ77SqW_3djrqkON_hE5_2S07-tc7J2hXNEiSy3Tb0ufsGlI5epurNvUGb5NMNxRSCIZ_0bMyFkVncnGYax1OXd1Y0BVACJJD6Z8ibPq4oI23sGrAWuAt2tbskxb2uW-rnf32O7L6zNtMiT0ojv_cwQgcPM9DtGkyqlfC2_6CUZj_gzP8DcYA_v2W00 "PERSON_SPRITE_3D Sample") + +**Using PERSON_SPRITE($person)** + +```csharp +@startuml PERSON_SPRITE Sample +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +!define osaPuml https://raw.githubusercontent.com/Crashedmind/PlantUML-opensecurityarchitecture2-icons/master +!include osaPuml/Common.puml +!include osaPuml/User/all.puml + +PERSON_SPRITE("osa_user_green_operations") + +Person(admin, "Administrator") +System_Boundary(c1, 'Sample') { + Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines") +} +System(twitter, "Twitter") + +Rel(admin, web_app, "Uses", "HTTPS") +Rel(web_app, twitter, "Gets tweets from", "HTTPS") +@enduml +``` + +![PERSON_SPRITE Sample](http://www.plantuml.com/plantuml/png/ZP1FRzD04CNl-HJJSAWh9RPQSU94i290eiMANJXQ6tlQhBH_LZDZHH7YkpDBt0R41L-idNapxpVlFOiXcRo3PhjhlpxqRRFxt6sXDJuvN5pPCBXfH3Y897vNLMIEvRELmxIV66c8GJ18EKHV9MT2NhHc6PtTL_NRTPDBZ_TVAczOaBJKrpfXR40gaseNYwiHd_G9aKsZXV_mgSdm0KTlmrYz6AnZmi0uJ6JbP6WuMC519iAxjTLPdW4kvynsLHszZ-7Cya_paPNPE3UZ_XLGiLHLdzdwPq8ClHAG4QjconlL8d4CXScOArXkyj-og2AIzjkJulZ-Gvp2QEXK3BShk3v7Vdq3FnQWtsjInH7tlKb9ztp7FMnISdRuRRNKKlrc1PksAH-sdOuGmbrv2_VVwjpRE1UF39cIGI9eVCcen4zEh7f1TxGYI23MerElpFvpfYlatDGziomVjaFtSjK5IuFYxFUfwvfMLLdqshsi-OZ2-iJyUwBe_npv1G00 "PERSON_SPRITE Sample") + diff --git a/README.md b/README.md index 8cddaa4..14587c6 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ At the top of your C4 PlantUML `.puml` file, you need to include the `C4_Context To be independent of any internet connectivity, you can also download the files found in the `root` and reference it locally with -```c# +```csharp !include path/to/C4.puml !include path/to/C4_Context.puml !include path/to/C4_Container.puml @@ -31,7 +31,7 @@ Just remember to change the `!include` statements at the top of the files. If you want to use the always up-to-date version in this repo, use the following: -```c# +```csharp !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml ``` @@ -76,7 +76,7 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS") Entities can also be decorated with icons using the last parameter, for example: -```cs +```csharp @startuml !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml @@ -110,6 +110,11 @@ Diagram types * System Context & System Landscape diagrams * Import: `!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml` * Macros: + * `PERSON_SPRITE_NONE()` + * `PERSON_SPRITE_ACTIVE()` + * `PERSON_SPRITE_C4()` + * `PERSON_SPRITE_3D()` + * `PERSON_SPRITE($person)` * `Person(alias, label, ?description, ?sprite)` * `Person_Ext` * `System(alias, label, ?description, ?sprite)` @@ -165,13 +170,21 @@ In rare cases, you can force the layout using hidden relationships, `Lay_U`, `La ## Layout Options -C4-PlantUML also comes with some layout options to make it easy and reuseable to create nice and useful diagrams: +C4-PlantUML also comes with some layout options to make it easy and reusable to create nice and useful diagrams: * [LAYOUT_TOP_DOWN() or LAYOUT_LEFT_RIGHT()](LayoutOptions.md#layout_top_down-or-layout_left_right) * [LAYOUT_WITH_LEGEND()](LayoutOptions.md#layout_with_legend) * [LAYOUT_AS_SKETCH()](LayoutOptions.md#layout_as_sketch) * [HIDE_STEREOTYPE()](LayoutOptions.md#hide_stereotype) +C4-PlantUML also comes with some default person sprite options: + +* [PERSON_SPRITE_NONE()](LayoutOptions.md#person_sprite_none) +* [PERSON_SPRITE_ACTIVE()](LayoutOptions.md#person_sprite_active) +* [PERSON_SPRITE_C4()](LayoutOptions.md#person_sprite_c4) +* [PERSON_SPRITE_3D()](LayoutOptions.md#person_sprite_3d) +* [PERSON_SPRITE($person)](LayoutOptions.md#person_sprite) + ## Snippets for Visual Studio Code Because the PlantUML support inside of Visual Studio Code is excellent with the [PlantUML extension](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml), you can also find VS Code snippets for C4-PlantUML at [.vscode/C4.code-snippets](.vscode/C4.code-snippets).