Feature Request: New element attribute "diagram"

[basejumpa]

I'd like to propose following new feature based on Umlet 15.0.0:

see Possible-solution-Alternative PosAlt_05 in post https://github.com/umlet/umlet/issues/687#issuecomment-1244898601 below

[basejumpa]

I'd like to contribute (to) this feature by (helping) to implement it.

Current work-in-progress resp. demonstrator is to find at forked-repo/branch

• Sources: https://github.com/basejumpa/umlet/tree/add-export-multiple-pages
• Downloadable Build(s) see the Actions Area: https://github.com/basejumpa/umlet/actions

[afdia]

Hi If I understand it correctly, you want to work on a large diagram and optionally specify the export-outputfilename for each element. If you then trigger an export they should export to the specified files instead of the main file (I guess there still has to be a main export target file for all elements without a page?)

We will discuss the idea, but I see some potential problems with it:

• what if the specified page (=output file if I understand correctly) already exists? will it be overwritten automatically?)
• what if the specified output file location doesnt exist or you don't have the right to write there?
• what if I want to change the outputfilename/path? I would have to change several elements in the same way (with the danger that I forget one which remains in the "old location"
• the feature would probably be incomatible with Umletino (because a webpage doesnt allow writing files directly) and probably also with the vscode plugin (similar restrictions)
• how to share such diagrams with very specific filepathes between users and filesystems
• It is a feature which is hard to explain to users and has potential security risks when sharing diagrams. E.g. if I specify something like /etc/passwd as export file and if the user has the right to overwrite the file, it would just silently overwrite it with an umlet export (of course the user could check every element for specified pages, but opening foreign diagrams would be much more dangerous)

Maybe there is an alternative way of doing things which already works for your usecase?

• selecting the elements before exporting (if elements are selected before exporting, only the selection will be exported)
• if you plan to export the same group of elements many times, maybe assign them to a shared group, then you only have to select one of the elements and the others will automatically be selected
• splitting the diagram into several diagrams (you then could setup a script which calls umlet in batchmode and export all files to fixed filenames which you have specified in your batchfile). Of course you could no longer work on a large diagram, but on the other hand you could automate the whole export procress using a script. Thanks to the Umlet Tabs working on several diagrams should not be that much more difficult than working on one large diagram.

So my first impression is that I'm not sure if there is enough benefit to such a feature to break the assumption that Umlet only writes to the filesystem if explicitly selected by the user using the filechooser.

[basejumpa]

@afdia Thx for your precious feedback. The following I have to say about each point (I gave them ids PotProb_(i) for the potential problems and PotAlt_(j) for the potential alternatives in order to ease communication on it).

PotProb_01

In the current sketch of realization I see two situations of "already exist":

a) At least one of the output files to get exported already exist(s). b) A defined page within the uxf-file already exists.

Regarding a): Page(s) are never exported without exporting the entire file. So in the situation when a user exports, via the GUI, the file and she/he has exported previously then the file of the export of the entire file also exists and Umlet asks the user if she/he wants to overwrite or not.

Exception: The situation that file(s) exist(s) containing page exports but there is no file of the entire content is possible. Then the user wouldn't be asked. I rate this situation not very likely and would live with the fact that page exports would be overwritten without prompt before.

We could let Umlet show an info/warning about that afterwords in GUI and also console in order not to overwrite anything silently.

We also could let Umlet block the export in this situation, tell it to the user and tell him how to handle this situation: By deleting the page export files as well.

Regarding b): Overwrite a page export with another page export of the same umlet-file when exporting: This is not possible by design because Design_b) (see issue description).

PotProb_02

By design Umlet never exports the pages without exporting the entire content. I think this would handle this situation appropriately.

PotProb_03

I don't see any problem here because ...

a) basename-stem of file: The facts written in answer of PotProb_02. b) suffix of basename determined by the page_value: The user can easily identify all elements with the attribute page= by using the search functionality and search for page=. Then Umlet selects relevant elements.

PosProb_04

Currently I don't have (enough) experience with neither Umletino nor the VS Code plugin to say about this. I'll dive into it.

PosProb_05

Because the filenames of the page exports are always the filename of the export of the entire content with a suffix to its basename (suffix = pagename) I don't see any problem here.

PosProb_06

See my answer to PosProb_05.

[basejumpa]

PotAlt_01

This tedious and time consuming process I'd like to automize with this new feature. It is no alternative to the feature.

PosAlt_02

This is an improvement to PotAlt_01 but still no alternative.

PosAlt_03

This is exactly what I'm doing currently. Our Umlet sketches are organized like this as soon as we enter the phase that we use them in documents.

In previous phase(s) we have the entire content in one file and benefit from the advantages of the open canvas.

The problem is that we lose those advantages as soon we enter the documentation phase.

So I don't rate this as an alternative to the suggested feature.

[afdia]

I have thought about it and I'm still not a fan of such a specific feature, but what about a more generic alternative to it?

• add new batchmode parameter, lets call it -containsline="group=mygroup"
• if the parameter is set the batchmode export only collects elements which contain this line at least once for the current export and ignores everything else

Then you set up e.g. 4 batch export scripts each targetting another line which is only present in the desired collection of elements you want to export. This has several advantages:

• it's more flexible because if you already use a common background color, group or whatever you don't have to specify page= on every element
• if you don't have a "shared property" between those elements you can just use comments like "//exportPage1" and set -containsline="//exportPage1". Lines which start with // are not printed into the Umlet element, so it wouldn't change the visuals of elements
• it would not be a dead features in Umletino+VSCode and it would not automatically create other files during exports, because such property-lines only get their specific function in combination with a specific batchmode call
• the code changes wouldn't affect that many classes (basically just the Main method for the batchparam, a new method to collect only elements containing a property and maybe a logic to cut white borders around those elements - but you would need this logic anyway)

[basejumpa]

@afdia Thx again for following up with my idea about the new feature so deeply.

I understand your doubt about it because it ...

• is so special and would lead to dead code/feature in Umletino,
• creates files which appear as a surprise to people who do not know that feature.

I'd like to baptize the latter possible alternative with the new batchmode parameter as PosAlt_04 and derive a PosAlt_05 from it as follows:

PosAlt_05

derived from PosAlt_04

a) Umlet gets enhanced by a new attribute for graphical elements with name diagram.

a.1) It is a replacement for the attribute page. So the semantics of that attribute diagram is different and opens a broader usage/interpretation for functionalities than page. a.2) The attribute needs a value; of type string; same restrictions as the value of pagein the originally proposed feature, so:

a.3) diagram=value_diagram. value_diagram shall donate here any string excluding whitespaces and excluding characters which would lead to a malformed filename when attaching it to a basename of a file as basename + "_" + value_diagram + "." + ext.

a.4) Maybe it could be restricted that attribute diagramcan only attached to graphical elements whose circumference is rectangular shaped.

a.5) Umlet maintains a list of graphical elements bearing the attribute diagramwhich is a.5.1) alphabetically sorted by value_diagram, a.5.2) value_diagram is unique across entire uxf-file.

b) The attribute diagram makes special ... b.1) the graphical element bearing the attribute itself, b.2) all the graphical elements which are completely inside the circumference of b.1 b.2.1) grouping of b.1 with b.2 or groupings of b.2 with themselves are irrelevant for the functionalities related to attribute diagram(see c).

c) Graphical elements bearing the attribute diagram play a role in following functionalities: c.1) Export in mode per diagram c.2) Browse to diagram ... with commands c.2.1) Next diagram c.2.2) Previous diagram

Details of c.1): c.1.1) batchmode gets a new optional parameter -perDiagram. It is boolean. Default: false. By specifying is is set to true. If true, the export exports a output file per diagram defined in the infile.

Details of c.2): c.2.1) The UI of Umlet contains two new buttons. A < and a > button. Tooltips: "Previous diagramandNext diagram`. c.2.2) The buttons are always visible.

(Alternative could be that they appear as soon the first graphical element bearing attribute diagram and disappear if the last one with that attribute is being removed.)

c.2.3) When one of the buttons is pressed, Umlet zooms the diagram so that the target element is being displayed entirely with maximal possible size in the view-pane.

End of PosAlt_05.

Best regards!

[basejumpa]

Replaced content of description.

Before, the description contained the very first suggestion which was:

Usecase: As an Umlet user I want to be able to define one or more named page frames within an Umlet file. Connected to that the export command (to any format, including uxf) exports an output file for each page frame along with the file containing export of the entire content.

The element which defines the page frame and all the elements which are completely inside its rectangular circumference are exported per page.

Business value/benefit: This is so that I can include exported pages frames as figures in documents (such as reST with Sphinx) while keeping the benefits of having Umlet content in the endless canvas.

Additional details: Design_a) Defining a page frame shall be realized by attaching attribute page=value_page to any existing (rectangular) element.

value_page shall donate here any string excluding whitespaces and excluding characters which would lead to a malformed filename when attaching it to a basename of a file as basename + "_" + value_page + "." + ext.

Design_b) Umlet shall take care about that the user cannot create a value_page which already exists in the file.

[afdia]

Sorry for the delayed reply. I'm still not convinced that Umlet should have a feature which has many "connection points" to the user like new menu options, buttons, a new properties-panel attribute, ... when as far as I know almost everybody uses the concept of 1 file = 1 diagram. It would clutter the UI for users who prefer a simpler workflow and would still not work in e.g. Umletino where file export is restricted due to being a web application.

The concept of a specialized batchexport option would avoid those problems and keep the UI simple while still allowing partial export of a diagram. Besides the mentioned -containsline="//exportPage1" approach which exports only elements which contains the given line within its properties (as suggested above), it could also be implemented similar to the new diagram attribute but hidden for normal users:

A new batchargument e.g. -container=//uniqueLine which instructs umlet to only export elements which are within the space of the given container element. Instead of a new diagram attribute to define containers, I would simply search for the element which contains the specified line (here //uniqueLine, but can be anything. maybe throw an exception if no unique non-relation element can be found). When the element is found, Umlet only exports elements which are fully overlapping the specififed element.

The batchexport could be called multiple times with different containers, therefore the outputfilename of each container would be contained within the batch-call and not partially distributed into element properties (which I see as an advantage because I don't like the idea of diagram elements having influence on filenames which may cause problems with different OS like Windows vs Linux allowed characters in filename or even security issues when we forget to forbid all ways to traverse directories e.g. diagram=../../../name)