gistfile1.js

// I dislike the pattern of using string action names instead
// of creating instances and having instance methods...
var videoPlayerElement = $('#playerContainer').videoPlayer({
	loop: true
}).videoPlayer('setSrc', 'whatever.mp4').videoPlayer('play');

// and later...
videoPlayerElement.videoPlayer('stop');


// I see it a lot in jQuery plugins. I guess it's convention,
// but I much prefer getting an instance of the 'player'

var videoPlayer = $('#playerContainer').videoPlayer('whatever.mp4', {
	loop: true
}).play();

// and later
videoPlayer.stop();

Indeed, trigger just used above for brevity :-) In reality I also namespace the events too ( i.e. elem.triggerHandler('stop.myplugin') ) to avoid collisions.

But I do agree with you - returning a non-jQuery object is a much more 'JavaScript' way of doing things, it's just that a lot of people use jQuery plugins who are not necessarily that good with plain ol' JS and who (in my experience) have the expectation that all the plugins are jQuery-chainable, and see them as 'broken' if that pattern is not adhered to.

The jQuery tools guys would agree, they solved the chain problem by storing the api object in the data() attribute.

they appear to have taken a lot of heat in the past for breaking with the jQuery UI convention though, even though in my opinion the tools model makes far more sense.

using their model your example would become:

var videoPlayer = $('#playerContainer').videoPlayer('whatever.mp4', {
    loop: true,
    api: true
}).play();

// and later
videoPlayer.stop();

the player object is always accessible even if you fail to keep track of it

var videoPlayer = $('#playerContainer').data('videoPlayer');

and you still get the chaining

$('#playerContainer').videoPlayer('whatever.mp4', {
    loop: true
}).show();

Ahh well, glad to know I'm not alone when it comes to my opinion of that style.

I don't see why videoPlayer() shouldn't return an object, other jQuery methods like .offset() return objects... but then I guess those objects don't have methods.

Actually, this pattern causes API confusion in jQuery UI...

$("#dialog").dialog().hide();

Because dialog() creates elements outside $("#dialog"), hiding #dialog means parts of the dialog stay visible.