Editor mode vs action terminology

Loren Maxwell

This is admittedly trivial, but I've been meaning to mention it and I'm virtually sitting in a boring staff meeting so I thought this might be a good time

The API has mode(), which is either create, edit, or remove.

But for events, such as open, the parameters are function( e, mode, action ), where the mode is main, inline, or bubble.

The action parameter is where the create, edit, or remove are found.

There have been a couple of times I've programed an event where I've done:

editor.on('open', function (e, mode, action) {
    // Should be "action == 'edit'" but the
    // api method "mode()" has thrown me off
    if (mode == 'edit') {
        ...
    }
});

The inconsistency always makes me wonder if it wouldn't be better to use the terminology from the event fields and have an action() method that will eventually replace the mode() method?

allan

Hah - an excellent use for a meeting .

Darn, I'd hoped to avoid an inconsistency in naming like that, but yes, I can see that it would be confusing there. I'll add an action() method as you suggest and see about tidying up the event documentation.

Thanks for flagging this up!

Allan

Loren Maxwell

Thanks, @allan -- I haven't checked all the event documentation, but action() would make it consistent with the few I checked.

I think another possibility that would avoid additional programming and preserve backward compatibility would be to keep mode() as is and change the parameters in the event documentation to something like:

// Note parameters are now documented as
// (e, method, mode) vs (e, mode, action)
editor.on('open', function (e, method, mode) {

   switch(method) {
       case 'main':
       case 'inline':
       case 'bubble':
       break;
   }

   switch(mode) {
       case 'create':
       case 'edit':
       case 'remove':
       break;
   }

});

I know I can use the (e, method, mode) or whatever else for the parameter names in my own code, but I usually use the ones from the event documentation to make sure I'm reminded of and passing the correct parameters.

Either way, I trust you'll work out a solution!

allan

I think the tweak to the naming in the documentation is the best solution for now - thank you for suggesting that. I've just committed that change (it might be a little while before it is on the site though, as I've put it in a development branch).

I can still add an action() method if it is needed (or possibly call it method() now), but I'm not sure how much it would be used...

Allan

Loren Maxwell

Thanks, @allan!

Changing the documentation seems to be the easiest and best solution!

Loren Maxwell

Just wanted to expand on this a little to resolve another name collision.

---

There is a display that sets the display controller.

There's also an unrelated display method that shows whether the form is opened in the main, inline, or bubble "method" (using the terminology from the above discussion).

---

First suggestion
Rename display to method (and only use as a getter) to match the naming convention from above, so that:
method = main, inline, bubble
mode = create, edit, remove

This would align with the tweaked documentation for events.

---

Second suggestion
Do away with display altogether to avoid conflation with display.

A new method would serve as a getter for main, inline, or bubble.

As a setter, passing true or false to display currently opens or closes the form, but open and close provide those same functions (and I'm guessing are the predominate ways a form is opened/closed through the api).

This isolates the display terminology (i.e., display) to discussion of the display controller.

allan

Another boring meeting? .

Excellent point to tidy up the terminology here as well. I've been working on DataTables 3 / Editor 3 recently, so this will be a good thing to add. I'll post back when done.

Allan