wp.media Tutorials, and wp.Backbone. Subviews

I'm still working on reading through the WP media code, but found several references that have helped.

Most of the tutorials are similar: how to set up and invoke wp.media() to open a dialog box to select an image. Fortunately, that is my use case, but I have another use case, which is to implement a dialog box for a simple form.

Here are the various tutorials I found online:

wp.media

How to Add the WP 3.5 Media Manager Interface

wp.template for front end templating

Building a Better Image Widget

Using the 3.5 Media Uploader within plugins

How to implement the WordPress media manager in your own plugin/theme

WP Core blog posts

How to use WordPress 3.5 Media Uploader in Theme Options

wp.Backbone Subviews

WordPress implements a small extension to Backbone Views that allows views to have subviews. A subview is a view within a view, and when the outer view is rendered, the subviews are also rendered.

This is a general expalation of subview:

Backbone View Patterns

The gist of that document is code:

render: function() {
    this.collection.each(function(comment){
        if (comment.get('type') == 'video') {
            this.$el.append( new CommentVideoView({ model: comment }) );
        } else {
            this.$el.append( new CommentView({ model: comment }) );
        }
    }, this);
}

When Backbone calls render(), you also render the subviews. The article then goes on to describe a management strategy for subviews, so that views don't need to be permanently wired into the code.

The technique is to maintain a property, "views", that is an array of subviews and selectors where they attach. Then, when it's time to render, the views are created, and appended.

initialize: function(){
    //- set views placeholder
    this.views = [];
},

render: function() {
    //- clean views before rendering new ones
    this.destroyViews();
    //- create new views
    this.views = this.collection.map(this.createView, this);
    this.$el.append( _.map(this.views, this.getDom, this) );
},

wp.Backbone.View is not Backbone.View

wp.Backbone.View extends Backbone.View by adding a sub-views feature.

wp.Backbone.View code to use a subview:

    // Create the views.
    var view = new ViewConstructor({
        // specify an existing element in the document to bind the view to.
        el: '.view-1-container'
    });
    var subview = new SubviewConstructor();
    view.views.set( '.subview-container', subview );

That code's from the Media Guide plugin.
Basically, every view has a property, views, that is a subview manager object. The class is wp.Backbone.Subviews in the file wp-includes/js/wp-backbone.js. It's less than 400 lines and not hard to understand.

To attach a subview:

view.views.set( selector, subview_instance );

Mark Jaquith talk notes.

Code for the talk.

A general presentation on Backbone for WordPress.