Reading the API

JW

I have a question about how to correctly read the API. I'm using the edit() as an example along with the Editor Duplicate Button example. Specifically this portion where edit() is called:

action: function ( e, dt, node, config ) {
    editor
        .edit( table.rows( {selected: true} ).indexes(), {
            title: 'Duplicate record',
            buttons: 'Create from existing'
         } )
         .mode( 'create' );
     }
}

I realize that the first parameter to the edit() method is the 'items' parameter and in hindsight, the 2nd parameter passed is an 'options' object. From the API, the 2nd parameter is listed as the 'show' option. But in the example above, it's obvious that the 2nd parameter being passed is the 'options' object (the 3rd parameter in the API). My questions are as follows:

1. In less obvious circumstances, how would I know that I can pass the 3rd parameter in as the 2nd parameter? Is it because the 2nd parameter in the edit() API (show) is listed as optional?
2. In the example above in regards to the call to rows(), the 'selected' parameter is a boolean but passed in as an object. Whereas the edit() API for the 2nd parameter for 'show' is a boolean but you don't need to pass in an object but simply state 'true' or 'false'. How do I know from the API whether to just pass 'true' or 'false' or pass in an object as is done in the rows() call above?

Thanks in advance for any help you can provide.
J

colin

Hi J,

Yep, I see what you're saying. In my experience, optional parameters tend to go at the end of a function prototype (Python, that is).

I guess as you say, the edit is the middle parameter, is optional, and has a default value, so it can be omitted.

Regarding table().rows() (see API reference page here) that's different. Yep, 'selected' is a boolean, but it's one of the selector-modifiers options expected by that method. And as can be seen in that link, selector-modifiers is an object.

Hope that makes it a bit clearer!

Cheers,

Colin

allan

Just to add to what column says, the square brackets show what is optional (this is similar to the jQuery documentation) - so taking the edit() documentation it says:

edit( items [, show ] [, options ] )

So it could be:

• edit( items )
• edit( items, show )
• edit( items, options )
• edit( items, show, options )

If it were shown as: edit( items [, show [, options ] ] ), then if you wanted to give the options you'd also have to give the show parameter. That isn't the case here though.

Does that make sense?

Allan

JW

@colin and @allan my apologies for not getting back to you sooner. Thank you very much for your responses. I had a nice, thorough response written for you and then accidently clicked an API link in the response and it erased it...all. I wish I had time to rewrite it but I don't. In short, yes, your explanations helped. Not sure I fully understand but I think that will come with time. Thank you for, both, for taking the time to respond and help me out.