Change custom serialization to use custom models, rather than transmitting the serializer name across the wire

This separates the kernel and the js much more cleanly, and doesn't use as much space on the wire as well!

IPython/html/static/widgets/js/init.js

@@ -1,34 +1,49
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/manager",
     "widgets/js/widget_link",
     "widgets/js/widget_bool",
     "widgets/js/widget_button",
     "widgets/js/widget_box",
     "widgets/js/widget_float",
     "widgets/js/widget_image",
     "widgets/js/widget_int",
     "widgets/js/widget_output",
     "widgets/js/widget_selection",
     "widgets/js/widget_selectioncontainer",
     "widgets/js/widget_string",
-], function(widgetmanager, linkModels) {
-    for (var target_name in linkModels) {
-        if (linkModels.hasOwnProperty(target_name)) {
-            widgetmanager.WidgetManager.register_widget_model(target_name, linkModels[target_name]);
-        }
+], function(widgetmanager) {
+
+
+    /**
+     * From https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith
+     * Can be removed with the string endsWith function is implemented in major browsers
+     */
+    var endsWith = function(target, searchString, position) {
+        var subjectString = target.toString();
+        if (position === undefined || position > subjectString.length) {
+            position = subjectString.length;
     }
+        position -= searchString.length;
+        var lastIndex = subjectString.indexOf(searchString, position);
+        return lastIndex !== -1 && lastIndex === position;
+    };
 
-    // Register all of the loaded views with the widget manager.
-    for (var i = 2; i < arguments.length; i++) {
-        for (var target_name in arguments[i]) {
-            if (arguments[i].hasOwnProperty(target_name)) {
-                widgetmanager.WidgetManager.register_widget_view(target_name, arguments[i][target_name]);
+    // Register all of the loaded models and views with the widget manager.
+    for (var i = 1; i < arguments.length; i++) {
+        var module = arguments[i];
+        for (var target_name in module) {
+            if (module.hasOwnProperty(target_name)) {
+                if (endsWith(target_name, "View")) {
+                    widgetmanager.WidgetManager.register_widget_view(target_name, module[target_name]);
+                } else if (endsWith(target_name, "Model")) {
+                    widgetmanager.WidgetManager.register_widget_model(target_name, module[target_name]);
+                }
             }
         }
     }
 
     return {'WidgetManager': widgetmanager.WidgetManager}; 
 });

IPython/html/static/widgets/js/widget.js

@@ -1,824 +1,780
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define(["widgets/js/manager",
         "underscore",
         "backbone",
         "jquery",
         "base/js/utils",
         "base/js/namespace",
 ], function(widgetmanager, _, Backbone, $, utils, IPython){
     "use strict";
 
     var WidgetModel = Backbone.Model.extend({
         constructor: function (widget_manager, model_id, comm) {
             /**
              * Constructor
              *
              * Creates a WidgetModel instance.
              *
              * Parameters
              * ----------
              * widget_manager : WidgetManager instance
              * model_id : string
              *      An ID unique to this model.
              * comm : Comm instance (optional)
              */
             this.widget_manager = widget_manager;
             this.state_change = Promise.resolve();
             this._buffered_state_diff = {};
             this.pending_msgs = 0;
             this.msg_buffer = null;
             this.state_lock = null;
             this.id = model_id;
             this.views = {};
-            this.serializers = {};
             this._resolve_received_state = {};
 
             if (comm !== undefined) {
                 // Remember comm associated with the model.
                 this.comm = comm;
                 comm.model = this;
 
                 // Hook comm messages up to model.
                 comm.on_close($.proxy(this._handle_comm_closed, this));
                 comm.on_msg($.proxy(this._handle_comm_msg, this));
 
                 // Assume the comm is alive.
                 this.set_comm_live(true);
             } else {
                 this.set_comm_live(false);
             }
 
             // Listen for the events that lead to the websocket being terminated.
             var that = this;
             var died = function() {
                 that.set_comm_live(false);
             };
             widget_manager.notebook.events.on('kernel_disconnected.Kernel', died);
             widget_manager.notebook.events.on('kernel_killed.Kernel', died);
             widget_manager.notebook.events.on('kernel_restarting.Kernel', died);
             widget_manager.notebook.events.on('kernel_dead.Kernel', died);
 
             return Backbone.Model.apply(this);
         },
 
         send: function (content, callbacks, buffers) {
             /**
              * Send a custom msg over the comm.
              */
             if (this.comm !== undefined) {
                 var data = {method: 'custom', content: content};
                 this.comm.send(data, callbacks, {}, buffers);
                 this.pending_msgs++;
             }
         },
 
         request_state: function(callbacks) {
             /** 
              * Request a state push from the back-end.
              */
             if (!this.comm) {
                 console.error("Could not request_state because comm doesn't exist!");
                 return;
             }
 
             var msg_id = this.comm.send({method: 'request_state'}, callbacks || this.widget_manager.callbacks());
 
             // Promise that is resolved when a state is received
             // from the back-end.
             var that = this;
             var received_state = new Promise(function(resolve) {
                 that._resolve_received_state[msg_id] = resolve;
             });
             return received_state;
         },
 
         set_comm_live: function(live) {
             /** 
              * Change the comm_live state of the model.
              */
             if (this.comm_live === undefined || this.comm_live != live) {
                 this.comm_live = live;
                 this.trigger(live ? 'comm:live' : 'comm:dead', {model: this});
             }
         },
 
         close: function(comm_closed) {
             /**
              * Close model
              */
             if (this.comm && !comm_closed) {
                 this.comm.close();
             }
             this.stopListening();
             this.trigger('destroy', this);
             delete this.comm.model; // Delete ref so GC will collect widget model.
             delete this.comm;
             delete this.model_id; // Delete id from model so widget manager cleans up.
             _.each(this.views, function(v, id, views) {
                 v.then(function(view) {
                     view.remove();
                     delete views[id];
                 });
             });
         },
 
         _handle_comm_closed: function (msg) {
             /** 
              * Handle when a widget is closed.
              */
             this.trigger('comm:close');
             this.close(true);
         },
 
         _handle_comm_msg: function (msg) {
             /**
              * Handle incoming comm msg.
              */
             var method = msg.content.data.method;
             
             var that = this;
             switch (method) {
                 case 'update':
                     this.state_change = this.state_change
                         .then(function() {
                             var state = msg.content.data.state || {};
                             var buffer_keys = msg.content.data.buffers || [];
                             var buffers = msg.buffers || [];
-                            var metadata = msg.content.data.metadata || {};
-                            var i,k;
                             for (var i=0; i<buffer_keys.length; i++) {
-                                k = buffer_keys[i];
-                                state[k] = buffers[i];
+                                state[buffer_keys[i]] = buffers[i];
                             }
 
-                            // for any metadata specifying a deserializer, set the
-                            // state to a promise that resolves to the deserialized version
-                            // also, store the serialization function for the attribute
-                            var keys = Object.keys(metadata);
-                            for (var i=0; i<keys.length; i++) {
-                                k = keys[i];
-                                if (metadata[k] && metadata[k].serialization) {
-                                    that.serializers[k] = utils.load_class.apply(that,
-                                                                                 metadata[k].serialization);
-                                    state[k] = that.deserialize(that.serializers[k], state[k]);
+                            // deserialize fields that have custom deserializers
+                            var serializers = that.constructor.serializers;
+                            if (serializers) {
+                                for (var k in state) {
+                                    if (serializers[k] && serializers[k].deserialize) {
+                                        state[k] = (serializers[k].deserialize)(state[k], that);
+                                    }
                                 }
                             }
                             return utils.resolve_promises_dict(state);
                         }).then(function(state) {
                             return that.set_state(state);
                         }).catch(utils.reject("Couldn't process update msg for model id '" + String(that.id) + "'", true))
                         .then(function() {
                             var parent_id = msg.parent_header.msg_id;
                             if (that._resolve_received_state[parent_id] !== undefined) {
                                 that._resolve_received_state[parent_id].call();
                                 delete that._resolve_received_state[parent_id];
                             }
                         }).catch(utils.reject("Couldn't resolve state request promise", true));
                     break;
                 case 'custom':
                     this.trigger('msg:custom', msg.content.data.content, msg.buffers);
                     break;
                 case 'display':
                     this.state_change = this.state_change.then(function() {
                         that.widget_manager.display_view(msg, that);
                     }).catch(utils.reject('Could not process display view msg', true));
                     break;
             }
         },
 
-        deserialize: function(serializer, value) {
-            // given a serializer dict and a value,
-            // return a promise for the deserialized value
-            var that = this;
-            return serializer.then(function(s) {
-                if (s.deserialize) {
-                    return s.deserialize(value, that);
-                } else {
-                    return value;
-                }
-            });
-        },
-
         set_state: function (state) {
             var that = this;
             // Handle when a widget is updated via the python side.
             return new Promise(function(resolve, reject) {
                 that.state_lock = state;
                 try {
                     WidgetModel.__super__.set.call(that, state);
                 } finally {
                     that.state_lock = null;
                 }
                 resolve();
             }).catch(utils.reject("Couldn't set model state", true));
         },
 
         get_state: function() {
             // Get the serializable state of the model.
             // Equivalent to Backbone.Model.toJSON()
             return _.clone(this.attributes);
         },
         
         _handle_status: function (msg, callbacks) {
             /**
              * Handle status msgs.
              *
              * execution_state : ('busy', 'idle', 'starting')
              */
             if (this.comm !== undefined) {
                 if (msg.content.execution_state ==='idle') {
                     // Send buffer if this message caused another message to be
                     // throttled.
                     if (this.msg_buffer !== null &&
                         (this.get('msg_throttle') || 3) === this.pending_msgs) {
                         var data = {method: 'backbone', sync_method: 'update', sync_data: this.msg_buffer};
                         this.comm.send(data, callbacks);
                         this.msg_buffer = null;
                     } else {
                         --this.pending_msgs;
                     }
                 }
             }
         },
 
         callbacks: function(view) {
             /**
              * Create msg callbacks for a comm msg.
              */
             var callbacks = this.widget_manager.callbacks(view);
 
             if (callbacks.iopub === undefined) {
                 callbacks.iopub = {};
             }
 
             var that = this;
             callbacks.iopub.status = function (msg) {
                 that._handle_status(msg, callbacks);
             };
             return callbacks;
         },
 
         set: function(key, val, options) {
             /**
              * Set a value.
              */
             var return_value = WidgetModel.__super__.set.apply(this, arguments);
 
             // Backbone only remembers the diff of the most recent set()
             // operation.  Calling set multiple times in a row results in a 
             // loss of diff information.  Here we keep our own running diff.
             this._buffered_state_diff = $.extend(this._buffered_state_diff, this.changedAttributes() || {});
             return return_value;
         },
 
         sync: function (method, model, options) {
             /**
              * Handle sync to the back-end.  Called when a model.save() is called.
              *
              * Make sure a comm exists.
 
              * Parameters
              * ----------
              * method : create, update, patch, delete, read
              *   create/update always send the full attribute set
              *   patch - only send attributes listed in options.attrs, and if we are queuing
              *     up messages, combine with previous messages that have not been sent yet
              * model : the model we are syncing
              *   will normally be the same as `this`
              * options : dict
              *   the `attrs` key, if it exists, gives an {attr: value} dict that should be synced,
              *   otherwise, sync all attributes
              * 
              */
             var error = options.error || function() {
                 console.error('Backbone sync error:', arguments);
             };
             if (this.comm === undefined) {
                 error();
                 return false;
             }
 
             var attrs = (method === 'patch') ? options.attrs : model.get_state(options);
 
             // the state_lock lists attributes that are currently be changed right now from a kernel message
             // we don't want to send these non-changes back to the kernel, so we delete them out of attrs
             // (but we only delete them if the value hasn't changed from the value stored in the state_lock
             if (this.state_lock !== null) {
                 var keys = Object.keys(this.state_lock);
                 for (var i=0; i<keys.length; i++) {
                     var key = keys[i];
                     if (attrs[key] === this.state_lock[key]) {
                         delete attrs[key];
                     }
                 }
             }
             
             if (_.size(attrs) > 0) {
 
                 // If this message was sent via backbone itself, it will not
                 // have any callbacks.  It's important that we create callbacks
                 // so we can listen for status messages, etc...
                 var callbacks = options.callbacks || this.callbacks();
 
                 // Check throttle.
                 if (this.pending_msgs >= (this.get('msg_throttle') || 3)) {
                     // The throttle has been exceeded, buffer the current msg so
                     // it can be sent once the kernel has finished processing 
                     // some of the existing messages.
                     
                     // Combine updates if it is a 'patch' sync, otherwise replace updates
                     switch (method) {
                         case 'patch':
                             this.msg_buffer = $.extend(this.msg_buffer || {}, attrs);
                             break;
                         case 'update':
                         case 'create':
                             this.msg_buffer = attrs;
                             break;
                         default:
                             error();
                             return false;
                     }
                     this.msg_buffer_callbacks = callbacks;
 
                 } else {
                     // We haven't exceeded the throttle, send the message like 
                     // normal.
                     this.send_sync_message(attrs, callbacks);
                     this.pending_msgs++;
                 }
             }
             // Since the comm is a one-way communication, assume the message 
             // arrived.  Don't call success since we don't have a model back from the server
             // this means we miss out on the 'sync' event.
             this._buffered_state_diff = {};
         },
 
 
         send_sync_message: function(attrs, callbacks) {
             // prepare and send a comm message syncing attrs
             var that = this;
             // first, build a state dictionary with key=the attribute and the value
             // being the value or the promise of the serialized value
-            var state_promise_dict = {};
-            var keys = Object.keys(attrs);
-            for (var i=0; i<keys.length; i++) {
-                // bind k and v locally; needed since we have an inner async function using v
-                (function(k,v) {
-                    if (that.serializers[k]) {
-                        state_promise_dict[k] = that.serializers[k].then(function(f) {
-                            if (f.serialize) {
-                                return f.serialize(v, that);
-                            } else {
-                                return v;
+            var serializers = this.constructor.serializers;
+            if (serializers) {
+                for (k in attrs) {
+                    if (serializers[k] && serializers[k].serialize) {
+                        attrs[k] = (serializers[k].serialize)(attrs[k], this);
                             }
-                        })
-                    } else {
-                        state_promise_dict[k] = v;
                     }
-                })(keys[i], attrs[keys[i]])
             }
-            utils.resolve_promises_dict(state_promise_dict).then(function(state) {
+            utils.resolve_promises_dict(attrs).then(function(state) {
                 // get binary values, then send
                 var keys = Object.keys(state);
                 var buffers = [];
                 var buffer_keys = [];
                 for (var i=0; i<keys.length; i++) {
                     var key = keys[i];
                     var value = state[key];
                     if (value.buffer instanceof ArrayBuffer
                         || value instanceof ArrayBuffer) {
                         buffers.push(value);
                         buffer_keys.push(key);
                         delete state[key];
                     }
                 }
                 that.comm.send({method: 'backbone', sync_data: state, buffer_keys: buffer_keys}, callbacks, {}, buffers);
             }).catch(function(error) {
                 that.pending_msgs--;
                 return (utils.reject("Couldn't send widget sync message", true))(error);
             });
         },
         
-        serialize: function(model, attrs) {
-            // Serialize the attributes into a sync message
-            var keys = Object.keys(attrs);            
-            var key, value;
-            var buffers, metadata, buffer_keys, serialize;
-            for (var i=0; i<keys.length; i++) {
-                key = keys[i];
-                serialize = model.serializers[key];
-                if (serialize && serialize.serialize) {
-                    attrs[key] = serialize.serialize(attrs[key]);
-                }
-            }
-        },
-
         save_changes: function(callbacks) {
             /**
              * Push this model's state to the back-end
              *
              * This invokes a Backbone.Sync.
              */
             this.save(this._buffered_state_diff, {patch: true, callbacks: callbacks});
         },
 
         on_some_change: function(keys, callback, context) {
             /**
              * on_some_change(["key1", "key2"], foo, context) differs from
              * on("change:key1 change:key2", foo, context).
              * If the widget attributes key1 and key2 are both modified, 
              * the second form will result in foo being called twice
              * while the first will call foo only once.
              */
             this.on('change', function() {
                 if (keys.some(this.hasChanged, this)) {
                     callback.apply(context);
                 }
             }, this);
 
         },
 
         toJSON: function(options) {
             /**
              * Serialize the model.  See the types.js deserialization function
              * and the kernel-side serializer/deserializer
              */
             return "IPY_MODEL_"+this.id;
         }
     });
     widgetmanager.WidgetManager.register_widget_model('WidgetModel', WidgetModel);
 
 
     var WidgetView = Backbone.View.extend({
         initialize: function(parameters) {
             /**
              * Public constructor.
              */
             this.model.on('change',this.update,this);
 
             // Bubble the comm live events.
             this.model.on('comm:live', function() {
                 this.trigger('comm:live', this);
             }, this);
             this.model.on('comm:dead', function() {
                 this.trigger('comm:dead', this);
             }, this);
 
             this.options = parameters.options;
             this.on('displayed', function() { 
                 this.is_displayed = true; 
             }, this);
         },
 
         update: function(){
             /**
              * Triggered on model change.
              *
              * Update view to be consistent with this.model
              */
         },
 
         create_child_view: function(child_model, options) {
             /**
              * Create and promise that resolves to a child view of a given model
              */
             var that = this;
             options = $.extend({ parent: this }, options || {});
             return this.model.widget_manager.create_view(child_model, options).catch(utils.reject("Couldn't create child view", true));
         },
 
         callbacks: function(){
             /**
              * Create msg callbacks for a comm msg.
              */
             return this.model.callbacks(this);
         },
 
         render: function(){
             /**
              * Render the view.
              *
              * By default, this is only called the first time the view is created
              */
         },
 
         send: function (content, buffers) {
             /**
              * Send a custom msg associated with this view.
              */
             this.model.send(content, this.callbacks(), buffers);
         },
 
         touch: function () {
             this.model.save_changes(this.callbacks());
         },
 
         after_displayed: function (callback, context) {
             /**
              * Calls the callback right away is the view is already displayed
              * otherwise, register the callback to the 'displayed' event.
              */
             if (this.is_displayed) {
                 callback.apply(context);
             } else {
                 this.on('displayed', callback, context);
             }
         },
 
         remove: function () {
             // Raise a remove event when the view is removed.
             WidgetView.__super__.remove.apply(this, arguments);
             this.trigger('remove');
         }
     });
 
 
     var DOMWidgetView = WidgetView.extend({
         initialize: function (parameters) {
             /**
              * Public constructor
              */
             DOMWidgetView.__super__.initialize.apply(this, [parameters]);
             this.model.on('change:visible', this.update_visible, this);
             this.model.on('change:_css', this.update_css, this);
 
             this.model.on('change:_dom_classes', function(model, new_classes) {
                 var old_classes = model.previous('_dom_classes');
                 this.update_classes(old_classes, new_classes);
             }, this);
 
             this.model.on('change:color', function (model, value) { 
                 this.update_attr('color', value); }, this);
 
             this.model.on('change:background_color', function (model, value) { 
                 this.update_attr('background', value); }, this);
 
             this.model.on('change:width', function (model, value) { 
                 this.update_attr('width', value); }, this);
 
             this.model.on('change:height', function (model, value) { 
                 this.update_attr('height', value); }, this);
 
             this.model.on('change:border_color', function (model, value) { 
                 this.update_attr('border-color', value); }, this);
 
             this.model.on('change:border_width', function (model, value) { 
                 this.update_attr('border-width', value); }, this);
 
             this.model.on('change:border_style', function (model, value) { 
                 this.update_attr('border-style', value); }, this);
 
             this.model.on('change:font_style', function (model, value) { 
                 this.update_attr('font-style', value); }, this);
 
             this.model.on('change:font_weight', function (model, value) { 
                 this.update_attr('font-weight', value); }, this);
 
             this.model.on('change:font_size', function (model, value) { 
                 this.update_attr('font-size', this._default_px(value)); }, this);
 
             this.model.on('change:font_family', function (model, value) { 
                 this.update_attr('font-family', value); }, this);
 
             this.model.on('change:padding', function (model, value) { 
                 this.update_attr('padding', value); }, this);
 
             this.model.on('change:margin', function (model, value) { 
                 this.update_attr('margin', this._default_px(value)); }, this);
 
             this.model.on('change:border_radius', function (model, value) { 
                 this.update_attr('border-radius', this._default_px(value)); }, this);
 
             this.after_displayed(function() {
                 this.update_visible(this.model, this.model.get("visible"));
                 this.update_classes([], this.model.get('_dom_classes'));
                 
                 this.update_attr('color', this.model.get('color'));
                 this.update_attr('background', this.model.get('background_color'));
                 this.update_attr('width', this.model.get('width'));
                 this.update_attr('height', this.model.get('height'));
                 this.update_attr('border-color', this.model.get('border_color'));
                 this.update_attr('border-width', this.model.get('border_width'));
                 this.update_attr('border-style', this.model.get('border_style'));
                 this.update_attr('font-style', this.model.get('font_style'));
                 this.update_attr('font-weight', this.model.get('font_weight'));
                 this.update_attr('font-size', this._default_px(this.model.get('font_size')));
                 this.update_attr('font-family', this.model.get('font_family'));
                 this.update_attr('padding', this.model.get('padding'));
                 this.update_attr('margin', this._default_px(this.model.get('margin')));
                 this.update_attr('border-radius', this._default_px(this.model.get('border_radius')));
 
                 this.update_css(this.model, this.model.get("_css"));
             }, this);
         },
 
         _default_px: function(value) {
             /**
              * Makes browser interpret a numerical string as a pixel value.
              */
             if (value && /^\d+\.?(\d+)?$/.test(value.trim())) {
                 return value.trim() + 'px';
             }
             return value;
         },
 
         update_attr: function(name, value) {
             /**
              * Set a css attr of the widget view.
              */
             this.$el.css(name, value);
         },
 
         update_visible: function(model, value) {
             /**
              * Update visibility
              */
             switch(value) {
                 case null: // python None
                     this.$el.show().css('visibility', 'hidden'); break;
                 case false:
                     this.$el.hide(); break;
                 case true:
                     this.$el.show().css('visibility', ''); break;
             }
          },
 
         update_css: function (model, css) {
             /**
              * Update the css styling of this view.
              */
             if (css === undefined) {return;}
             for (var i = 0; i < css.length; i++) {
                 // Apply the css traits to all elements that match the selector.
                 var selector = css[i][0];
                 var elements = this._get_selector_element(selector);
                 if (elements.length > 0) {
                     var trait_key = css[i][1];
                     var trait_value = css[i][2];
                     elements.css(trait_key ,trait_value);
                 }
             }
         },
 
         update_classes: function (old_classes, new_classes, $el) {
             /**
              * Update the DOM classes applied to an element, default to this.$el.
              */
             if ($el===undefined) {
                 $el = this.$el;
             }
             _.difference(old_classes, new_classes).map(function(c) {$el.removeClass(c);})
             _.difference(new_classes, old_classes).map(function(c) {$el.addClass(c);})
         },
 
         update_mapped_classes: function(class_map, trait_name, previous_trait_value, $el) {
             /**
              * Update the DOM classes applied to the widget based on a single
              * trait's value.
              *
              * Given a trait value classes map, this function automatically
              * handles applying the appropriate classes to the widget element
              * and removing classes that are no longer valid.
              *
              * Parameters
              * ----------
              * class_map: dictionary
              *  Dictionary of trait values to class lists.
              *  Example:
              *      {
              *          success: ['alert', 'alert-success'],
              *          info: ['alert', 'alert-info'],
              *          warning: ['alert', 'alert-warning'],
              *          danger: ['alert', 'alert-danger']
              *      };
              * trait_name: string
              *  Name of the trait to check the value of.
              * previous_trait_value: optional string, default ''
              *  Last trait value
              * $el: optional jQuery element handle, defaults to this.$el
              *  Element that the classes are applied to.
              */
             var key = previous_trait_value;
             if (key === undefined) {
                 key = this.model.previous(trait_name);
             }
             var old_classes = class_map[key] ? class_map[key] : [];
             key = this.model.get(trait_name);
             var new_classes = class_map[key] ? class_map[key] : [];
 
             this.update_classes(old_classes, new_classes, $el || this.$el);
         },
         
         _get_selector_element: function (selector) {
             /**
              * Get the elements via the css selector.
              */
             var elements;
             if (!selector) {
                 elements = this.$el;
             } else {
                 elements = this.$el.find(selector).addBack(selector);
             }
             return elements;
         },
 
         typeset: function(element, text){
             utils.typeset.apply(null, arguments);
         },
     });
 
 
     var ViewList = function(create_view, remove_view, context) {
         /**
          * - create_view and remove_view are default functions called when adding or removing views
          * - create_view takes a model and returns a view or a promise for a view for that model
          * - remove_view takes a view and destroys it (including calling `view.remove()`)
          * - each time the update() function is called with a new list, the create and remove
          *   callbacks will be called in an order so that if you append the views created in the
          *   create callback and remove the views in the remove callback, you will duplicate 
          *   the order of the list.
          * - the remove callback defaults to just removing the view (e.g., pass in null for the second parameter)
          * - the context defaults to the created ViewList.  If you pass another context, the create and remove
          *   will be called in that context.
          */
 
         this.initialize.apply(this, arguments);
     };
 
     _.extend(ViewList.prototype, {
         initialize: function(create_view, remove_view, context) {
             this._handler_context = context || this;
             this._models = [];
             this.views = []; // list of promises for views
             this._create_view = create_view;
             this._remove_view = remove_view || function(view) {view.remove();};
         },
 
         update: function(new_models, create_view, remove_view, context) {
             /**
              * the create_view, remove_view, and context arguments override the defaults
              * specified when the list is created.
              * after this function, the .views attribute is a list of promises for views
              * if you want to perform some action on the list of views, do something like
              * `Promise.all(myviewlist.views).then(function(views) {...});`
              */
             var remove = remove_view || this._remove_view;
             var create = create_view || this._create_view;
             context = context || this._handler_context;
             var i = 0;
             // first, skip past the beginning of the lists if they are identical
             for (; i < new_models.length; i++) {
                 if (i >= this._models.length || new_models[i] !== this._models[i]) {
                     break;
                 }
             }
             
             var first_removed = i;
             // Remove the non-matching items from the old list.
             var removed = this.views.splice(first_removed, this.views.length-first_removed);
             for (var j = 0; j < removed.length; j++) {
                 removed[j].then(function(view) {
                     remove.call(context, view)
                 });
             }
 
             // Add the rest of the new list items.
             for (; i < new_models.length; i++) {
                 this.views.push(Promise.resolve(create.call(context, new_models[i])));
             }
             // make a copy of the input array
             this._models = new_models.slice();
         },
 
         remove: function() {
             /**
              * removes every view in the list; convenience function for `.update([])`
              * that should be faster
              * returns a promise that resolves after this removal is done
              */
             var that = this;
             return Promise.all(this.views).then(function(views) {
                 for (var i = 0; i < that.views.length; i++) {
                     that._remove_view.call(that._handler_context, views[i]);
                 }
                 that.views = [];
                 that._models = [];
             });
         },
     });
 
     var widget = {
         'WidgetModel': WidgetModel,
         'WidgetView': WidgetView,
         'DOMWidgetView': DOMWidgetView,
         'ViewList': ViewList,
     };
 
     // For backwards compatability.
     $.extend(IPython, widget);
 
     return widget;
 });

IPython/html/static/widgets/js/widget_box.js

@@ -1,154 +1,186
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/widget",
     "jqueryui",
+    "underscore",
     "base/js/utils",
     "bootstrap",
-], function(widget, $, utils){
+], function(widget, $, _, utils){
     "use strict";
+    var unpack_models = function unpack_models(value, model) {
+        /**
+         * Replace model ids with models recursively.
+         */
+        var unpacked;
+        if ($.isArray(value)) {
+            unpacked = [];
+            _.each(value, function(sub_value, key) {
+                unpacked.push(unpack_models(sub_value, model));
+            });
+            return Promise.all(unpacked);
+        } else if (value instanceof Object) {
+            unpacked = {};
+            _.each(value, function(sub_value, key) {
+                unpacked[key] = unpack_models(sub_value, model);
+            });
+            return utils.resolve_promises_dict(unpacked);
+        } else if (typeof value === 'string' && value.slice(0,10) === "IPY_MODEL_") {
+            // get_model returns a promise already
+            return model.widget_manager.get_model(value.slice(10, value.length));
+        } else {
+            return Promise.resolve(value);
+        }
+    };
+
+    var BoxModel = widget.WidgetModel.extend({}, {
+        serializers: _.extend({
+            children: {deserialize: unpack_models}
+        }, widget.WidgetModel.serializers)
+    });
 
     var BoxView = widget.DOMWidgetView.extend({
         initialize: function(){
             /**
              * Public constructor
              */
             BoxView.__super__.initialize.apply(this, arguments);
             this.children_views = new widget.ViewList(this.add_child_model, null, this);
             this.listenTo(this.model, 'change:children', function(model, value) {
                 this.children_views.update(value);
             }, this);
             this.listenTo(this.model, 'change:overflow_x', function(model, value) {
                 this.update_overflow_x();
             }, this);
             this.listenTo(this.model, 'change:overflow_y', function(model, value) {
                 this.update_overflow_y();
             }, this);
             this.listenTo(this.model, 'change:box_style', function(model, value) {
                 this.update_box_style();
             }, this);
         },
 
         update_attr: function(name, value) {
             /**
              * Set a css attr of the widget view.
              */
             this.$box.css(name, value);
         },
 
         render: function(){
             /**
              * Called when view is rendered.
              */
             this.$box = this.$el;
             this.$box.addClass('widget-box');
             this.children_views.update(this.model.get('children'));
             this.update_overflow_x();
             this.update_overflow_y();
             this.update_box_style('');
         },
 
         update_overflow_x: function() {
             /**
              * Called when the x-axis overflow setting is changed.
              */
             this.$box.css('overflow-x', this.model.get('overflow_x'));
         },
 
         update_overflow_y: function() {
             /**
              * Called when the y-axis overflow setting is changed.
              */
             this.$box.css('overflow-y', this.model.get('overflow_y'));
         },
 
         update_box_style: function(previous_trait_value) {
             var class_map = {
                 success: ['alert', 'alert-success'],
                 info: ['alert', 'alert-info'],
                 warning: ['alert', 'alert-warning'],
                 danger: ['alert', 'alert-danger']
             };
             this.update_mapped_classes(class_map, 'box_style', previous_trait_value, this.$box);
         },
         
         add_child_model: function(model) {
             /**
              * Called when a model is added to the children list.
              */
             var that = this;
             var dummy = $('<div/>');
             that.$box.append(dummy);
             return this.create_child_view(model).then(function(view) {
                 dummy.replaceWith(view.el);
 
                 // Trigger the displayed event of the child view.
                 that.after_displayed(function() {
                     view.trigger('displayed');
                 });
                 return view;
             }).catch(utils.reject("Couldn't add child view to box", true));
         },
         
         remove: function() {
             /**
              * We remove this widget before removing the children as an optimization
              * we want to remove the entire container from the DOM first before
              * removing each individual child separately.
              */
             BoxView.__super__.remove.apply(this, arguments);
             this.children_views.remove();
         },
     });
 
 
     var FlexBoxView = BoxView.extend({
         render: function(){
             FlexBoxView.__super__.render.apply(this);
             this.listenTo(this.model, 'change:orientation', this.update_orientation, this);
             this.listenTo(this.model, 'change:flex', this._flex_changed, this);
             this.listenTo(this.model, 'change:pack', this._pack_changed, this);
             this.listenTo(this.model, 'change:align', this._align_changed, this);
             this._flex_changed();
             this._pack_changed();
             this._align_changed();
             this.update_orientation();
         },
 
         update_orientation: function(){
             var orientation = this.model.get("orientation");
             if (orientation == "vertical") {
                 this.$box.removeClass("hbox").addClass("vbox");
             } else {
                 this.$box.removeClass("vbox").addClass("hbox");
             }
         },
 
         _flex_changed: function(){
             if (this.model.previous('flex')) {
                 this.$box.removeClass('box-flex' + this.model.previous('flex'));
             }
             this.$box.addClass('box-flex' + this.model.get('flex'));
         },
 
         _pack_changed: function(){
             if (this.model.previous('pack')) {
                 this.$box.removeClass(this.model.previous('pack'));
             }
             this.$box.addClass(this.model.get('pack'));
         },
 
         _align_changed: function(){
             if (this.model.previous('align')) {
                 this.$box.removeClass('align-' + this.model.previous('align'));
             }
             this.$box.addClass('align-' + this.model.get('align'));
         },
     });
 
     return {
+        'BoxModel': BoxModel,
         'BoxView': BoxView,
         'FlexBoxView': FlexBoxView,
     };
 });

IPython/html/widgets/widget.py

@@ -1,523 +1,490
 """Base Widget class.  Allows user to create widgets in the back-end that render
 in the IPython notebook front-end.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from contextlib import contextmanager
 import collections
 
 from IPython.core.getipython import get_ipython
 from IPython.kernel.comm import Comm
 from IPython.config import LoggingConfigurable
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import Unicode, Dict, Instance, Bool, List, \
     CaselessStrEnum, Tuple, CUnicode, Int, Set
 from IPython.utils.py3compat import string_types
 from .trait_types import Color
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 class CallbackDispatcher(LoggingConfigurable):
     """A structure for registering and running callbacks"""
     callbacks = List()
     
     def __call__(self, *args, **kwargs):
         """Call all of the registered callbacks."""
         value = None
         for callback in self.callbacks:
             try:
                 local_value = callback(*args, **kwargs)
             except Exception as e:
                 ip = get_ipython()
                 if ip is None:
                     self.log.warn("Exception in callback %s: %s", callback, e, exc_info=True)
                 else:
                     ip.showtraceback()
             else:
                 value = local_value if local_value is not None else value
         return value
 
     def register_callback(self, callback, remove=False):
         """(Un)Register a callback
 
         Parameters
         ----------
         callback: method handle
             Method to be registered or unregistered.
         remove=False: bool
             Whether to unregister the callback."""
         
         # (Un)Register the callback.
         if remove and callback in self.callbacks:
             self.callbacks.remove(callback)
         elif not remove and callback not in self.callbacks:
             self.callbacks.append(callback)
 
 def _show_traceback(method):
     """decorator for showing tracebacks in IPython"""
     def m(self, *args, **kwargs):
         try:
             return(method(self, *args, **kwargs))
         except Exception as e:
             ip = get_ipython()
             if ip is None:
                 self.log.warn("Exception in widget method %s: %s", method, e, exc_info=True)
             else:
                 ip.showtraceback()
     return m
 
 
 def register(key=None):
     """Returns a decorator registering a widget class in the widget registry. 
     If no key is provided, the class name is used as a key. A key is
     provided for each core IPython widget so that the frontend can use
     this key regardless of the language of the kernel"""
     def wrap(widget):
         l = key if key is not None else widget.__module__ + widget.__name__
         Widget.widget_types[l] = widget
         return widget
     return wrap
 
 
-def _widget_to_json(x):
-    if isinstance(x, dict):
-        return {k: _widget_to_json(v) for k, v in x.items()}
-    elif isinstance(x, (list, tuple)):
-        return [_widget_to_json(v) for v in x]
-    elif isinstance(x, Widget):
-        return "IPY_MODEL_" + x.model_id
-    else:
-        return x
-
-def _json_to_widget(x):
-    if isinstance(x, dict):
-        return {k: _json_to_widget(v) for k, v in x.items()}
-    elif isinstance(x, (list, tuple)):
-        return [_json_to_widget(v) for v in x]
-    elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets:
-        return Widget.widgets[x[10:]]
-    else:
-        return x
-
-widget_serialization = {
-    'from_json': _json_to_widget,
-    'to_json': lambda x: (_widget_to_json(x), {'serialization': ('models', 'widgets/js/types')})
-}
-
 class Widget(LoggingConfigurable):
     #-------------------------------------------------------------------------
     # Class attributes
     #-------------------------------------------------------------------------
     _widget_construction_callback = None
     widgets = {}
     widget_types = {}
 
     @staticmethod
     def on_widget_constructed(callback):
         """Registers a callback to be called when a widget is constructed.
 
         The callback must have the following signature:
         callback(widget)"""
         Widget._widget_construction_callback = callback
 
     @staticmethod
     def _call_widget_constructed(widget):
         """Static method, called when a widget is constructed."""
         if Widget._widget_construction_callback is not None and callable(Widget._widget_construction_callback):
             Widget._widget_construction_callback(widget)
 
     @staticmethod
     def handle_comm_opened(comm, msg):
         """Static method, called when a widget is constructed."""
         widget_class = import_item(msg['content']['data']['widget_class'])
         widget = widget_class(comm=comm)
 
 
     #-------------------------------------------------------------------------
     # Traits
     #-------------------------------------------------------------------------
     _model_module = Unicode(None, allow_none=True, help="""A requirejs module name
         in which to find _model_name. If empty, look in the global registry.""")
     _model_name = Unicode('WidgetModel', help="""Name of the backbone model 
         registered in the front-end to create and sync this widget with.""")
     _view_module = Unicode(help="""A requirejs module in which to find _view_name.
         If empty, look in the global registry.""", sync=True)
     _view_name = Unicode(None, allow_none=True, help="""Default view registered in the front-end
         to use to represent the widget.""", sync=True)
     comm = Instance('IPython.kernel.comm.Comm')
     
     msg_throttle = Int(3, sync=True, help="""Maximum number of msgs the 
         front-end can send before receiving an idle msg from the back-end.""")
     
     version = Int(0, sync=True, help="""Widget's version""")
     keys = List()
     def _keys_default(self):
         return [name for name in self.traits(sync=True)]
     
     _property_lock = Tuple((None, None))
     _send_state_lock = Int(0)
     _states_to_send = Set()
     _display_callbacks = Instance(CallbackDispatcher, ())
     _msg_callbacks = Instance(CallbackDispatcher, ())
     
     #-------------------------------------------------------------------------
     # (Con/de)structor
     #-------------------------------------------------------------------------
     def __init__(self, **kwargs):
         """Public constructor"""
         self._model_id = kwargs.pop('model_id', None)
         super(Widget, self).__init__(**kwargs)
 
         Widget._call_widget_constructed(self)
         self.open()
 
     def __del__(self):
         """Object disposal"""
         self.close()
 
     #-------------------------------------------------------------------------
     # Properties
     #-------------------------------------------------------------------------
 
     def open(self):
         """Open a comm to the frontend if one isn't already open."""
         if self.comm is None:
             args = dict(target_name='ipython.widget',
                         data={'model_name': self._model_name,
                               'model_module': self._model_module})
             if self._model_id is not None:
                 args['comm_id'] = self._model_id
             self.comm = Comm(**args)
 
     def _comm_changed(self, name, new):
         """Called when the comm is changed."""
         if new is None:
             return
         self._model_id = self.model_id
         
         self.comm.on_msg(self._handle_msg)
         Widget.widgets[self.model_id] = self
         
         # first update
         self.send_state()
 
     @property
     def model_id(self):
         """Gets the model id of this widget.
 
         If a Comm doesn't exist yet, a Comm will be created automagically."""
         return self.comm.comm_id
 
     #-------------------------------------------------------------------------
     # Methods
     #-------------------------------------------------------------------------
 
     def close(self):
         """Close method.
 
         Closes the underlying comm.
         When the comm is closed, all of the widget views are automatically
         removed from the front-end."""
         if self.comm is not None:
             Widget.widgets.pop(self.model_id, None)
             self.comm.close()
             self.comm = None
     
     def send_state(self, key=None):
         """Sends the widget state, or a piece of it, to the front-end.
 
         Parameters
         ----------
         key : unicode, or iterable (optional)
             A single property's name or iterable of property names to sync with the front-end.
         """
-        state, buffer_keys, buffers, metadata = self.get_state(key=key)
+        state, buffer_keys, buffers = self.get_state(key=key)
         msg = {"method": "update", "state": state}
         if buffer_keys:
             msg['buffers'] = buffer_keys
-        if metadata:
-            msg['metadata'] = metadata
         self._send(msg, buffers=buffers)
 
     def get_state(self, key=None):
         """Gets the widget state, or a piece of it.
 
         Parameters
         ----------
         key : unicode or iterable (optional)
             A single property's name or iterable of property names to get.
 
         Returns
         -------
         state : dict of states
         buffer_keys : list of strings
             the values that are stored in buffers
         buffers : list of binary memoryviews
             values to transmit in binary
         metadata : dict
             metadata for each field: {key: metadata}
         """
         if key is None:
             keys = self.keys
         elif isinstance(key, string_types):
             keys = [key]
         elif isinstance(key, collections.Iterable):
             keys = key
         else:
             raise ValueError("key must be a string, an iterable of keys, or None")
         state = {}
         buffers = []
         buffer_keys = []
-        metadata = {}
         for k in keys:
             f = self.trait_metadata(k, 'to_json', self._trait_to_json)
             value = getattr(self, k)
-            serialized, md = f(value)
+            serialized = f(value)
             if isinstance(serialized, memoryview):
                 buffers.append(serialized)
                 buffer_keys.append(k)
             else:
                 state[k] = serialized
-            if md is not None:
-                metadata[k] = md
-        return state, buffer_keys, buffers, metadata
+        return state, buffer_keys, buffers
 
     def set_state(self, sync_data):
         """Called when a state is received from the front-end."""
         for name in self.keys:
             if name in sync_data:
                 json_value = sync_data[name]
                 from_json = self.trait_metadata(name, 'from_json', self._trait_from_json)
                 with self._lock_property(name, json_value):
                     setattr(self, name, from_json(json_value))
     
     def send(self, content, buffers=None):
         """Sends a custom msg to the widget model in the front-end.
 
         Parameters
         ----------
         content : dict
             Content of the message to send.
         buffers : list of binary buffers
             Binary buffers to send with message
         """
         self._send({"method": "custom", "content": content}, buffers=buffers)
 
     def on_msg(self, callback, remove=False):
         """(Un)Register a custom msg receive callback.
 
         Parameters
         ----------
         callback: callable
             callback will be passed three arguments when a message arrives::
             
                 callback(widget, content, buffers)
             
         remove: bool
             True if the callback should be unregistered."""
         self._msg_callbacks.register_callback(callback, remove=remove)
 
     def on_displayed(self, callback, remove=False):
         """(Un)Register a widget displayed callback.
 
         Parameters
         ----------
         callback: method handler
             Must have a signature of::
             
                 callback(widget, **kwargs)
             
             kwargs from display are passed through without modification.
         remove: bool
             True if the callback should be unregistered."""
         self._display_callbacks.register_callback(callback, remove=remove)
 
     #-------------------------------------------------------------------------
     # Support methods
     #-------------------------------------------------------------------------
     @contextmanager
     def _lock_property(self, key, value):
         """Lock a property-value pair.
 
         The value should be the JSON state of the property.
 
         NOTE: This, in addition to the single lock for all state changes, is 
         flawed.  In the future we may want to look into buffering state changes 
         back to the front-end."""
         self._property_lock = (key, value)
         try:
             yield
         finally:
             self._property_lock = (None, None)
 
     @contextmanager
     def hold_sync(self):
         """Hold syncing any state until the context manager is released"""
         # We increment a value so that this can be nested.  Syncing will happen when
         # all levels have been released.
         self._send_state_lock += 1
         try:
             yield
         finally:
             self._send_state_lock -=1
             if self._send_state_lock == 0:
                 self.send_state(self._states_to_send)
                 self._states_to_send.clear()
 
     def _should_send_property(self, key, value):
         """Check the property lock (property_lock)"""
         to_json = self.trait_metadata(key, 'to_json', self._trait_to_json)
         if (key == self._property_lock[0]
             and to_json(value) == self._property_lock[1]):
             return False
         elif self._send_state_lock > 0:
             self._states_to_send.add(key)
             return False
         else:
             return True
     
     # Event handlers
     @_show_traceback
     def _handle_msg(self, msg):
         """Called when a msg is received from the front-end"""
         data = msg['content']['data']
         method = data['method']
 
         # Handle backbone sync methods CREATE, PATCH, and UPDATE all in one.
         if method == 'backbone':
             if 'sync_data' in data:
                 # get binary buffers too
                 sync_data = data['sync_data']
                 for i,k in enumerate(data.get('buffer_keys', [])):
                     sync_data[k] = msg['buffers'][i]
                 self.set_state(sync_data) # handles all methods
 
         # Handle a state request.
         elif method == 'request_state':
             self.send_state()
 
         # Handle a custom msg from the front-end.
         elif method == 'custom':
             if 'content' in data:
                 self._handle_custom_msg(data['content'], msg['buffers'])
 
         # Catch remainder.
         else:
             self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method)
 
     def _handle_custom_msg(self, content, buffers):
         """Called when a custom msg is received."""
         self._msg_callbacks(self, content, buffers)
 
     def _notify_trait(self, name, old_value, new_value):
         """Called when a property has been changed."""
         # Trigger default traitlet callback machinery.  This allows any user
         # registered validation to be processed prior to allowing the widget
         # machinery to handle the state.
         LoggingConfigurable._notify_trait(self, name, old_value, new_value)
 
         # Send the state after the user registered callbacks for trait changes
         # have all fired (allows for user to validate values).
         if self.comm is not None and name in self.keys:
             # Make sure this isn't information that the front-end just sent us.
             if self._should_send_property(name, new_value):
                 # Send new state to front-end
                 self.send_state(key=name)
 
     def _handle_displayed(self, **kwargs):
         """Called when a view has been displayed for this widget instance"""
         self._display_callbacks(self, **kwargs)
 
     def _trait_to_json(self, x):
-        """Convert a trait value to json.
-
-        Metadata (the second return value) is not sent
-        """
-        return x, None
+        """Convert a trait value to json."""
+        return x
 
     def _trait_from_json(self, x):
         """Convert json values to objects."""
         return x
 
     def _ipython_display_(self, **kwargs):
         """Called when `IPython.display.display` is called on the widget."""
         # Show view.
         if self._view_name is not None:
             self._send({"method": "display"})
             self._handle_displayed(**kwargs)
 
     def _send(self, msg, buffers=None):
         """Sends a message to the model in the front-end."""
         self.comm.send(data=msg, buffers=buffers)
 
 
 class DOMWidget(Widget):
     visible = Bool(True, allow_none=True, help="Whether the widget is visible.  False collapses the empty space, while None preserves the empty space.", sync=True)
     _css = Tuple(sync=True, help="CSS property list: (selector, key, value)")
     _dom_classes = Tuple(sync=True, help="DOM classes applied to widget.$el.")
     
     width = CUnicode(sync=True)
     height = CUnicode(sync=True)
     # A default padding of 2.5 px makes the widgets look nice when displayed inline.
     padding = CUnicode(sync=True)
     margin = CUnicode(sync=True)
 
     color = Color(None, allow_none=True, sync=True)
     background_color = Color(None, allow_none=True, sync=True)
     border_color = Color(None, allow_none=True, sync=True)
 
     border_width = CUnicode(sync=True)
     border_radius = CUnicode(sync=True)
     border_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_border-style.asp
         'none', 
         'hidden', 
         'dotted', 
         'dashed', 
         'solid', 
         'double', 
         'groove', 
         'ridge', 
         'inset', 
         'outset', 
         'initial', 
         'inherit', ''],
         default_value='', sync=True)
 
     font_style = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_font-style.asp
         'normal', 
         'italic', 
         'oblique', 
         'initial', 
         'inherit', ''], 
         default_value='', sync=True)
     font_weight = CaselessStrEnum(values=[ # http://www.w3schools.com/cssref/pr_font_weight.asp
         'normal', 
         'bold', 
         'bolder', 
         'lighter',
         'initial', 
         'inherit', ''] + list(map(str, range(100,1000,100))),
         default_value='', sync=True)
     font_size = CUnicode(sync=True)
     font_family = Unicode(sync=True)
 
     def __init__(self, *pargs, **kwargs):
         super(DOMWidget, self).__init__(*pargs, **kwargs)
 
         def _validate_border(name, old, new):
             if new is not None and new != '':
                 if name != 'border_width' and not self.border_width:
                     self.border_width = 1
                 if name != 'border_style' and self.border_style == '':
                     self.border_style = 'solid'
         self.on_trait_change(_validate_border, ['border_width', 'border_style', 'border_color'])

IPython/html/widgets/widget_box.py

@@ -1,80 +1,107
 """Box class.  
 
 Represents a container that can be used to group other widgets.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from .widget import DOMWidget, register, widget_serialization
+from .widget import DOMWidget, Widget, register
 from IPython.utils.traitlets import Unicode, Tuple, TraitError, Int, CaselessStrEnum
 from IPython.utils.warn import DeprecatedClass
 
+def _widget_to_json(x):
+    if isinstance(x, dict):
+        return {k: _widget_to_json(v) for k, v in x.items()}
+    elif isinstance(x, (list, tuple)):
+        return [_widget_to_json(v) for v in x]
+    elif isinstance(x, Widget):
+        return "IPY_MODEL_" + x.model_id
+    else:
+        return x
+
+def _json_to_widget(x):
+    if isinstance(x, dict):
+        return {k: _json_to_widget(v) for k, v in x.items()}
+    elif isinstance(x, (list, tuple)):
+        return [_json_to_widget(v) for v in x]
+    elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets:
+        return Widget.widgets[x[10:]]
+    else:
+        return x
+
+widget_serialization = {
+    'from_json': _json_to_widget,
+    'to_json': _widget_to_json
+}
+
+
 @register('IPython.Box')
 class Box(DOMWidget):
     """Displays multiple widgets in a group."""
+    _model_name = Unicode('BoxModel', sync=True)
     _view_name = Unicode('BoxView', sync=True)
 
     # Child widgets in the container.
     # Using a tuple here to force reassignment to update the list.
     # When a proper notifying-list trait exists, that is what should be used here.
     children = Tuple(sync=True, **widget_serialization)
     
     _overflow_values = ['visible', 'hidden', 'scroll', 'auto', 'initial', 'inherit', '']
     overflow_x = CaselessStrEnum(
         values=_overflow_values, 
         default_value='', sync=True, help="""Specifies what
         happens to content that is too large for the rendered region.""")
     overflow_y = CaselessStrEnum(
         values=_overflow_values, 
         default_value='', sync=True, help="""Specifies what
         happens to content that is too large for the rendered region.""")
 
     box_style = CaselessStrEnum(
         values=['success', 'info', 'warning', 'danger', ''], 
         default_value='', allow_none=True, sync=True, help="""Use a
         predefined styling for the box.""")
 
     def __init__(self, children = (), **kwargs):
         kwargs['children'] = children
         super(Box, self).__init__(**kwargs)
         self.on_displayed(Box._fire_children_displayed)
 
     def _fire_children_displayed(self):
         for child in self.children:
             child._handle_displayed()
 
 
 @register('IPython.FlexBox')
 class FlexBox(Box):
     """Displays multiple widgets using the flexible box model."""
     _view_name = Unicode('FlexBoxView', sync=True)
     orientation = CaselessStrEnum(values=['vertical', 'horizontal'], default_value='vertical', sync=True)
     flex = Int(0, sync=True, help="""Specify the flexible-ness of the model.""")
     def _flex_changed(self, name, old, new):
         new = min(max(0, new), 2)
         if self.flex != new:
             self.flex = new
 
     _locations = ['start', 'center', 'end', 'baseline', 'stretch']
     pack = CaselessStrEnum(
         values=_locations, 
         default_value='start', sync=True)
     align = CaselessStrEnum(
         values=_locations, 
         default_value='start', sync=True)
 
 
 def VBox(*pargs, **kwargs):
     """Displays multiple widgets vertically using the flexible box model."""
     kwargs['orientation'] = 'vertical'
     return FlexBox(*pargs, **kwargs)
 
 def HBox(*pargs, **kwargs):
     """Displays multiple widgets horizontally using the flexible box model."""
     kwargs['orientation'] = 'horizontal'
     return FlexBox(*pargs, **kwargs)
 
 
 # Remove in IPython 4.0
 ContainerWidget = DeprecatedClass(Box, 'ContainerWidget')