Support create/append anything

[nikku]

Is your feature request related to a problem? Please describe.

Currently our modeling experience is geared towards quickly building end to end BPMN diagrams. We're a little bit reluctant on modeling for execution use-cases; each and every task has to be manually upgraded when modeling for execution. At the same time we've received feedback in the past that people don't know how to model X, where X is any element (parallel gateway, service task) that people do not see in the palette / context pad. The replace menu, the one thing they need to understand is hard to spot, at times.

Describe the solution you'd like

A way to to create/append any element from the palette (create) and context pad (append):

• Feels native in our existing modeling experience (cf. design principles)
• Available in a way that people recognize ("create something else", "append something else")
• Keyboard enabled (model keyboard only)
• Scalable (due to the large amount of options they have as a choice), also: keyboard enabled
• Integrates with / amends existing replace menu
  Create, append and replace are interconnected and shall work in similar ways
• Pluggable: Accounts for custom element types defined via elementTemplates
• Extensible / replaceable: Defines clear APIs that can be replaced to support a different modeling UX (i.e. advanced create / append controls)

Breakdown:

Step 1: New replace menu + reworked popup menu foundations: ✅

• Implement new replace menu UI #1793
• Add element templates to replace menu camunda/camunda-bpmn-js#204
  • Ensure interoperability with connectors extension camunda/camunda-bpmn-js#211
  • Cannot replace with base element if element template is applied camunda/camunda-modeler#3350
  • Remove feature flag
• Integrate new replace menu camunda/camunda-modeler#3332

Step 2: Create/append anything:

• feat(popup-menu): allow entries to be draggable diagram-js#731
• Add append anything
  • Add append to contextPad #1801
  • Add keyboard shortcuts for append #1808
  • Append anything breaks modeler when triggered from connection #1813
  • Add element templates provider for append menu camunda/camunda-bpmn-js#235
• Add create anything
  • Add create to palette #1798
  • Add keyboard shortcuts for create #1814
    • feat(palette): allow trigger with entry id diagram-js#741
  • [camunda-bpmn-js] Allow to hide behind feature toggle until fully implemented (Be able to hide create / append anything behind a feature toggle camunda/camunda-bpmn-js#236)
  • Add element templates provider for the create menu  camunda/camunda-bpmn-js#243
• Integrate create/append anything camunda/camunda-modeler#3472

Follow-ups to consider:

• Add text annotation to the append menu #1806
• Improve semantic ordering in replace / append menu for "implementation" #1621
  • strictness of append menu - Add append element #1802 (review)
• Accessibility check-up: Improve the aural interface of the element template chooser diagram-js#735
• Cannot find Participant in create menu #1816

Describe alternatives you've considered

Keep our two step approach to model anything.

Additional context

See element template chooser UX for a working simple UI component.

---

A prototype that sketches how this feature could look like:

---

Related to forum post.

---

Cf. also discovery board.

Cf. connectors solution architecture.

[nikku]

Announced via forum and pushed a running version to our BPMN modeling demo.

[smbea]

Working on adding UI for replace anything: develop...add-replce-anything

• I added a searchPopupMenu that can be easily used by replace, append, create. I based it on https://github.com/bpmn-io/element-template-chooser
• I moved the replaceMenuProvider to a replace-menu folder which contains the replaceMenu (that calls to open the searchPopupMenu)
• In contextPadProvider, wrench tool calls replaceMenu.open instead of popupMenu.open

Before going forward with this approach and adding some tests, I want to present to team and have some feedback.

[barmac]

I am wondering what happens to the plain old PopupMenu after we implement this. If I understand it correctly, the diagram-js infra is too inflexible for us to have create/append anything based on this.

[smbea]

Currently I am still using PopupMenu logic of having the providers and using it to feed the entries. Of course this can be re-implemented on the new search PopupMenu. But I think maybe we should keep the original PopupMenu at least for now, for backwards compatibility.

[barmac]

But I think maybe we should keep the original PopupMenu at least for now, for backwards compatibility.

For sure, as we use it now also for the alignment/distribution buttons :)

However, if I am not missing anything, the search menu does not use the popupMenu to gather entries, does it?

[smbea]

Technically correct, the replace anything menu. This is where the "searchPopupMenu.open" is called.

Now that I'm seeing this again, this part could be generalised and we could simple have a ReplaceMenuProvider (already exists), AppendMenuProvider, CreateAnythingProvider to have the specific entries. And replace replaceMenu.open(...) with searchPopupMenu.open(element, provider, ...). But in any case, we will still be using the popUpMenu providers logic.

[barmac]

The problem with the diagram-js popupMenu I wanted to signal with:

If I understand it correctly, the diagram-js infra is too inflexible for us to have create/append anything based on this.

is that the popupMenu does not allow the application to freely decide on the structure of the menu. The popupMenu gathers the entries and has a strict way to construct the HTML based on this.

In the case of append/create anything, the structure is totally different:

So instead of entries providers as we have with the popup menu, we will in fact have menu providers, or plainly different menus, as you noticed. Then, to support for example the connectors use case, append menu should also be able to be enriched so that it contains not only plain BPMN elements, but also custom elements.

I hope this helps, and I am happy to discuss this if you want to.

[smbea]

With this the popupMenu UI would stop being used yes, if thats what you are trying to get at. Because of the exact reasons you mentioned. That is why I am only using the original popupMenu for this._popupMenu._getEntries (feature which can be easily migrated to the new one later if hypothetically we chose to remove the original popupMenu)

[smbea]

Some other thoughts:

• We can build the searchPopupMenu component to be prepared to received the element template structure we know (including description, etc) - (see here). Although including this in bpmn-js might not be the best practice since element template entries will be added after

• We can build a general component that allows custom html to replace the base entry html (see spike here and custom html provider rough example). This might make more sense.

  • If we go for this approach then we should consider that the search (as is in connectors extension) must assume there could be at least a description property, so it can search for the input there as well.

[smbea]

After a chat with Nico, we decided that it makes sense that the popupMenu be completely replaced by the new UI. For this, we talked about having the UI portion in a separate library (like "diagram-js-ui") that exposes it's own preact version, similarly to properties panel, in order to try to avoid preact version conflicts.

So far, I have:

• tested that the popupMenu can be replaced without conflicting much with existing usages of it - eg alignment and distribution
• i moved the UI portion to a separate library (still working locally)

Next steps:

• test with other modules that use preact like properties panel to check for conflicts
• move on to proper implementation
  • clean up of existing UI code (was taken from connectors extension, but should be reworked to properly replace the original popupMenu in terms of structure and classes applied)

[nikku]

I believe all remaining (diagram-js) items will be closed via bpmn-io/diagram-js#710 + linked pull requests.

[smbea]

The first part of the epic - new popup menu - has been implemented and released with bpmn-js@11.0.0.

Therefore, will move on to allowing "replace with templates" in camunda-bpmn-js(camunda/camunda-bpmn-js#204)

[smbea]

With Modeler v5.6.0, we are releasing the new popup menu. But we are leaving "replace with templates" out for now because we need to ensure usage of camunda-bpmn-js together with the connectors extension works properly (issue camunda/camunda-bpmn-js#211)

The shortcuts for the the replace menu will be added in a later release too.

[berghall]

+1 waiting for this!

[smbea]

Replace everything has been fully integrated into desktop modeler with v5.7.0.

Currently working on adding append to the context pad #1801. There are some things that need to be added/fixed first to support the append behaviour we defined:

• feat(popup-menu): allow entries to be draggable diagram-js#731
• fix(element-factory): add missing attributes #1807

[smbea]

With #1811, we made the decision to encapsulate the create/append feature within a module. This way users can opt out of this if not wanted. This will be done fully after #1815.

[smbea]

There are two more items that are defined and easily implemented regarding the append menu:

• Cannot find Participant in create menu #1816
• Append anything breaks modeler when triggered from connection #1813

I would argue that after those are done, we have a good solid base to integrate in camunda-bpmn-js and add the template entries. There are remaining follow ups linked on this issue description which can be tackled in a following iteration.

Feel free to point out if you think any of those should be handled in this iteration.

cc @nikku

[nikku]

Makes sense.

In terms of impact, I'd love to see #1621 addressed, because it makes non-keyboard discovery substantially simpler.

[smbea]

That would be my next priority. I completely agree with the potential that feature has 🙂

[smbea]

Append/create anything have been included in Modeler 5.8. The missing features (Append/create templates + modeler shortcuts) are likely to be included in the next release

[smbea]

The implementation for this topic has been concluded. There are of course some improvements and bugs reported but I think they can be picked up overtime and we can close this issue.

Some of the issues I gathered:

Improvements:

• Improve the aural interface of the element template chooser diagram-js#735 (maybe during accessibility days)
• Add text annotation to the append menu #1806 (not planned, needs some effort)
• Create/append search should prefer items starting with typed text camunda/camunda-modeler#3439 (assign to me already, will likely follow up)
• Cannot type to filter in replace menu #1839

Bugs:

• Cannot access replace menu header icons with keyboard camunda/camunda-modeler#3437

I will move on to work on documentation and etc, tracked on the parent issue.

[SanderBreivik]

Hi! I do not know if this is the right place. But is it possible to remove the append menu from the pallete? I have tried to create my own provider with my own getPalleteEntries where i delete the 'append' menu, but it still shows.

[smbea]

@SanderBreivik Please have a look at our forum, here is a post regarding that topic: https://forum.bpmn.io/t/custom-appen-element-popmenu/8807/2. If you still have trouble with this, please create a forum post and feel free to share you current implementation

[SanderBreivik]

Thanks @smbea! I found the problem: I forgot to add what I assume is a priority number (the 500 in this): this._contextPad.registerProvider(500,this);

[Ken-Scofield]

Help, how to add "create element" to palette?

[nikku]

Provided nowadays as an extension.