New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow generation of diagrams using third-party diagramming tools #600

Open
Nava2 opened this Issue Aug 26, 2015 · 39 comments

Comments

@Nava2
Member

Nava2 commented Aug 26, 2015

Originally reported on Google Code with ID 702


There is growing list of third-party tools for drawing UML diagrams.

Generating approproate Javascript versions using some of these tools would be useful.

See
http://modeling-languages.com/javascript-drawing-libraries-diagrams/


Reported by @umple on 2015-04-07 14:49:40

@marc22alain

This comment has been minimized.

Contributor

marc22alain commented Oct 6, 2016

The goals of the project

Implement the use of an abstracted API that draws interactive diagrams, with fully-featured formatting capabilities.

Features

It should:

  • make it easy to draw a variety of diagrams, such as class and state-machine diagrams
  • be easily extensible to new diagram types
  • allow the user to edit the UML (or other) model directly from the diagram, sending changes back to the server for updating the text view
  • allow the user to export the diagram as a graphic for inclusion in documents
  • reveal nested state-machine charts by double-clicking on the parent element

Project Constraints

The scope of work must be restricted to the client-side.
Changes to client-server system configuration are out-of-scope.

The selection criteria for a 3rd party JS library

Library Open-Source / Provisioning Active Full-Featured Format-ting Zooms & Pans Views User Editable Data Ease of Use
JointJS Mozilla Public License - via CDN Draws UML class and state-machine diagrams, using plug-in architecture. demo
Raphaël MIT - via CDN Basic drawing elements provided
FabricJS MIT - via CDN X Fully-featured for drawing in the HTML canvas and with SVG; good docs
PaperJS MIT - via CDN X Fully-featured for drawing vector graphics; good docs
JsPlumb MIT/GPL2 (dual) - via CDN X Fully-featured for drawing graphs; good docs
P5JS GPL - via CDN X Based on Processing! Provides: basic drawing elements, data-binding, transition animations, tutorials.
CytoscapeJS MIT - via CDN Fully-featured for drawing graphs; has proper manual
Dagre-D3 MIT - via CDN X X Extends and abstracts D3 to draw graphs, demo
D3 BSD - via CDN X Provides: basic drawing elements, data-binding, transition animations, tutorials.
KLayJS Eclipse Public License - by self X X Designed to draw graphs - code is obfuscated
@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Oct 6, 2016

Great work. as we talked let first choose what will be the best candidate :-)

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Oct 7, 2016

OK. Update the table if you can, but rule out a) Any not being actively developed (updates in 2016), b) Those that cannot easily draw class and fully nested class and state diagrams; c) GPL licensed code, as this is incompatible with MIT and forces GPL on us.

The exception to c would be if we can have people who set up UmpleOnline install the js code from the third party directly so we don't have to clone it or modify it.

Ideally UmpleOnline would iniitally just have the new library as an alternative drawing technology. We would maybe switch to it as default (leaving the others as alternatives) once we have stabilized this work.

@marc22alain

This comment has been minimized.

Contributor

marc22alain commented Oct 11, 2016

I believe that I have completed an adequate comparison of the FOSS JavaScript libraries for producing either diagrams, graphs, or drawings.
The only library that is ready to produce UML diagrams is JointJS. While a few of the other libraries have shown examples of state-machine diagrams, none offers an API that enables the user to edit the diagrams.
As for provisioning the user with the JS library, I would suggest that our web page should only provide a <src> link to a content-delivery network (CDN) that provides the library.
I like the idea that this project should, at first, be thought of simply providing an alternative to the current drawing methods. This way, we can get something out there sooner.

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Oct 11, 2016

Great. Go ahead then. There is already a switch in the options menu and with 'hot keys' to switch diagram type.

The biggest initial challenge will be generating the needed input for their tool. Start with this as a new generator (we have many generators). Generate using UmpleTL of course. Start with class diagrams. To be even more agile, just have it display the raw classes. After that works. Add attributes. Then associations and generalizations, and other details (interfaces, methods). Once all is perfect, you can move on to state machines if you have time.

@marc22alain

This comment has been minimized.

Contributor

marc22alain commented Oct 20, 2016

In JointJS, there is a class called joint.shapes.uml.Class that is used to instantiate UML classes. It is sub-classed to create Interface and Abstract classes.
Given the following umpleClass delivered from the server:

class1 = {
    "position": {"x": 543, "y": 212, "width": 140, "height": 108}, 
    "attributes": [
        { "type" : "String", "name" : "startTime", "modifier" : "", "traceColor" : "black" }, 
        { "type" : "String", "name" : "endTime", "modifier" : "", "traceColor" : "black" }, 
        { "type" : "String", "name" : "status", "modifier" : "", "traceColor" : "black" }
        ],
    "methods": [],
    "id": "TimeSlot", 
    "name": "TimeSlot", 
    "isAbstract": "false", 
    "displayColor": "" , 
    "isInterface": "false"
}

, a new JointJS Class object can be instantiated with this code:

new_class1 = new joint.shapes.uml.Class({
    position: class1.position,
    size: class1.position,
    name: addToArray(class1.name),
    attributes: addAttributes(class1.attributes),
    methods: addMethods(class1.methods),
    id: class1.id
}); 

, where there are short helper methods addToArray(), addAttributes(), and addMethods().

These helper methods format the data for the constructor. Please note, however, that the nested object representation of attributes and methods is lost in the JointJS Class definition.

Alternatively, by using the server to produce a different format for the JSON representation of the Umple model, such as:

class2 = {
    position: {"x": 543, "y": 212},
    size: {"width": 140, "height": 108},
    attributes: ["- startTime: String", "- endTIme: String"],
    methods: [],
    id: "TimeSlot",
    name: ["TimeSlot"],
    isAbstract: "false", 
    isInterface: "false"
}

, then the JointJS Class could be instantiated with:
new_class2 = new joint.shapes.uml.Class({ class2 });.

I am suggesting that we would keep the isAbstract and isInterface properties in order to determine which class type to instantiate. This template language solution does not address the shortcoming of the simplified methods and attributes in JointJS Class.

I realize now that I need to grasp the JointJS representation of the diagram elements, to determine how it would be sent back to the server to update the model.

Here it is for class2:

{
    "type":"uml.Class",
    "name":["TimeSlot"],
    "attributes":["- startTime: String","- endTIme: String"],
    "methods":[],
    "position":{"x":543,"y":212},
    "size":{"width":140,"height":108},
    "angle":0,
    "id":"TimeSlot",
    "isAbstract":"false",
    "isInterface":"false",
    "attrs":{
        ".uml-class-name-rect":{"height":40,"transform":"translate(0,0)"},
        ".uml-class-attrs-rect":{"height":60,"transform":"translate(0,40)"},
        ".uml-class-methods-rect":{"height":20,"transform":"translate(0,100)"},
        ".uml-class-name-text":{"text":"TimeSlot"},
        ".uml-class-attrs-text":{"text":"- startTime: String\n- endTIme: String"},
        ".uml-class-methods-text":{"text":""}
    }
}
@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Oct 24, 2016

Just for the record. There is another library called mxGraph
The website draw.io is based on it.

@marc22alain

This comment has been minimized.

Contributor

marc22alain commented Oct 25, 2016

I have just pushed some basic functionality to the branch. You can see it by checking out the branch, starting up the server locally, and selecting the JointJS class diagram type with one of the demonstration class models.
Edit: now including display of basic association links.

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Nov 8, 2016

Great work so far.

Some next steps:

If you select the background, focus should be grabbed (note the yellow border)
it as happens with editable and graphviz. The command keys for doing
things like control-T to hide/show text etc. would then work while there
is focus on the jointjs diagram. This is quite important for consistency.

Also the diagram should be drawn as a constant size of UML elements, and you should be
able to scroll it with scrollbars if it goes off the edge. I note that if
I zoom the window in, the scrollbars appear so just drawing with constant
size should be all that is needed.

I would prefer a slightly lighter shade of grey too.

Then, onward with editing or state machines (I leave it up to you which you prefer).

@marc22alain

This comment has been minimized.

Contributor

marc22alain commented Nov 21, 2016

I am now investigating how to implement the display of state machines with the JointJS library, including the display of nested state machines and mixed class / state machine diagrams.

As I see them, the high-level tasks are:

  1. Design a JSON data format that properly describes the state machine
  2. Revise an existing or create a new generator to generate this JSON data
  3. Revise the server code to process this new data request type
  4. Design and implement a diagram interface that provides an intuitive way to explore the mixed class diagram and multi-level state machine

My first big question is about the best way to accomplish # 2.
Do I:

  • extend Generator_CodeJson.ump to generate the additional JSON to describe the state machines; this would require ensuring that the client's Editable Diagram parser ignores this extra data
  • extend Generator_CodeJson.ump to generate the additional JSON, but it does so only in response to an additional build option argument coming from the client
  • create a new Generator_ ... ump to create the mixed class and state machine JSON

Are there other options as well?
All suggestions would be appreciated!

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Nov 21, 2016

Unless you can see that it would result in extra complexity, I would have thought that your third option: "create a new Generator_ ... ump to create the mixed class and state machine JSON" would be the better one. My second choice would be your second option.

There is an alternative argument that says all aspects of a model should be made available to the UI, (your option 1) such that it can generate code which mixes class and state diagrams. However I think that from an agile perspective, the third option is better. A more complex UI could always request both results.

One more thing: I note in the current code that if I click on a class it does not highlight the respective code in the text pane. Both the graphviz and the original editable class diagram did this.

@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Nov 22, 2016

I would go with option 3 but design the generator in a way it could be reused later. In big systems, for example, we might not want to have state machines generated all the time and need to have them when they are required (which shows the usefulness of option 2).
Option 1 looks a little bit tricky because it might break the current editor and also need debugging which is time-consuming.
To sum up, I would say reuse the current code generator for JASON under a new generator (which is just duplication), then mix state machines with it. However, allow future developers to easy disable state machine generation for class diagrams.

@marc22alain

This comment has been minimized.

Contributor

marc22alain commented Nov 24, 2016

In discussion today with Vahdat, we reviewed the Umple state machine model, how umpleonline draws the state machines in GraphViz, and how we would like to see them drawn with JointJS.
Generally, we seem to be happy with the GraphViz rendering, but there are opportunities to enhance the diagrams:

  • actions or transitions with multiple behaviours generally consist of a lot text; some way of hiding / showing, or at least hinting of its presence (with an ellipsis for instance) would be preferred
  • keywords such as after, queued, and pooled should be colour-formatted and added to the state machine and transition labels (as appropriate)
  • dotted lines to separate orthogonal regions of composite states should be added

Also, there are a few other items offered for discussion:

  • any state qualified with the final keyword should be rendered with the UML standard symbol for a final state
  • when a state has multiple out-transitions, show a single one connected to a pseudo-state from which all of the transitions propagate
@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Nov 25, 2016

I agree with much of the last post, but not the very last point.

@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Nov 25, 2016

Please consider tthat the last point is not about all transitions. It should be related to transitions with the same event names. Having pseudo-state is not necessary in the current situation of Umple and I also like the current approach, but I can consider the case it which it would be beneficial. For example, if one day we extend the sytax of transitions to have something like event [guard] -> S1 else S2; it would be much better to have the proper pseudo-state.
@marc22alain let's not have the pseudo-state (joint) and follow the approach we have in Graphviz.

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Nov 25, 2016

OK. I see future extensions allowing this.

@a3994288

This comment has been minimized.

Contributor

a3994288 commented Feb 26, 2017

I've pushed the basic functions of adding class/associations to the branch issue#600term.

As discussed with Vahdat, I will pop up a window beside the class object to let the user edit the class instead of editing it right on the class object (because JointJS does not have the function out of the box)

a small bug I found is that the size of jjsPaper does not change when the browser window size changes. I will work on it.

@a3994288

This comment has been minimized.

Contributor

a3994288 commented Mar 10, 2017

As we discussed before, there are two options to edit the properties of a class object in JoinsJS paper.

  1. pop up a property dialog.
  2. edit on the object (just like editable class) diagram.

I chose to go with the first approach because it is easier to implement and easy to use, the drawbacks of the first approach are distracting user and inconsistency.

I have implemented basic features for the first approach, and I've recorded a demo here (please select the highest quality to watch): https://youtu.be/WswuVwQSgKM

While I am working on the first approach, I found one way to implement the second approach is to create my own UML object instead of using the JointJS default ones (see examples here: http://resources.jointjs.com/tutorial/html-elements)

Should I keep working on the first approach? If so, I will fix bugs on my current implementation and have a PR by next Friday.

Or should I start to work on the second approach? If so, I should have the basic features of the second approach by next Friday.
If you have a better idea, also please let me know.

Also, as I talked with Vahdat, when the mouse move on the link and about to delete it, a red 'x' should be displayed instead of a 'hand' cursor. This features is implemented by JoinsJS already (see the video above), However, it does not display properly in umpleonline, and I am still investigating the reason.

Last, the bug relates to the JointJS paper size when resizing the browser has been fixed, it will be push together with my next PR.

@a3994288 a3994288 closed this Mar 10, 2017

@a3994288

This comment has been minimized.

Contributor

a3994288 commented Apr 7, 2017

I wrote an editable State Machine Element, and here is what it look like in umple: link (pretty much works the same as the one for Class)
However, even the element is editable, editing the element will not affect the umple code. We might need to write some functions in the back-end to support, I will look it up next week see if I can make it work (maybe I cannot)

I am still working on the auto-layout for nested state machine and avoiding overlapping for links.

Below are some bugs I fixed:

  • Now the remove icon 'x' will be visible when clicking the 'delete' button in the tool section and will be removed when 'delete' button is clicked again.
  • methods textually will show up in the diagram, could you please provide a specific case?
  • I am going to handle the cases when there is error coming from compiler (not done yet)
  • define method with parameter in graph is fixed (not commited yet)
  • The format to define a method in graph is + test() : String, the plus sign indicates the return type. However, when there is no sign at the beginning, should I set it to private by default?
  • When attributes are added they should appear after the keyword isA: In the editable class diagram, the order of 'isA' and attributes depends on which one was added first. Should I try to change this feature?
  • current font size is 12 which I think is big, so I will make the icon smaller.
@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Apr 7, 2017

Thanks.

I wrote an editable State Machine Element, and here is what it look like in umple

Change the transition arrows to be like the one we have for associations.

I will look it up next week see if I can make it work

Even, you can satisfy this, make sure textual to graphical work correctly.

I am still working on the auto-layout for nested state machine and avoiding overlapping for links.

Good. This is important as well.

methods textually will show up in the diagram, could you please provide a specific case?

I didn't get what you want.

The format to define a method in graph is + test() : String, the plus sign indicates the return type. However, when there is no sign at the beginning, should I set it to private by default?

The sign + shows if it is public or not. If people directly put - then make it private. Wth sign +, keep it as. The Umple compiler will consider that as public.

When attributes are added they should appear after the keyword isA: In the editable class diagram, the order of 'isA' and attributes depends on which one was added first. Should I try to change this feature?

Not a hight priority task. If it's easy to do it otherwise focus on other tasks.

@a3994288

This comment has been minimized.

Contributor

a3994288 commented Apr 7, 2017

methods textually will show up in the diagram, could you please provide a specific case?
I didn't get what you want.

In the previous message, you mentioned that When you define methods textually it doesn't show up in the diagram., However, It does show up in the diagram when I tested that. So that might be a bug that I am not aware of. Could you provide an example situation? (don't bother to rebuild the branch and test, you can just generally describe what you did so that I can test around it )

@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Apr 7, 2017

I don't remember now :-) . Maybe, it's been fixed. I'll check it in your PR.

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Apr 7, 2017

Remember that you have to click the option to see methods ...

@a3994288

This comment has been minimized.

Contributor

a3994288 commented Apr 8, 2017

should the comments be included in the state machine diagram? for example, this is how it work right now. image

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Apr 8, 2017

No, comments should appear only in tool tips.

@a3994288

This comment has been minimized.

Contributor

a3994288 commented May 5, 2017

There are few bugs can be fixed with JointJS diagram in the future:

  1. When adding split points to the link, the information should be saved so that the graph will be kept the same when reloading.

  2. It is fine to add/remove a link (associations and generalizations). However, a link can be re-direct to another object in the graph, when re-direct, we should be able to just call a single function to update the code instead of calling remove and then add.

  3. When the format of the class attribute or method is not correct, we need to throw an error to notify users.

  4. For JointJS state machine, umple code need to be updated when the diagram changes

  5. Some examples cannot be loaded, like "Geometric system", it seems like the JSON that received from the server is not in a correct format. Some commas are missing.

  6. When holding ALT and scrolling the mouse, the graph should be able to zoom in and out. However, because the customized JointJS class was used, and the HTML element rendered above the JointJS element won't zoom. To fix this problem, we need to update the HTML element when the JointJS element changes.

@a3994288 a3994288 removed their assignment May 5, 2017

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Sep 12, 2017

Priorities to get joint.js capability complete:

a) When the joint.js diagram is edited, update the model in the same way as our editable diagrams update it. Currently updates are ignored. (This is item 4 above).

b) Fine-tuning of the look of the diagram. Currently the boxes around classes are too thick.

c) Other issues in the above list of bugs.

d) State diagrams in joint.js (if this is possible).

@vahdat-ab

This comment has been minimized.

Member

vahdat-ab commented Nov 8, 2017

@runqingz
I suggested Umple to a researcher who does an experimental study on modeling IDE.
We could not draw associations and generalization graphically in JointJS. I know it is there but I personally could make it. It might be disabled. However, we need to make it clear. Please have a look at it and if it is there let me know how it is done.
Another point is that if we select a class graphically the related text must be highlighted. This is done in the default graphical view for Umple code.

@runqingz

This comment has been minimized.

Contributor

runqingz commented Nov 14, 2017

@vahdat-ab all the features you are mentioning exist; however as we discussed, they are all currently triggered only if you click on the corresponding portion of the graph when your cursor is a compass like cursor (always work if you click on the class icon). I guess it was implemented like this to distinguish between text edit and graph editing. (Sorry I clicked on the wrong button "close and comment")

@TimLethbridge

This comment has been minimized.

Member

TimLethbridge commented Dec 8, 2017

This master issue is being kept open for reference. Specialized issues to be worked on to continue joint.js are #1140 #1137 #1131 #1132

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment