Enables theme support - Githubissues

kirchsth commented 1 year ago

related to #245 and #291,

C4-PlantUML is prepared that themes can be used (all internal variables are only set, if they are not defined in an e.g. theme). This enables custom themes like below

@startuml
!theme C4_FirstTest from https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/themes
!include https://raw.githubusercontent.com/kirchsth/C4-PlantUML/extended/C4_Component.puml

Person_Ext(customer, "Customer", "A customer of Widgets Limited.")

Enterprise_Boundary(c0, "Widgets Limited") {
    Person(csa, "Customer Service Agent", "Deals with customer enquiries.")
    System(ecommerce, "E-commerce System", "Allows customers to buy widgts online via the widgets.com website.")
    System(fulfilment, "Fulfilment System", "Responsible for processing and shipping of customer orders.")
}

System_Ext(taxamo, "Taxamo", "Calculates local tax (for EU B2B customers) and acts as a front-end for Braintree Payments.")
System_Ext(braintree, "Braintree Payments", "Processes credit card payments on behalf of Widgets Limited.")
System_Ext(post, "Jersey Post", "Calculates worldwide shipping costs for packages.")

Rel_R(customer, csa, "Asks questions to", "Telephone")
Rel_R(customer, ecommerce, "Places orders for widgets using")
Rel(csa, ecommerce, "Looks up order information using")
Rel_R(ecommerce, fulfilment, "Sends order information to")
Rel_D(fulfilment, post, "Gets shipping charges from")
Rel_D(ecommerce, taxamo, "Delegates credit card processing to")
Rel_L(taxamo, braintree, "Uses for credit card processing")
Lay_D(customer, braintree)

SHOW_LEGEND()
@enduml

Theme sample

The sample theme C4_FirstTest is stored in the themes folder.

The list of all changeable variables is documented in the Themes.md.

The MR is basically full working (it can be checked via my extended branch), but atm the documentation is not finished and I have no useful theme therefore it is a draft.

@Potherca, @manonmichel, @ProtoSlayer: it should fix #245 and #291. Can you please check if everything is OK or if I have missed something.

AND if you have a nice theme (best case based on an existing theme) maybe you want to publish it that it can be included.

BR Helmut

kirchsth commented 1 year ago

Another open question is the integration in the stdlib, details see https://forum.plantuml.net/17601/how-where-should-integrate-themes-into-the-plantuml-stdlib

Potherca commented 1 year ago

Should we do "something" regarding defaults? I was looking at the current default settings:

Name	Size
LEGEND_DETAILS_SMALL_SIZE	10
ARROW_FONT_SIZE	12
STEREOTYPE_FONT_SIZE	12
TECHN_FONT_SIZE	12
LEGEND_DETAILS_NORMAL_SIZE	14
EIGHT_SIDED_SIZE	18
ROUNDED_BOX_SIZE	25

Name	Color
COMPONENT_FONT_COLOR	`#000000`
LEGEND_TITLE_COLOR	`#000000`
NODE_FONT_COLOR	`#000000`
PERSON_BORDER_COLOR	`#073B6F`
PERSON_BG_COLOR	`#08427B`
SYSTEM_BG_COLOR	`#1168BD`
CONTAINER_BORDER_COLOR	`#3C7FC0`
SYSTEM_BORDER_COLOR	`#3C7FC0`
CONTAINER_BG_COLOR	`#438DD5`
BOUNDARY_COLOR	`#444444`
LEGEND_DARK_COLOR	`#66622E`
ARROW_COLOR	`#666666`
EXTERNAL_PERSON_BG_COLOR	`#686868`
COMPONENT_BORDER_COLOR	`#78A8D8`
COMPONENT_BG_COLOR	`#85BBF0`
EXTERNAL_PERSON_BORDER_COLOR	`#8A8A8A`
EXTERNAL_SYSTEM_BORDER_COLOR	`#8A8A8A`
EXTERNAL_SYSTEM_BG_COLOR	`#999999`
NODE_BORDER_COLOR	`#A2A2A2`
EXTERNAL_CONTAINER_BORDER_COLOR	`#A6A6A6`
EXTERNAL_CONTAINER_BG_COLOR	`#B3B3B3`
EXTERNAL_COMPONENT_BORDER_COLOR	`#BFBFBF`
EXTERNAL_COMPONENT_BG_COLOR	`#CCCCCC`
SKETCH_BG_COLOR	`#EEEBDC`
ELEMENT_FONT_COLOR	`#FFFFFF`
LEGEND_FONT_COLOR	`#FFFFFF`
NODE_BG_COLOR	`#FFFFFF`
SKETCH_WARNING_COLOR	red
BOUNDARY_BG_COLOR	transparent

And I was thinking, the "theme" can be greatly simplified by providing a few COLOR and SIZE settings and filling the rest with calculated values (lighter/darker and smaller/larger). At the heart of the matter only 2 values would be needed (or three if the black/white also needs to be another value).

Just thinking out loud though.

kirchsth commented 1 year ago

@Potherca: related to "dependent color/size":

Size should be simple I can try to make a calculation (I try to find out the correct default size that I can make all other values relative)
but related to the colors I'm not sure if there is a simple rule and if you check the (typical, reused) themes they use already concrete colors and e.g. $DARK_DARK could be lighter than $DARK

kirchsth commented 1 year ago

@Potherca:

related to "Size should be simple..."

I tried to introduce a default font size as starting point (that we can calculate all other sizes based on it) but skinparam defaultfontsize xxx didn't scale as expected therefore I didn't introduce it and for the moment I will leave it as it is.

If you review is OK I would merge it and would even create a new release 2.6 out of it (and move all other open into a backlog release?)

Potherca commented 1 year ago

Regarding:

If you review is OK I would merge it and would even create a new release 2.6 out of it (and move all other open into a backlog release?)

I'm all for it!

Usually I'd say bump all "documentation" issues to a 2.6.1 (so we can follow up with writing some prose and docs but no code changes) and everything else to v2.7 but based on https://github.com/plantuml-stdlib/C4-PlantUML/discussions/293, do we want to make a 2023-Q2 milestone instead?

mweagle commented 1 year ago

Thanks for adding theme support! I've published a handful of themes based on ColorBrewer and Seaborn palettes to https://github.com/mweagle/C4-PlantUML-Themes if you're interested in including/linking. Thanks again.

plantuml-stdlib / C4-PlantUML

Enables theme support #295