confusing API with regards to error callbacks
I just spent a lot of time with the basic JW Player API (setup) when I tried to set up some callbacks and I wanted to share my experience.
What I tried to do: I wanted to use the onSetupError callback as documented.
final solution:
var player = jwplayer(contentElement).setup(jwOpts);
player.onSetupError(this.handlePlayerError);
In hindsight I see two issues which confused me:
1. It is possible to set up an onReady callback in the setup options.
For example:
jwOpts = {
...
events: {'onReady': this.handlePlayerReady},
...
}
but it is not possible doing the same for onSetupError. If you don't support it (I suspect support for events in setup might be meant as a backwards-compat for JW Player 5 and onSetupError is v6+) I'd like to see an error message if someone sends a callback for an unknown/unsupported event. (I acknowledge that this is uncommon in JS but I think "fail fast" is a good practice.)
I used the approach above because I was used to it with JW Player 5 and to me it seemed like the best way because I assumed that I avoid every possible race condition if the listener is added immediately in setup().
Second issue:
The object returned by the "jwplayer()" call is not the same as the one returned by .setup() but provides an "onSetupError" method which has no effect - but does not bail out either.
Initially I did (simplified):
var player = jwplayer(contentElement);
player.setup(jwOpts);
player.onSetupError(this.handlePlayerError);
I see two problems here:
1. In jQuery it is very common just to return a this argument if the operation is not a selector. I assumed that this is also the case for JW Player as "setup()" seems to be just some initialization but should not change the actual object. That assumption was wrong.
2. If the returned instance has to be different for some reason please make it fail for unsupported operations! For example calling ".onSetupError()" should raise an exception (fail fast again) so I notice the problem immediately.
Also I was unable to find an example for onSetupError in the support articles.
now what is wr
this._jwplayer = jwplayer(contentElement).setup(jwOpts);
this._jwplayer.onSetupError(this.handlePlayerError);
