mirror of
https://github.com/plantuml-stdlib/C4-PlantUML.git
synced 2022-10-18 01:14:54 +00:00
#219 Update Readme.md (add sprite section, a diagram with BiRel() calls and unify relation to relationship)
This commit is contained in:
KIRCHSTH
@@ -122,7 +122,7 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS", $link="https://plantuml.com/l
|
||||
|
||||
|
||||
|
||||
Elements and relations can be decorated with tags and explained via a calculated legend, for example:
|
||||
Elements and relationships can be decorated with tags and explained via a calculated legend, for example:
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
@@ -231,56 +231,40 @@ You can force the direction of a relationship by using:
|
||||
* `Rel_L`, `Rel_Left`
|
||||
* `Rel_R`, `Rel_Right`
|
||||
|
||||
Relationship specific sprites are typically smaller and therefore following options are possible:
|
||||
* use smaller icons (like the $triangle in the following sample)
|
||||
* use an additional scale factor (direct as part of the argument, or via a variable)
|
||||
* if sprite argument starts with `&` an OpenIconic name can be used too (details see https://useiconic.com/open)
|
||||
In following sample a person uses different systems, and a group of persons which have bidirectional relationships
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
|
||||
HIDE_STEREOTYPE()
|
||||
|
||||
Person(user, "User")
|
||||
Person(user1, "User 1")
|
||||
Person(user2, "User 2")
|
||||
Person(user3, "User 3")
|
||||
Person(a, "A")
|
||||
Person(b, "B")
|
||||
Person(c, "C")
|
||||
Person(d, "D")
|
||||
Person(e, "E")
|
||||
|
||||
System(system, "System")
|
||||
BiRel_U(a, b, "talk with")
|
||||
BiRel_R(a, c, "talk with")
|
||||
BiRel_D(a, d, "talk with")
|
||||
BiRel_L(a, e, "talk with")
|
||||
|
||||
' normal sprites are too big
|
||||
Rel_L(user, user2, "informs", "courier", "normal sprites are too big", $sprite="person2")
|
||||
Person(x, "X")
|
||||
System(s1, "S1")
|
||||
System(s2, "S2")
|
||||
System(s3, "S3")
|
||||
System(s4, "S4")
|
||||
|
||||
' scaled sprites are ok
|
||||
Rel_R(user, user3, "informs", "courier", "scaled sprites are OK", $sprite="person2,scale=0.5")
|
||||
|
||||
' combine sprite and scale to a new sprite
|
||||
!$combinedSprite="person2,scale=0.5"
|
||||
Rel_R(user, user3, "informs", "courier", "combined sprites are OK", $sprite=$combinedSprite)
|
||||
|
||||
|
||||
' special smaller sprites can be used
|
||||
sprite $triangle {
|
||||
00000000000
|
||||
00000F00000
|
||||
0000FBF0000
|
||||
0000FBF0000
|
||||
000F999F000
|
||||
000F999F000
|
||||
00F66666F00
|
||||
00F66666F00
|
||||
0F3333333F0
|
||||
0F3333333F0
|
||||
0FFFFFFFFF0
|
||||
00000000000
|
||||
}
|
||||
Rel_R(user1, system, "orders", "http", "small sprites, like the small triangle", $sprite="triangle")
|
||||
|
||||
' if sprite starts with &, sprite defines a OpenIconic, details see https://useiconic.com/open/
|
||||
Rel_D(user, user1, "requests", "async message", "if sprite starts with &, it defines a OpenIconic like &envelope-closed", $sprite = "&envelope-closed")
|
||||
Rel_U(x, s1, "uses")
|
||||
Rel_R(x, s2, "uses")
|
||||
Rel_D(x, s3, "uses")
|
||||
Rel_L(x, s4, "uses")
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## Layout (arrange) elements (without relationships)
|
||||
|
||||
In rare cases, you can force the layout of elements which have no relationships by using:
|
||||
|
||||
@@ -289,7 +273,7 @@ In rare cases, you can force the layout of elements which have no relationships
|
||||
* `Lay_L(from, to)`, `Lay_Left(from, to)`
|
||||
* `Lay_R(from, to)`, `Lay_Right(from, to)`
|
||||
|
||||
In following sample a person uses different systems, and group of persons which have no relations
|
||||
In following sample a person uses different systems, and a group of persons which have no relationships
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
@@ -320,7 +304,7 @@ Rel_L(x, s4, "uses")
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
(In combination with [SHOW_FLOATING_LEGEND()](LayoutOptions.md#show_floating_legend)) a greater distance between an element and the
|
||||
e.g. floating legend could be required that all e.g. corners of the drawing area can be reached.
|
||||
@@ -357,7 +341,7 @@ Lay_Distance(LEGEND(), db, 1)
|
||||
|
||||
|
||||
|
||||
## Layout Options
|
||||
## Global Layout Options
|
||||
|
||||
C4-PlantUML also comes with some layout options to make it easy and reusable to create nice and useful diagrams:
|
||||
|
||||
@@ -374,6 +358,95 @@ C4-PlantUML also comes with some person sprite/portrait options:
|
||||
* [SHOW_PERSON_PORTRAIT()](LayoutOptions.md#show_person_portrait)
|
||||
* [SHOW_PERSON_OUTLINE()](LayoutOptions.md#show_person_outline) (requires PlantUML version >= 1.2021.4)
|
||||
|
||||
## Sprites and other images
|
||||
|
||||
`$sprite` (images) can be defined with following PlantUML supported options:
|
||||
|
||||
* included (standard library) sprites via their `{SpriteName}`; details see [sprites](https://plantuml.com/sprite)
|
||||
* images via `img:{File or Url}`
|
||||
* OpenIconic via `&{OpenIconicName}`; details see [openiconic](https://plantuml.com/openiconic)
|
||||
|
||||
Size of the displayed images can be changed with `,scale={factor}`.
|
||||
Color of the displayed images can be changed with `,color={color} `.
|
||||
|
||||
(If sprites are defined via $tags then the calculated legend is updated too)
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
'stdlib users.puml defines sprite "users"
|
||||
!include <office/users/users.puml>
|
||||
|
||||
|
||||
AddRelTag("plantuml", $textColor="$ARROW_COLOR", $lineColor="$ARROW_COLOR", $sprite="img:http://plantuml.com/logo3.png{scale=0.3}", $legendSprite="img:http://plantuml.com/logo3.png{scale=0.1}", $legendText="console triggered")
|
||||
|
||||
Person(user, "user group displayed with a sprite", $sprite="users")
|
||||
|
||||
|
||||
Container(container, "Container with scaled and colored OpenIconic", $sprite="&folder,scale=5.0,color=gray")
|
||||
|
||||
System(system, "System with an image", $sprite="img:http://plantuml.com/logo3.png")
|
||||
|
||||
Rel(user, system, "Rel with image (via tags)", $tags="plantuml")
|
||||
Rel(user, container, "Rel with OpenIconinc", $sprite="&folder")
|
||||
|
||||
SHOW_LEGEND()
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
|
||||
Relationship specific sprites are typically smaller and therefore following options are possible:
|
||||
* use smaller icons (like the $triangle in the following sample)
|
||||
* use an additional scale factor (direct as part of the argument, or via a variable)
|
||||
* if sprite argument starts with `&` an OpenIconic name can be used too (details see https://useiconic.com/open)
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
|
||||
|
||||
Person(user, "User")
|
||||
Person(user1, "User 1")
|
||||
Person(user2, "User 2")
|
||||
Person(user3, "User 3")
|
||||
|
||||
System(system, "System")
|
||||
|
||||
' normal sprites are too big
|
||||
Rel_L(user, user2, "informs", "courier", "normal sprites are too big", $sprite="person2")
|
||||
|
||||
' scaled sprites are ok
|
||||
Rel_R(user, user3, "informs", "courier", "scaled sprites are OK", $sprite="person2,scale=0.5")
|
||||
|
||||
' combine sprite and scale to a new sprite
|
||||
!$combinedSprite="person2,scale=0.5"
|
||||
Rel_R(user, user3, "informs", "courier", "combined sprites are OK", $sprite=$combinedSprite)
|
||||
|
||||
' special smaller sprites can be used
|
||||
sprite $triangle {
|
||||
00000000000
|
||||
00000F00000
|
||||
0000FBF0000
|
||||
0000FBF0000
|
||||
000F999F000
|
||||
000F999F000
|
||||
00F66666F00
|
||||
00F66666F00
|
||||
0F3333333F0
|
||||
0F3333333F0
|
||||
0FFFFFFFFF0
|
||||
00000000000
|
||||
}
|
||||
Rel_R(user1, system, "orders", "http", "small sprites, like the small triangle", $sprite="triangle")
|
||||
|
||||
' if sprite starts with &, sprite defines a OpenIconic, details see https://useiconic.com/open/
|
||||
Rel_D(user, user1, "requests", "async message", "if sprite starts with &, it defines a OpenIconic like &envelope-closed", $sprite = "&envelope-closed")
|
||||
@enduml
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Custom tags/stereotypes support and skinparam updates
|
||||
|
||||
Additional tags/stereotypes can be added to the existing element stereotypes (component, ...) and highlight,... specific aspects:
|
||||
@@ -381,7 +454,7 @@ Additional tags/stereotypes can be added to the existing element stereotypes (co
|
||||
* `AddElementTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite)`:
|
||||
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)`:
|
||||
Introduces a new relation tag. The styles of the tagged relations are updated and the tag is displayed in the calculated legend.
|
||||
Introduces a new Relationship tag. The styles of the tagged relationships are updated and the tag is displayed in the calculated legend.
|
||||
* `UpdateElementStyle(elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite)`:
|
||||
This call updates the default style of the elements (component, ...) and creates no additional legend entry.
|
||||
* `UpdateRelStyle(textColor, lineColor)`:
|
||||
@@ -425,7 +498,7 @@ Following calls introduces new element tags with element specific default colors
|
||||
* `SHOW_LEGEND()` has to be last line in diagram.
|
||||
* Don't use space between `$tags` and `=` (PlantUML does not support it).
|
||||
* Don't use `,` as part of the tag names (PlantUML does not support it in combination with keyword arguments).
|
||||
* If 2 tags defines the same skinparam, the first definition is used.
|
||||
* If 2 tags define the same skinparam, the first definition is used.
|
||||
* If specific skinparams have to be merged (e.g. 2 tags change the font color) an additional combined tag has to be defined. Use `&` as part of combined tag names.
|
||||
|
||||
* Colors of relationship tags cannot be automatically merged (PlantUML does not support it).
|
||||
@@ -579,7 +652,7 @@ SHOW_LEGEND()
|
||||
|
||||
|
||||
|
||||
## Element and Relation properties
|
||||
## Element and Relationship properties
|
||||
|
||||
A model can be extended with (a table of) properties that concrete deployments or more detailed concepts can be documented:
|
||||
|
||||
@@ -615,7 +688,7 @@ Deployment_Node_L(nodeAlias, "Label", "Optional Type", "Optional Description (wi
|
||||
|
||||
System(systemAlias, "Label", "Optional Description (without properties)")
|
||||
|
||||
' starting with v.2.5.0 relations support properties too
|
||||
' starting with v.2.5.0 relationships support properties too
|
||||
WithoutPropertyHeader()
|
||||
AddProperty("PropC1", "ValueC1")
|
||||
AddProperty("PropC2", "ValueC2")
|
||||
|
||||
Reference in New Issue
Block a user