Should we reduce legend text width with line, border style symbols (instead of text)? #232

kirchsth · 2022-08-21T13:50:23Z

Atm we have a lot of different line, border and shape styles and the legend text can be very wide like below

(@Potherca:) Should we uses symbols that the legend size is reduced, like below?

The disadvantage could be that the symbols are not clear for everybody.

I found no useful color alternatives for "transparent", "no text color", "no back(ground) color" and "no line color" therefore this would remain unchanged atm. In most of the cases the e.g. "no text color" can be avoided at all (as soon a concrete color is defined).

Second question: should I remove (border) "transparent" from the legend at all?

Thank you and best regards
Helmut

PS.: source of the samples

@startuml
' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally
!if %variable_exists("RELATIVE_INCLUDE")
  !include ./../C4_Container.puml
!else
  !include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Container.puml
!endif

''''' THIS SECTION ACTIVATES THE NEW SYMBOLS (deactivate it and you get the orig. design back)  
!global $LEGEND_SHADOW_TEXT = "(<$shadowSprite>) "
!global $LEGEND_NO_SHADOW_TEXT = "(no <$shadowSprite>) "
!global $LEGEND_ROUNDED_BOX = "(<$roundCornerSprite>) "
!global $LEGEND_EIGHT_SIDED = "(<$cutCornerSprite>) "
' http://unicode-search.net/unicode-namesearch.pl
!global $LEGEND_DOTTED_LINE = "(<U+250A>) "
!global $LEGEND_DASHED_LINE = "(<U+254E>) "
!global $LEGEND_BOLD_LINE = "(<U+2503>) "
!global $LEGEND_DASHED_BOUNDARY = "boundary (<U+254E>) "
!global $LEGEND_DASHED_TRANSPARENT_BOUNDARY = "boundary (<U+254E>, transparent) "
''''' END OF SECTION

SHOW_PERSON_OUTLINE()
' Tags support no spaces in the name (based on the underlining stereotypes, which don't support spaces anymore). 
' If spaces are requested in the legend, legend text with space has to be defined
AddElementTag("backendContainer", $fontColor=$ELEMENT_FONT_COLOR, $bgColor="#335DA5", $shape=EightSidedShape(), $shadowing="true")
AddRelTag("async", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DashedLine())
AddRelTag("sync/async", $textColor=$ARROW_COLOR, $lineColor=$ARROW_COLOR, $lineStyle=DottedLine())
UpdateSystemBoundaryStyle()
UpdateElementStyle("external_system", $EXTERNAL_SYSTEM_BG_COLOR, $ELEMENT_FONT_COLOR, $EXTERNAL_SYSTEM_BORDER_COLOR, $shape=RoundedBoxShape())

sprite $roundCornerSprite [16x16/16] {
0000000000000000
0000000007BEFFF0
0000000AFA631000
000005FC20000000
00007F7000000000
0005F30000000000
002F700000000000
00AB000000000000
02F2000000000000
07A0000000000000
0B60000000000000
0E30000000000000
0F10000000000000
0F00000000000000
0F00000000000000
0000000000000000
}

sprite $cutCornerSprite [16x16/16] {
0000000000000000
0000000004EFFFF0
000000004E400000
00000004E4000000
0000004E40000000
000004E400000000
00004E4000000000
0004E40000000000
004E400000000000
04E4000000000000
0E40000000000000
0F00000000000000
0F00000000000000
0F00000000000000
0F00000000000000
0000000000000000
}

sprite $shadowSprite [16x16/16] {
0000000000000000
00000000000F0000
00000000000FA000
00000000000FA800
00000000000FA800
00000000000FA800
00000000000FA800
00000000000FA800
00000000000FA800
00000000000FA800
00000000000FA800
00000000000FA800
0FFFFFFFFFFFA800
00AAAAAAAAAAA400
0008888888888800
0000000000000000
}

title Container diagram for Internet Banking System

Person(customer, Customer, "A customer of the bank, with personal bank accounts")

System_Boundary(c1, "Internet Banking") {
    Container(web_app, "Web Application", "Java, Spring MVC", "Delivers the static content and the Internet banking SPA")
    Container(spa, "Single-Page App", "JavaScript, Angular", "Provides all the Internet banking functionality to cutomers via their web browser")
    Container(mobile_app, "Mobile App", "C#, Xamarin", "Provides a limited subset of the Internet banking functionality to customers via their mobile device")
    ContainerDb(database, "Database", "SQL Database", "Stores user registration information, hashed auth credentials, access logs, etc.")
    Container(backend_api, "API Application", "Java, Docker Container", "Provides Internet banking functionality via API", $tags="backendContainer")
}

System_Ext(email_system, "E-Mail System", "The internal Microsoft Exchange system")
System_Ext(banking_system, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

Rel(customer, web_app, "Uses", "HTTPS")
Rel(customer, spa, "Uses", "HTTPS")
Rel(customer, mobile_app, "Uses")

Rel_Neighbor(web_app, spa, "Delivers")
Rel(spa, backend_api, "Uses", "async, JSON/HTTPS", $tags="async")
Rel(mobile_app, backend_api, "Uses", "async, JSON/HTTPS", $tags="async")
Rel_Back_Neighbor(database, backend_api, "Reads from and writes to", "sync, JDBC")

Rel_Back(customer, email_system, "Sends e-mails to")
Rel_Back(email_system, backend_api, "Sends e-mails using", "sync, SMTP")
Rel_Neighbor(backend_api, banking_system, "Uses", "sync/async, XML/HTTPS", $tags="sync/async")

SHOW_LEGEND()
footer drawn with PlantUML v. %version() and C4-PlantUML v. C4Version()
@enduml

Potherca · 2022-08-21T15:49:28Z

Usually I am not a big fan of replacing information with symbols. It might be clear to the author of the diagram but most likely not to other people.

Before I can really comment, I would need to better understand why it is an issue that the legend can become rather wide...

Looking only at the legend:

If the transparent is removed, things could also be made less wide by using a smaller font for the additional information:

The shortest it could be is this:

If the user is willing to gain a shorter legend by losing some meaning, that would be easy enough to achieve.

kirchsth · 2022-08-21T22:20:25Z

I like the idea with the smaller size.

I could make following changes:

The user can define the legend text without the additional information via a new $label=... parameter of the Add...Tag()/Update..Style() calls (as an alternative to $legendText).

And if $label is defined then it will be combined with the (calculated) additional information.
This has the advantage that no (calculated) additional information has to be added to $legendText anymore.

E.g. AddElementTag("backendContainer", ... , $legendText = "backend container (shadowed) (eight sided)" ) and
AddElementTag("backendContainer", ... , $label = "backend container" ) produce the same output.

add to SHOW_LEGEND() and SHOW_FLOATING_LEGEND() a $showStyle(?) parameter with the options "none", "normal", "small", "symbol"(?)
The $showStyle(?) parameter requires a tag definition with $label (and if $label is defined then the default is small)

source

@startuml
skinparam LegendBorderColor transparent
skinparam LegendBackgroundColor transparent
skinparam LegendFontColor #FFFFFF

skinparam shadowing<<legendArea>> false
skinparam rectangle<<legendArea>> {
    backgroundcolor #00000000
    bordercolor #00000000
}

sprite $roundCornerSprite [16x16/16] {
0000000000000000
0000000007BEFFF0
0000000AFA631000
000005FC20000000
00007F7000000000
0005F30000000000
002F700000000000
00AB000000000000
02F2000000000000
07A0000000000000
0B60000000000000
0E30000000000000
0F10000000000000
0F00000000000000
0F00000000000000
0000000000000000
}

sprite $cutCornerSprite [16x16/16] {
0000000000000000
00004EFFFFE40000
0004E400004E4000
004E40000004E400
04E4000000004E40
0E400000000004E0
0F000000000000F0
0F000000000000F0
0F000000000000F0
0E400000000004E0
04E4000000004E40
004E40000004E400
0004E400004E4000
00004EFFFFE40000
0000000000000000
}

sprite $shadowSprite [16x16/16] {
0000000000000000
00000000000F0000
00000000000FA000
00000000000FA800
00000000000FA840
00000000000FA840
00000000000FA840
00000000000FA840
00000000000FA840
00000000000FA840
00000000000FA840
0FFFFFFFFFFFA840
00AAAAAAAAAAA840
0008888888888840
0000444444444440
0000000000000000
}

legend right
<#00000000,#00000000>|<color:#000000>**Legend**</color> |
| |
|<#335DA5><color:#335DA5> <U+25AF></color> <color:#FFFFFF> backend container (eight sided, shadow) </color> |
| |
|<#335DA5><color:#335DA5> <U+25AF></color> <color:#FFFFFF> backend container <size:9>(eight sided, shadow)</size> </color> |
| |
|<#335DA5><color:#335DA5> <U+25AF></color> <color:#FFFFFF> backend container (<$cutCornerSprite>, <$shadowSprite>) </color> |
| |
|<#335DA5><color:#335DA5> <U+25AF></color> <color:#FFFFFF> backend container </color> |
| |
endlegend
@enduml

remove "transparent" (which is basically only a specific color like white and white is not displayed too) from boundary that we avoid a legend like

What do you think?
And do you have a better name for showStyle?

Thank you and best regards
Helmut

Potherca · 2022-08-26T11:03:02Z

The user can define the legend text via a new $label=... parameter

Sounds good.

add to SHOW_LEGEND() and SHOW_FLOATING_LEGEND() a $showStyle(?) parameter

Also good.

remove "transparent" from boundary

Also good.

do you have a better name for showStyle?

Naming a thing is always a bit tricky.

What does the parameter do or represents to a user? 🤔

It doesn't really have to do with "style" as much as information representation. It gives the user an option to change how secondary information is display in the legend. $legendSecondaryInformationDisplayMethod is a bit verbose but it also doesn't fell "right".

For the user the information has meaning. That meaning is not "secondary" but is part of how they can identify items of a specific type.

$legendTypeDisplay is better but not there yet. Currently, I do not have a better suggestion yet.

Looking at the values "none", "normal", "small", "symbol" I think "symbol" might be "pictogram"? Also not sure yet.

Potherca · 2022-10-23T19:28:35Z

Regarding

do you have a better name for showStyle?

and

$legendTypeDisplay is better but not there yet.

Currently, I am oscilating between "shapeDescription" and "legendVerbosity" or something like that.

kirchsth · 2022-10-23T19:58:50Z

I wouldn't use verbosity because normal and small displays the same information.
We could call it "(legend)Layout" or something like this.
I don't like the current no color implementation too;
1. text is long and not 100% clear
2. the used colors
  but I have no better idea atm

PS.: I'm not sure if I implement the pictograms at all (only none, normal and small)

without the pictogram I can implement it via the font size (0..none) and I'm finished
and your argument that a pictograms is not so clear is correct
Atm I have no preference, and therefore I think this will be the last of my 2.5.0 issues ;-)

Potherca · 2022-10-25T08:28:59Z

I think "legendLayout" is a good description. Lets go with that.

Skipping pictograms sounds like a good plan. Only having "none", "normal" and "small" is good enough.

As to "no-color", I have no clear solution. I guess an unsatisfactory solution is still better than no solution. 🤷

Potherca · 2022-11-06T10:25:29Z

@kirchsth Do you want this to be part of v2.5 or should we bump it to v2.6?

kirchsth · 2022-11-07T17:42:35Z

please wait

…or None(); defined via SHOW_LEGEND($details=...) - if $legendText contains a `\n` then the part before is the label and the part behind the details

…ned via SHOW_LEGEND($details=...) - if $legendText contains a `\n` then the part before is the label and the part behind the details

Potherca changed the title ~~Should we reduce license text width with line, border style symbols (instead of text)?~~ Should we reduce legend text width with line, border style symbols (instead of text)? Aug 21, 2022

Potherca moved this to In Progress in All Projects Aug 21, 2022

Potherca added this to All Projects Aug 21, 2022

kirchsth self-assigned this Sep 7, 2022

kirchsth mentioned this issue Oct 22, 2022

Release v2.5.0 🎉 #248

Closed

7 tasks

Potherca added this to the v2.5.0 milestone Oct 23, 2022

kirchsth mentioned this issue Nov 1, 2022

Add support for lineThickness in AddRelTag #235

Closed

kirchsth added a commit to kirchsth/C4-PlantUML that referenced this issue Nov 12, 2022

plantuml-stdlib#232 Legend details (2 - fix tests)

69224ed

kirchsth mentioned this issue Nov 12, 2022

#232 Legend details can be smaller or hidden #259

Merged

kirchsth linked a pull request Nov 12, 2022 that will close this issue

#232 Legend details can be smaller or hidden #259

Merged

kirchsth closed this as completed in #259 Nov 14, 2022

Repository owner moved this from In Progress to Done in All Projects Nov 14, 2022

kirchsth added a commit that referenced this issue Nov 14, 2022

#232 Legend details can be Small()==default, Normal() or None(); defi…

e68bf9d

…ned via SHOW_LEGEND($details=...) - if $legendText contains a `\n` then the part before is the label and the part behind the details

kirchsth added a commit that referenced this issue Nov 14, 2022

#232 Legend details (2 - fix tests)

f1aa60f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Should we reduce legend text width with line, border style symbols (instead of text)? #232

Should we reduce legend text width with line, border style symbols (instead of text)? #232

kirchsth commented Aug 21, 2022 •

edited by Potherca

Loading

Potherca commented Aug 21, 2022

kirchsth commented Aug 21, 2022

Potherca commented Aug 26, 2022

Potherca commented Oct 23, 2022

kirchsth commented Oct 23, 2022

Potherca commented Oct 25, 2022

Potherca commented Nov 6, 2022

kirchsth commented Nov 7, 2022

Should we reduce legend text width with line, border style symbols (instead of text)? #232

Should we reduce legend text width with line, border style symbols (instead of text)? #232

Comments

kirchsth commented Aug 21, 2022 • edited by Potherca Loading

Potherca commented Aug 21, 2022

kirchsth commented Aug 21, 2022

Potherca commented Aug 26, 2022

Potherca commented Oct 23, 2022

kirchsth commented Oct 23, 2022

Potherca commented Oct 25, 2022

Potherca commented Nov 6, 2022

kirchsth commented Nov 7, 2022

kirchsth commented Aug 21, 2022 •

edited by Potherca

Loading