#552 ✓ resolved
David Humphrey

Provide good docs and examples to plugin authors on the meaning of |this| within plugin functions

Reported by David Humphrey | June 2nd, 2011 @ 03:00 PM | in 0.7

Plugins put their instance data on an options object, which we pass to every plugin function (e.g., _setup(options)). From within the scope of these functions, it is often desirable to get access to the Popcorn instance for this track. For example, you might want to pause/seek the video, so you need to access the .media property, or you might want to grab the media element's containing div in order to style it.

It's possible to do this today using |this|. The trouble I have with this method is that it's not clear what |this| will be at runtime to plugin authors (ignoring the fact that |this| is difficult for many junior JS developers already). I'd like to see us provide an explicit way for the Popcorn instance to be reached from any plugin function.

I can see two ways to do this:

1) pass an instance or popcorn argument to each function along with options, so you'd have _setup(popcorn, options).

2) put a reference to the popcorn instance on the options object when it gets registered. This would mean you could have _setup(options) { var video = options.popcorn.media; ...}

I think 2) is the best way to go, with the core doing this behind the scenes, since it means we don't have to break the plugin API. I'm not sure if you want to name it .instance or .popcorn or whatever, and it doesn't really matter.

Comments and changes to this ticket

  • Scott Downe

    Scott Downe June 2nd, 2011 @ 03:06 PM

    I am also currently asking myself what to do in this case as well, regarding trackliner, which has plugins that are almost exactly the same as popcorn's.

    Few things, anyone else know of any other APIs that do something like this, and we could see what they are doing.

    The "ignoring the fact that |this| is difficult for many junior JS developers already" is a HUGE argument for this ticket's existence, and also why I am leaning towards number 2.

    Number 2 also doesn't break any API.

    Also, we should not break the current use of |this|, just add a more explicit way to get there.

  • David Humphrey

    David Humphrey June 2nd, 2011 @ 03:08 PM

    Right, we don't want to monkey with the current meaning of |this|, nor change how the core works. We're just surfacing an API for plugin authors that's not shrouded in mystery.

  • Rick

    Rick June 2nd, 2011 @ 07:17 PM

    I've documented the existing "explicit path to the Popcorn instance": http://popcornjs.org/API/popcorn

  • Rick

    Rick June 11th, 2011 @ 11:03 AM

    • Milestone cleared.
    • State changed from “feature-request” to “blocked”

    Blocked by #567

    If Popcorn provides an explicit reference to its own current instance (which includes a DOM element) will throw TypeErrors when track events (which include the options object) are serialized (with JSON.stringify()) for HTML export embeds by Butter. Credit to Scott for discovering this in #567

    Here is a reduced test case for fun: http://jsfiddle.net/rwaldron/KDxED/2/

  • David Humphrey

    David Humphrey June 11th, 2011 @ 11:09 AM

    • Milestone set to 0.7
    • State changed from “blocked” to “home-page”
    • Title changed from “Provide an explicit path to the Popcorn instance for plugin track objects” to “Provide good docs and examples to plugin authors on the meaning of |this| within plugin functions”
    • Milestone order changed from “39” to “0”

    Good point. Morphing this ticket into a doc ticket.

  • Rick

    Rick June 11th, 2011 @ 11:30 AM

    I propose that we create a narrated documentation experience, similar to this: http://dev.popcornjs.org/documentation (awesome!!!)

  • Brett Gaylor

    Brett Gaylor June 13th, 2011 @ 11:44 AM

    Yes, I think this should be the next one we do in this style.

    I added a few others off the top of my head here:

    http://etherpad.mozilla.com:9000/popcorndocs

    Please feel free to add. They were fairly easy to do so we should try and do a few for 0.7
    bg

  • Rick

    Rick June 18th, 2011 @ 11:34 AM

    • State changed from “home-page” to “assigned”
    • Assigned user set to “Rick”
  • Rick

    Rick June 18th, 2011 @ 11:44 AM

    • State changed from “assigned” to “peer-review-requested”
    • Assigned user changed from “Rick” to “David Humphrey”

    http://popcornjs.org/API/popcorn

    Dave, any feedback or ideas that you think will be helpful to illustrate this would be awesome - thanks!

  • David Humphrey

    David Humphrey June 23rd, 2011 @ 10:28 AM

    • State changed from “peer-review-requested” to “resolved”

    This is good. Is that page top-level linked?

  • Rick

    Rick June 23rd, 2011 @ 10:41 AM

    It can be and I'll make sure it is.

Please Sign in or create a free account to add a new ticket.

With your very own profile, you can contribute to projects, track your activity, watch tickets, receive and update tickets through your email and much more.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile »

Popcorn.js is an HTML5 video framework that lets you bring elements of the web into your videos.

Popcorn.js is a project of Web Made Movies, Mozilla's Open Video Lab.

Shared Ticket Bins

Pages