Documentation/Manuals/Books regarding customisation


#1

Hi,
short of “just reading the examples” - are there any resources for how to go about customising the modeler ?

I’m particular interested in added a “window” for some data entry for each node and to get that read/written into the generated XML.

(I’m wrapping the canvas used to display the modeler in some ExtJS panel stuff - compiled up the code and then just copied the generated index.js into my project - probably not a great way of doing it)


#2

We have a number of examples that should cover the use cases and extension points, too. Depending on your use cases, you could simply listen to diagram events is enough for you.


#3

Its might be that the diagram events are enough.
But - for example - if I listen for a double click - open my window - it still shows the original “name” edit frame.
How do I prevent that ? (i tried e.preventDefault() and return false - but I think its opened when it calls my event handler)


#4

The problem is that the edit box openes before you are able to intercept the event.

To solve this, simply listen to the event with a higher priorty, i.e.

eventBus.on('element.click', 5000, function(e) {
  console.log('clicked, yEA!', e);
  e.preventDefault();
});

#5

Perfect - I’ve got a window opening now - i’ll continue to play :smile:


#6

Ok - mostly there now - I have a window with properties.
I can change the X,Y etc
But “name” is changing on the element (i can see it when I re-open my window) - but its not reflected on the diagram.

I saw some code which does something like :

me.renderer.invoke(function (elementRegistry, modeling)
{
modeling.updateProperties(e.element,
newData);
});

So - I tried that - but it still not updating.
Here - I’ve set newData to be an object containing the data I need to change - so something like
newData={name: ‘somename’};

[ no idea what this invoke is supposed to do - it was a c&p from google job! ]

Any clues ?


#8

The reason you need to generally dispatch updates via modeling is the fact that bpmn-js needs to be informed when elements have changed (read about it here).

Using modeling.updateProperties(...) changes attributes of the underlying BPMN element (exactly what you want to do). For details have a look at the UpdatePropertiesHandler that takes care of doing that.

For further assistance, please provide your example somewhere so we can look into it.

Edit: Learn about the available BPMN properties in the bpmn.json descriptor.


#9

What I have is something along the lines :

function showProperties (e) {
    //newData is actually setup via a form..
    var newData={ name:'blah'};
    me.renderer.invoke(function (elementRegistry, modeling) {
             modeling.updateProperties(e.element,
             newData
          );
    });
}

 var eventBus = me.renderer.get('eventBus');

 eventBus.on('element.dblclick', 5000,function (e)
      {
         if (showProperties(e)) {
            e.preventDefault();
            return false;
         }
 });

Now - I can see that the “name” property changes to “blah” - and if i go back in - the form has this filled in - but the diagram still has the name being blank… (and so no label)…

I also tried without the event handler :

function setName() {
   me.renderer.invoke(function (elementRegistry, modeling)
                                {
                                    var newData = { name: 'blah' };
                                    var e=elementRegistry.get('StartEvent_1');
                                    modeling.updateProperties(e,
                                        newData
                                    );
                                });
}

and - again - no updated diagram.

I’m probably just missing something stupid…


#10

I edited the modeller example - just added an extra button to the html

 <ul class="buttons">
   <li>
     download
   </li>
   <li>
     <a id="js-download-diagram" href title="download BPMN diagram">
       BPMN diagram
     </a>
   </li>
   <li>
     <a id="js-download-svg" href title="download as SVG image">
       SVG image
     </a>
   </li>
   <li>
     <a id="js-setName" href title="SetName">
      SetName
     </a>
     </li>
 </ul>

And then - added code to set the name in the js

  var downloadLink = $('#js-download-diagram');
  var downloadSvgLink = $('#js-download-svg');

  $('#js-setName').click(function(e) {
    e.stopPropagation();
    e.preventDefault();

    renderer.invoke(function (elementRegistry, modeling)
                                {
                                    var newData = { name: 'blah' };
                                    var e=elementRegistry.get('StartEvent_1');
                                    modeling.updateProperties(e,
                                        newData
                                    );

  });
window.alert("Set Name");
  });

Compiled & loaded - it updated the “name” (you can see if you double click - its set to blah) - but the name is not displayed.
(I cant see an obvious way to attach the files - but I hope thats clear enough ? )


#11

You can always for fork projects on GitHub, make the changes and commit these changes onto your own fork or branch. It is much easier for us to look into these branches than to rebuild examples from instructions.


#12

I dont normally github - but I’ve tried …

in the “modeler” example, do the npm install/grunt, load the dist/index.html
Click “create new diagram”
Click “SetName”

You see no update on the diagram - double click on the circle and you can see it was set to “blah”…


#13

Thank you for putting the example up! I can confirm that you found a bug in the modeler.

We set labels to hidden, if they are empty but do not to reset them to visible if the label is updated via modeling#updateProperties().

A workaround is setting the element labels hidden attribute to false yourself:

var element = event.element;
var labelElement = element.label;

// we are changing text, force rendering it
if (labelElement) {
  labelElement.hidden = false;
}

// modeling ....

#14

Fixed with next release.


#15

Cheers.
As a matter of interest - should I be setting “name” or businessObject.name ?

Only - setting “name”, then saving and reloading is causing issues with the display labels - they are in the wrong place - and “name” is no longer set on the node itself (but is set in the businessObject.name)…


#16

A diagram element does not have a name itself, so setting it is meaningless.

A BPMN element has a name, and thus a text to be displayed. If you would like to update the name, set it on the respective BPMN element.


#17

I think i’ve got it mostly sorted now - thanks…