EIP sprite library

[nikolay-martynov]

There is EIP library by aheil https://github.com/aheil/EIP-PlantUML but:
. it lacks catalog of all what it offers
. there are bugs in it leading to some images not being shown at all
. it does too much with stereotypes and so on limiting where you can use those images due to syntax errors after macro expansion

Instead, i've created another library https://github.com/nikolay-martynov/eip-for-plantuml based on MIT licensed SVG's from https://github.com/comsysto/enterprise-integration-pattern-shapes-for-gliffy
There's quite a number of pictures for enterprise integration patterns.

Being a pure sprite library like Cloud Inside standard library you have lots of freedom about how you like your diagram to look like.

I've also made a full catalog that makes it easier to pick sprite you need and copy its name. You can find it description of project and it could also be linked from githubpages:
https://camo.githubusercontent.com/343945ec5319da62cd7955fa7f4c7b18a79e77be/68747470733a2f2f6e696b6f6c61792d6d617274796e6f762e6769746875622e696f2f6569702d666f722d706c616e74756d6c2f67656e6572617465642d6578616d706c65732f616c6c2d737072697465732e737667

Here's example diagram from EIP book (same as in project description):

@startuml
!includeurl https://raw.githubusercontent.com/nikolay-martynov/eip-for-plantuml/master/dist/eip-for-plantuml.puml
legend top
    You can use sprite
    anywhere you can use text.
    Rectangle content is most
    convenient.
endlegend
rectangle "<$EIP_MessageDouble>\nNew order" as newOrder
rectangle "<$EIP_Splitter>\nSplitter" as splitter
rectangle "<$EIP_MessageSingleGreen>\nOrder item 1" as item1
rectangle "<$EIP_MessageSingleOrange>\nOrder item 2" as item2
newOrder -> splitter
splitter -> item1
item1 -[hidden] item2
@enduml

It renders as the following on demo server: http://www.plantuml.com/plantuml/uml/XOz1IyD048Nl-HLZyPg4zYXIUb34WrRiILHacup9ucPscPrjpBztDqshKiGSminxVFFUhhmebj2Px4nJPKADWGsq8ivVb2MhlcYqj64RF79bIP2ag6nNalwmHWrv5-c1xAv4xV9toxapYjAzibDUaCjQUpan2vSI3JP8DOXr6SJloGQe546C0kzO2uwoeg5laH667xxWfnIZ_OYLA6eCmbGFj8VEUabkqdP8EhNEOjO-CUCZCxiylxvzUBj3xrM3LpPi3IvVw1vxi5mZpq1v8EpNQJdbDive4UI8xCU9yDFoPz969_664IcoutM83-vWdlXndFy3hpbw-9jU7Eb5TcWD-VAxps68uXGo_Y5_RdLT8xrEy0gf3ftv0W00

Please consider adopting the sprites.

[arnaudroques]

Well, it would be nice if both https://github.com/aheil/EIP-PlantUML and https://github.com/nikolay-martynov/eip-for-plantuml could be merged into a single product.
Maybe you should contact Andreas Heil to work together ?

[aheil]

I would propose to maybe integrate the sprites or any better UI elements in the EIP-PlantUML extension at some point. The project is always open for better UI elements. I have originally considered using the SVG sprites by Bernhard G. However, I decided not to use them in the first place as further development of the EIP-PlantUML required tweaking UI as well as probably adding new pattern and features in the future. If there will be a community there might be a good chance that someone takes the task to create suitable SVG graphics.

I have experienced that "sprites only" does not help in building sophisticated integration documentation with some hundred elements. We used to create diagrams in an automated process with some hundred queues and components with EIP-PlantUML already.

Using the "sprites" e.g. as in the Camel EIP documentation provided, does not necessarily create semantic useful diagrams. In contrast, the capabilities of PlantUML allow considering constraints and prerequisites in your diagram. Which IMHO is a lack of other tools such as Gliffy or draw.io where you "just draw images". One major goal of EIP-PlantUML is to allow to code your infrastructure documentation and ultimately to create automated documentation including the semantics in your PlantUML file. This is a major difference to "just images".

If any (or some) sprites to not render in EIP-PlantUML feel free to open issues as it is in a beta stage at the moment. This is the reason I have not considered to submit the EIP-PlantUML before a stable 1.0 version to the standard lib. EIP patterns are around for quite a while, therefore taking some time to increase the maturity of the library should not be an issue.

Turning off stereotypes is a feature added recently after switching to the new preprocessor features.

In terms of 'catalog of all what it offers', there is an extensive list of features offered by this extension in the README provided, which again is open to be extended.

The example above can be seen on the PLantUML server as well.

HIDE_STEREOTYPES()

Message(newOrder, "New order")
Message(item1, "Item 1")
Message(item2, "Item 2")
Splitter(splitter, "Splitter")

Send(newOrder, splitter)
Send(splitter, item1)
Send(splitter, item2) #transparent

I think with this example the difference is quite clear, as EIP-PLantUML focus on the semantic description of integration solutions. BTW: to group elements is WIP, so one can commit the #transparent tag (to avoid technical details in the code).

One more feature to come after a stable version will be available will be a collection Visual Studio Code snippets for easily writing integration diagrams.

I think the PlantUML team is up to decide if a sprite only library or a more syntax based library (or even both?) makes more sense in the standard lib.

[nikolay-martynov]

The project is always open for better UI elements.

Sorry I hadn't been able to fix issues I faced. First i tried to create catalog to see elements available and copy/paste names into diagrams. Once done I've found that many do not work. I tried to fix those issues but C# and lack of integrated build script did not allow me to.

I have originally considered using the SVG sprites by Bernhard G. However, I decided not to use them in the first place as further development of the EIP-PlantUML required tweaking UI as well as probably adding new pattern and features in the future.

They have quite a number of SVGs from different pattern groups. They're MIT now. I guess one can take those SVGs and manually integrate into whatever project.

I have experienced that "sprites only" does not help in building sophisticated integration documentation with some hundred elements.

I've quite opposing situation in my organization. We often need branded elements on diagrams that describe enterprise or solution architecture. Not abstract "translator" or "splitter" but:

1. either a product that serves particular purpose like translator
2. or product with detailed internals like: on this big picture this product has inside of it event driven consumer then translator and then finally it pushes to this message store that is actually a kafka bus

With sprites we are free to combine kafka/message store and whatever text we need in the element we need. You want product name on top? No problem. On bottom? No problem? You want product name between pattern icon and product logo? Here you have it: http://www.plantuml.com/plantuml/uml/POwnJWCn343t-ufGTUrbHr7LWXWOa91WH48cyUMYIvp8Te3-FQsEeLBNP_lv7KI1jPSyt2NokGVidCsiskJUMeQVCIQT-rSNP5z9aNJqjLXAIyrmsXLWFL7zjfZQRggyQndeuhC5H95jIA8tmx5TVpJEvzf38abnLhl0jC1-a2LH0uPY0axGixxZhnvpYbIGr7WaHHuOlGB5Z6RZjkkbEJuycdEmSTkdvzVF5nI1Y6zQ6VSVvDm_C2kveDkzAySgtGm7f72k_WC0

With macros and functions you have less possibilities in what you can achieve. Yes, you'll have pattern names for free on your diagram but what if i don't need them? What if I want component name on top rather than on bottom? What if I need arrows to go up or down or left? In all of these cases you will have to directly use sprites that are used by macros. If a library has both sprites and macros and both are properly documented and easy to use - that's perfect. Everyone will be able to get what he needs.

We used to create diagrams in an automated process with some hundred queues and components with EIP-PlantUML already.

Well, we generate PlantUML diagrams as well. Maybe not hundreds of elements. But if the process is automated then what's the difference between printing into the file

FuncName(Param1, Param2)

compared to

rectangle "<<Pattern Name>>\n<$SpriteName>" as ComponentName

? There is difference for a human that first option is less to type so maybe easier to remember and use. However, for automated process I really feel the difference is marginal.

Using the "sprites" e.g. as in the Camel EIP documentation provided, does not necessarily create semantic useful diagrams.

Well, lets define what's the purpose of PlantUML libraries: being semantically correct or letting people easily create diagrams they need?

Diagrams we create in our organization are not always correct to EIP book and even UML diagrams are often not correct as per book. And I'm not even embarrassed to admit that because:

1. those diagrams will be seen by people that haven't have proper skills to understand semantically correct by the book diagram
2. simplifications and additional elements are there intentionally to add more information and make diagrams easier to understand
3. I'd prefer to finish one diagram in simplest way I find good enough and continue with rest of the text because these diagrams are most of the time to be inserted in this or that (in our case asciidoctor) text

In contrast, the capabilities of PlantUML allow considering constraints and prerequisites in your diagram. Which IMHO is a lack of other tools such as Gliffy or draw.io where you "just draw images".

Well, maybe. But for us PlantUML is a way to embed diagrams we want into asciidoctor documentation. Some of these diagrams generated, some handwritten. But ultimate goal is to have as quickly as possible good quality documentation that is easy to maintain. We just don't care about constraints and so on. Does this have right to exist?

One major goal of EIP-PlantUML is to allow to code your infrastructure documentation and ultimately to create automated documentation including the semantics in your PlantUML file. This is a major difference to "just images".

Ok. But other people that just need to write documentation with diagrams... what should they do?
Library could support both usage types by providing clear and easy way to use both sprites and macros. If i want constraints and prerequisites and pure EIP then i go macros. If i want to quickly have diagram i want it to be then i go sprites. Just need clear sprite names and good catalog for them. Both could be provided by the same library.

If any (or some) sprites to not render in EIP-PlantUML feel free to open issues as it is in a beta stage at the moment.

As said earlier, I've went inside and tried to fix it myself. But there were just too much to fix since lots of things are manual and then I had issues with generating combined puml file. We have diagrams that use your library but in our org we cannot just sit and wait until someone fixes the issue. That's why generating sprites from existing library of EIP SVG felt fast and easy.

In terms of 'catalog of all what it offers', there is an extensive list of features offered by this extension in the README provided, which again is open to be extended.

What it lacks is illustration of how it looks. If i generate diagram programmatically them maybe i don't care because macro name is selected programmatically. But if i'm a human that need to add diagram to illustrate something i just wrote in user guide then i need a list of available elements to pick from. That's why any graphical design application has a graphical representation of each tool rather than just its text name. See example of office standard library. It's an ideal that makes it easy for uses to pick what they need: https://github.com/Roemer/plantuml-office
Same goes for Cloud Insight, which I personally like a lot: https://github.com/rabelenda/cicon-plantuml-sprites/blob/master/sprites-list.md

The example above can be seen on the PLantUML server as well

Sorry, but not exactly: there is different representation for each part of splitted message. See original from book here: https://www.enterpriseintegrationpatterns.com/patterns/messaging/Sequencer.html
It's true that sprites from Bernhard Grünewaldt also do not allow precise duplication of what's there in the book. However, they allow much more close replica compared to EIP-PlantUML in its current state.

I think with this example the difference is quite clear, as EIP-PLantUML focus on the semantic description of integration solutions.

Ok. But still there are lots of people (at least in my organization) that just need to add diagrams to documentation they write.

One more feature to come after a stable version will be available will be a collection Visual Studio Code snippets for easily writing integration diagrams.

What about people that write diagrams with hands? BTW, in our organization we use neither C# nor Visual Studio to generate diagrams. Means might be more useful to share recipes or articles or something like this that might be more (re)usable.

I think the PlantUML team is up to decide if a sprite only library or a more syntax based library (or even both?) makes more sense in the standard lib.

Sure. Since urls can happily be used, everyone can already use both libraries at present time without changing anything in PlantUML itself. It's just a matter of:

1. Performance when generating diagrams - that might be important if you have more than 20-30 small diagrams compared to 2-3 large diagrams
2. Using angle brackets in import statement or not - that's really not important
3. Telling people who want to write diagrams and come to PlantUML site that "here's how you can do it"

arnaudroques, maybe we can have a page or something on PlantUML site that's like a list of 3rd party libraries? You wouldn't need to choose and people could easily get exact recipe they need.

For example, in sprite library, all sprites come in 3 sizes to easily get exact diagram look we often need in our organization:

1. Icons are just small illustration to left of text
2. Normal size pictures for diagrams with 10 or more elements or when you want to use pictures to show details of some other element on diagram (like "system consists of these components and this one has the following structure")
3. Large pictures for diagrams with small number of elements (like 5 or less)

However, If one would need extra small or extra large icons - that's easily done by person who needs it. If you need HUGE icons for A2 paper - go generate 500px icons.

However, if you need diagrams-as-a-code then here's another library.

However, if you need both then you can have this too.

[arnaudroques]

Well, lets define what's the purpose of PlantUML libraries: being semantically correct or letting people easily create diagrams they need?

Well in my opinion, PlantUML libraries should be able to cover both approach.

Of course, we could easily integrated both libraries into the PlantUML standard library set. Maybe we will end up this way.
But we think that it would be easier to a single library that would allow both approach and both syntax.

We have created a #eip slack chanel so that we could discuss about this goal. I think that interactions will be easier on slack, so you are welcome to join.