Be able to create an element from an element template

[nikku]

Is your feature request related to a problem? Please describe

As a user I am able to change an element to an element template of a specific type. I am also able to declare an element template as default; this ensures it is applied as the element is created.

What I am not able to do yet is to create an element of a specific type, i.e. because I want to create it right off the palette or append it:

We have a workaround for what I envision: Bootstrap the element (with all required extensions) manually, cf. ConnectorsExtension. That, however forces me to know all element templates in advance; it is not a solution applicable for general template support.

Describe the solution you'd like

• It is possible to create an element of a specific type similar to ElementFactory#create**, i.e. elementTemplates.createElement(template: ElementTemplate): DiagramElement - The element shall not be added to the canvas yet, but it shall be already configured to the extend needed.

Describe alternatives you've considered

Decide this is not a direction we want to go.

Additional context

This pops up in the context of connectors, specifically in the realm of how to integrate them nicely into the existing modeling UX.

[MaxTru]

Next step: discuss priority / necessity of this

[nikku]

@pinussilvestrus Updated with further background.

As mentioned I'll also create an epic to capture the overall picture.

[pinussilvestrus]

Just for my understanding, can you maybe explain what would be the difference between our existing commands?

const element = elementFactory.createShape({ type: 'bpmn:Task' });

return commandStack.execute('propertiesPanel.camunda.changeTemplate', {
  element: element,
  newTemplate: template
});

The ChangeElementTemplateHandler would be then create all the necessary properties retrieved from the bindings. The difference here is probably that I need to create the (base) element beforehand?

[nikku]

To clarify: This feature request is about creating a diagram element of a specific type outside the core modeling cycle.

The use-case is that I want to pull that element out from the palette (into "hover state"), and preview it accordingly (or add it using existing modeling APIs).

Hope this answers your question.

[pinussilvestrus]

Thanks for the clarification 👍

I quickly sketched this one from my current understanding

/**
 * Create an element based on an element template.
 *
 * @param {ElementTemplate} template
 * @returns {djs.model.Base}
 */
createElement(template) {

  // todo: throw?
  if (!template) {
    return;
  }

  const {
    appliesTo
  } = template;

  // todo: throw?
  if (!appliesTo || !appliesTo.length) {
    return;
  }

  // todo: what do if appliesTo has more than one entries?
  const type = appliesTo[0];

  // (1) create element from appliesTo
  const element = this._elementFactory.createShape({ type });

  // (2) apply template
  // todo: make command configurable, e.g. propertiesPanel.zeebe.changeTemplate
  this._commandStack.execute('propertiesPanel.camunda.changeTemplate', {
    element: element,
    newTemplate: template
  });

  return element;
}

This already works pretty nicely, e.g. by using this example template

[nikku]

But do we want to execute a commandStack action to get the job done?

We don't usually do that before element creation? What is supposed to be undone here?

[pinussilvestrus]

Good point. That would be the easiest way though, otherwise, we would need to pull all the stuff out of the command, and make it generally available. That would be another option. Note that these things also execute commands.

[pinussilvestrus]

If we want to make this stuff available without any command being involved, we would need to build from scratch (again), for all bindings extract only the creation bits of the update template command.

Lemme sketch that out.

[pinussilvestrus]

I tried out an approach that doesn't use commands, but re-uses our existing CreateHelper to fill up the element by the defined bindings. As a consequence, it works like an ElementFactory for templates.

That already works for all Zeebe bindings.

tldr

const elementTemplates = modeler.get('elementTemplates');
const create = modeler.get('create');

const element = elementTemplates.createElement(template);
create.start(canvasEvent({ x: 250, y: 300 }), element);

Find some sketching around on this Miro Board.
Branch: https://github.com/bpmn-io/bpmn-js-properties-panel/compare/582-element-templates-create?expand=1
What's missing:

• all bindings for Camunda Platform
• shall we validate the template beforehand?
• do not create extension elements when not needed (keep XML clean)

Let's sync on what direction we should follow next week @nikku 👍

[pinussilvestrus]

After a chat with @nikku I think the direction described in #582 (comment) is the way to go. Furthermore, we could consider (as future improvement)

• refactor the existing propertiesPanel.x.changeTemplate command to a similar fashion, moving the binding related bits to providers
• promote the elementTemplates feature as a service to a higher extent, e.g. providing more API in a similar fashion to the createElement one
  • elementTemplates.getMatching(element): Array<ElementTemplate> // get all applicable element templates (cf. #604)
  • elementTemplates.apply(element, template): void // apply my template
  • ...

all bindings for Camunda Platform

Since providing this in a similar fashion as for cloud-element-templates would need more time (due to some more bindings + edge cases), we could consider going the "command" solution, but providing the same API.

We can easily refactor it internally to the factory approach once we have more time. I would have to time box to make a final decision. Another possibility would be to make this feature only available for Cloud (for now).

[pinussilvestrus]

Along with our Reflect & Plan, and given our current priorities (Web Modeler & Connectors), I will descope the API for Camunda Platform for now. We can (easily) add the same foundations to the element-templates provider once we need it. I added another issue for that: #607