Merge pull request #6789 from jdfreder/persistence2

Widget persistence API

docs/source/whatsnew/pr/persistence-api-feature.rst

@@ -0,0 +1,16 b''
+* Added a widget persistence API.  This allows you to persist your notebooks interactive widgets.
+  Two levels of control are provided:
+  1. Higher level- ``WidgetManager.set_state_callbacks`` allows you to register callbacks for loading and saving widget state.  The callbacks you register are automatically called when necessary.
+  2. Lower level- the ``WidgetManager`` Javascript class now has ``get_state`` and ``set_state`` methods that allow you to get and set the state of the widget runtime.
+
+  Example code for persisting your widget state to session data:
+  
+  ::
+    %%javascript
+    require(['widgets/js/manager'], function(manager) {
+        manager.WidgetManager.set_state_callbacks(function() { // Load
+            return JSON.parse(sessionStorage.widgets_state || '{}');
+        }, function(state) { // Save
+            sessionStorage.widgets_state = JSON.stringify(state);
+        });
+    });
  No newline at end of file

IPython/html/static/notebook/js/codecell.js

@@ -101,7 +101,7 b' define(['
 
         this.last_msg_id = null;
         this.completer = null;
-
+        this.widget_views = [];
 
         var config = utils.mergeopt(CodeCell, this.config);
         Cell.apply(this,[{
@@ -191,12 +191,19 b' define(['
             .addClass('widget-subarea')
             .appendTo(widget_area);
         this.widget_subarea = widget_subarea;
+        var that = this;
         var widget_clear_buton = $('<button />')
             .addClass('close')
             .html('&times;')
             .click(function() {
-                widget_area.slideUp('', function(){ widget_subarea.html(''); });
-                })
+                widget_area.slideUp('', function(){ 
+                    for (var i = 0; i < that.widget_views.length; i++) {
+                        that.widget_views[i].remove();
+                    }
+                    that.widget_views = [];
+                    widget_subarea.html(''); 
+                });
+            })
             .appendTo(widget_prompt);
 
         var output = $('<div></div>');
@@ -210,6 +217,25 b' define(['
         this.completer = new completer.Completer(this, this.events);
     };
 
+    /**
+    *  Display a widget view in the cell.
+    */
+    CodeCell.prototype.display_widget_view = function(view_promise) {
+
+        // Display a dummy element
+        var dummy = $('<div/>');
+        this.widget_subarea.append(dummy);
+
+        // Display the view.
+        var that = this;
+        return view_promise.then(function(view) {
+            that.widget_area.show();
+            dummy.replaceWith(view.$el);
+            that.widget_views.push(view);
+            return view;
+        });
+    };
+
     /** @method bind_events */
     CodeCell.prototype.bind_events = function () {
         Cell.prototype.bind_events.apply(this);
@@ -322,6 +348,10 b' define(['
         this.active_output_area.clear_output();
         
         // Clear widget area
+        for (var i = 0; i < this.widget_views.length; i++) {
+            this.widget_views[i].remove();
+        }
+        this.widget_views = [];
         this.widget_subarea.html('');
         this.widget_subarea.height('');
         this.widget_area.height('');

IPython/html/static/notebook/js/notebook.js

@@ -1980,6 +1980,10 b' define(['
             return;
         }
 
+        // Trigger an event before save, which allows listeners to modify
+        // the notebook as needed.
+        this.events.trigger('before_save.Notebook');
+
         // Create a JSON model to be sent to the server.
         var model = {
             type : "notebook",

IPython/html/static/widgets/js/manager.js

@@ -7,7 +7,8 b' define(['
     "jquery",
     "base/js/utils",
     "base/js/namespace",
-], function (_, Backbone, $, utils, IPython) {
+    "services/kernels/comm"
+], function (_, Backbone, $, utils, IPython, comm) {
     "use strict";
     //--------------------------------------------------------------------
     // WidgetManager class
@@ -22,10 +23,31 b' define(['
         this.keyboard_manager = notebook.keyboard_manager;
         this.notebook = notebook;
         this.comm_manager = comm_manager;
-        this._models = {}; /* Dictionary of model ids and model instances */
+        this.comm_target_name = 'ipython.widget';
+        this._models = {}; /* Dictionary of model ids and model instance promises */
 
         // Register with the comm manager.
-        this.comm_manager.register_target('ipython.widget', $.proxy(this._handle_comm_open, this));
+        this.comm_manager.register_target(this.comm_target_name, $.proxy(this._handle_comm_open, this));
+
+        // Load the initial state of the widget manager if a load callback was
+        // registered.
+        var that = this;
+        if (WidgetManager._load_callback) {
+            Promise.resolve(WidgetManager._load_callback.call(this)).then(function(state) {
+                that.set_state(state);
+            }).catch(utils.reject('Error loading widget manager state', true));
+        }
+
+        // Setup state saving code.
+        this.notebook.events.on('before_save.Notebook', function() {
+            var save_callback = WidgetManager._save_callback;
+            var options = WidgetManager._get_state_options;
+            if (save_callback) {
+                that.get_state(options).then(function(state) {
+                    save_callback.call(that, state);
+                }).catch(utils.reject('Could not call widget save state callback.', true));
+            }
+        });
     };
 
     //--------------------------------------------------------------------
@@ -34,17 +56,52 b' define(['
     WidgetManager._model_types = {}; /* Dictionary of model type names (target_name) and model types. */
     WidgetManager._view_types = {}; /* Dictionary of view names and view types. */
     WidgetManager._managers = []; /* List of widget managers */
+    WidgetManager._load_callback = null;
+    WidgetManager._save_callback = null;
 
     WidgetManager.register_widget_model = function (model_name, model_type) {
-        // Registers a widget model by name.
+        /** 
+         * Registers a widget model by name.
+         */
         WidgetManager._model_types[model_name] = model_type;
     };
 
     WidgetManager.register_widget_view = function (view_name, view_type) {
-        // Registers a widget view by name.
+        /** 
+         * Registers a widget view by name.
+         */
         WidgetManager._view_types[view_name] = view_type;
     };
 
+    WidgetManager.set_state_callbacks = function (load_callback, save_callback, options) {
+        /**
+         * Registers callbacks for widget state persistence.
+         * 
+         * Parameters
+         * ----------
+         * load_callback: function()
+         *      function that is called when the widget manager state should be
+         *      loaded.  This function should return a promise for the widget
+         *      manager state.  An empty state is an empty dictionary `{}`.
+         * save_callback: function(state as dictionary)
+         *      function that is called when the notebook is saved or autosaved.
+         *      The current state of the widget manager is passed in as the first
+         *      argument.
+         */
+        WidgetManager._load_callback = load_callback;
+        WidgetManager._save_callback = save_callback;
+        WidgetManager._get_state_options = options;
+
+        // Use the load callback to immediately load widget states.
+        WidgetManager._managers.forEach(function(manager) {
+            if (load_callback) {
+                Promise.resolve(load_callback.call(manager)).then(function(state) {
+                    manager.set_state(state);
+                }).catch(utils.reject('Error loading widget manager state', true));
+            }
+        });
+    };
+
     //--------------------------------------------------------------------
     // Instance level
     //--------------------------------------------------------------------
@@ -52,21 +109,31 b' define(['
         /**
          * Displays a view for a particular model.
          */
-        var that = this;
         var cell = this.get_msg_cell(msg.parent_header.msg_id);
         if (cell === null) {
-            return Promise.reject(new Error("Could not determine where the display" +
-                                            " message was from.  Widget will not be displayed"));
-        } else if (cell.widget_subarea) {
-            var dummy = $('<div />');
-            cell.widget_subarea.append(dummy);
-            return this.create_view(model, {cell: cell}).then(
-                function(view) {
-                    that._handle_display_view(view);
-                    dummy.replaceWith(view.$el);
-                    view.trigger('displayed');
-                    return view;
-                }).catch(utils.reject('Could not display view', true));
+            return Promise.reject(new Error("Could not determine where the display" + 
+                " message was from.  Widget will not be displayed"));
+        } else {
+            return this.display_view_in_cell(cell, model)
+                .catch(utils.reject('Could not display view', true)); 
+        }
+    };
+
+    WidgetManager.prototype.display_view_in_cell = function(cell, model) {
+        // Displays a view in a cell.
+        if (cell.display_widget_view) {
+            var that = this;
+            return cell.display_widget_view(this.create_view(model, {
+                cell: cell,
+                // Only set cell_index when view is displayed as directly.
+                cell_index: that.notebook.find_cell_index(cell),
+            })).then(function(view) {
+                that._handle_display_view(view);
+                view.trigger('displayed');
+                resolve(view);
+            }).catch(utils.reject('Could not create or display view', true)); 
+        } else {
+            return Promise.reject(new Error('Cell does not have a `display_widget_view` method'));
         }
     };
 
@@ -112,7 +179,13 b' define(['
                 return Promise.resolve(view.render()).then(function() {return view;});
             }).catch(utils.reject("Couldn't create a view for model id '" + String(model.id) + "'", true));
         });
-        model.views[utils.uuid()] = model.state_change;
+        var id = utils.uuid();
+        model.views[id] = model.state_change;
+        model.state_change.then(function(view) { 
+            view.once('remove', function() {
+                delete view.model.views[id];
+            }, this);
+        });
         return model.state_change;
     };
 
@@ -238,6 +311,8 b' define(['
                 widget_model.once('comm:close', function () {
                     delete that._models[model_id];
                 });
+                widget_model.name = options.model_name;
+                widget_model.module = options.model_module;
                 return widget_model;
 
             }, function(error) {
@@ -249,6 +324,139 b' define(['
         return model_promise;
     };
 
+    WidgetManager.prototype.get_state = function(options) {
+        /**
+         * Asynchronously get the state of the widget manager.
+         *
+         * This includes all of the widget models and the cells that they are
+         * displayed in.
+         *
+         * Parameters
+         * ----------
+         * options: dictionary
+         *  Dictionary of options with the following contents:
+         *      only_displayed: (optional) boolean=false
+         *          Only return models with one or more displayed views.
+         *      not_live: (optional) boolean=false
+         *          Include models that have comms with severed connections.
+         *
+         * Returns
+         * -------
+         * Promise for a state dictionary
+         */
+        var that = this;
+        return utils.resolve_promises_dict(this._models).then(function(models) {
+            var state = {};
+            for (var model_id in models) {
+                if (models.hasOwnProperty(model_id)) {
+                    var model = models[model_id];
+
+                    // If the model has one or more views defined for it,
+                    // consider it displayed.
+                    var displayed_flag = !(options && options.only_displayed) || Object.keys(model.views).length > 0;
+                    var live_flag = (options && options.not_live) || model.comm_live;
+                    if (displayed_flag && live_flag) {
+                        state[model_id] = {
+                            model_name: model.name,
+                            model_module: model.module,
+                            state: model.get_state(),
+                            views: [],
+                        };
+
+                        // Get the views that are displayed *now*.
+                        for (var id in model.views) {
+                            if (model.views.hasOwnProperty(id)) {
+                                var view = model.views[id];
+                                if (view.options.cell_index) {
+                                    state[model_id].views.push(view.options.cell_index);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            return state;
+        }).catch(utils.reject('Could not get state of widget manager', true));
+    };
+    
+    WidgetManager.prototype.set_state = function(state) {
+        /**
+         * Set the notebook's state.
+         *
+         * Reconstructs all of the widget models and attempts to redisplay the
+         * widgets in the appropriate cells by cell index.
+         */
+        
+        // Get the kernel when it's available.
+        var that = this;
+        return this._get_connected_kernel().then(function(kernel) {
+            
+            // Recreate all the widget models for the given state and 
+            // display the views.
+            that.all_views = [];
+            var model_ids = Object.keys(state);
+            for (var i = 0; i < model_ids.length; i++) {
+                var model_id = model_ids[i];
+                
+                // Recreate a comm using the widget's model id (model_id == comm_id).
+                var new_comm = new comm.Comm(kernel.widget_manager.comm_target_name, model_id);
+                kernel.comm_manager.register_comm(new_comm);
+
+                // Create the model using the recreated comm.  When the model is
+                // created we don't know yet if the comm is valid so set_comm_live
+                // false.  Once we receive the first state push from the back-end
+                // we know the comm is alive.
+                var views = kernel.widget_manager.create_model({
+                    comm: new_comm, 
+                    model_name: state[model_id].model_name, 
+                    model_module: state[model_id].model_module})
+                .then(function(model) {
+
+                    model.set_comm_live(false);
+                    var view_promise = Promise.resolve().then(function() {
+                        return model.set_state(state[model.id].state);
+                    }).then(function() {
+                        model.request_state().then(function() {
+                            model.set_comm_live(true);
+                        });
+
+                        // Display the views of the model.
+                        var views = [];
+                        var model_views = state[model.id].views;
+                        for (var j=0; j<model_views.length; j++) {
+                            var cell_index = model_views[j];
+                            var cell = that.notebook.get_cell(cell_index);
+                            views.push(that.display_view_in_cell(cell, model));
+                        }
+                        return Promise.all(views);
+                    });
+                    return view_promise;
+                });
+                that.all_views.push(views);
+            }
+            return Promise.all(that.all_views);
+        }).catch(utils.reject('Could not set widget manager state.', true));  
+    };
+
+    WidgetManager.prototype._get_connected_kernel = function() {
+        /**
+         * Gets a promise for a connected kernel
+         */
+        var that = this;
+        return new Promise(function(resolve, reject) {
+            if (that.comm_manager && 
+                that.comm_manager.kernel && 
+                that.comm_manager.kernel.is_connected()) {
+
+                resolve(that.comm_manager.kernel);
+            } else {
+                that.notebook.events.on('kernel_connected.Kernel', function(event, data) {
+                    resolve(data.kernel);
+                });
+            }    
+        });
+    };
+
     // Backwards compatibility.
     IPython.WidgetManager = WidgetManager;
 

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

@@ -31,6 +31,7 b' define(["widgets/js/manager",'
             this.state_lock = null;
             this.id = model_id;
             this.views = {};
+            this._resolve_received_state = {};
 
             if (comm !== undefined) {
                 // Remember comm associated with the model.
@@ -40,6 +41,11 b' define(["widgets/js/manager",'
                 // 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);
             }
             return Backbone.Model.apply(this);
         },
@@ -55,11 +61,43 b' define(["widgets/js/manager",'
             }
         },
 
-        _handle_comm_closed: function (msg) {
+        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) {
             /**
-             * Handle when a widget is closed.
+             * Close model
              */
-            this.trigger('comm:close');
+            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.
@@ -73,6 +111,14 b' define(["widgets/js/manager",'
             });
         },
 
+        _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.
@@ -81,15 +127,24 b' define(["widgets/js/manager",'
             var that = this;
             switch (method) {
                 case 'update':
-                    this.state_change = this.state_change.then(function() {
-                        return that.set_state(msg.content.data.state);
-                    }).catch(utils.reject("Couldn't process update msg for model id '" + String(that.id) + "'", true));
+                    this.state_change = this.state_change
+                        .then(function() {
+                            return that.set_state(msg.content.data.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);
                     break;
                 case 'display':
-                    this.widget_manager.display_view(msg, this);
+                    this.widget_manager.display_view(msg, this)
+                        .catch(utils.reject('Could not process display view msg', true));
                     break;
             }
         },
@@ -107,6 +162,17 b' define(["widgets/js/manager",'
             }).catch(utils.reject("Couldn't set model state", true));
         },
 
+        get_state: function() {
+            // Get the serializable state of the model.
+            state = this.toJSON();
+            for (var key in state) {
+                if (state.hasOwnProperty(key)) {
+                    state[key] = this._pack_models(state[key]);
+                }
+            }
+            return state;
+        },
+
         _handle_status: function (msg, callbacks) {
             /**
              * Handle status msgs.
@@ -356,16 +422,6 b' define(["widgets/js/manager",'
              */
         },
 
-        show: function(){
-            /**
-             * Show the widget-area
-             */
-            if (this.options && this.options.cell &&
-                this.options.cell.widget_area !== undefined) {
-                this.options.cell.widget_area.show();
-            }
-        },
-
         send: function (content) {
             /**
              * Send a custom msg associated with this view.
@@ -387,6 +443,12 b' define(["widgets/js/manager",'
             } 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');
         }
     });
 
@@ -397,7 +459,6 b' define(["widgets/js/manager",'
              * Public constructor
              */
             DOMWidgetView.__super__.initialize.apply(this, [parameters]);
-            this.on('displayed', this.show, this);
             this.model.on('change:visible', this.update_visible, this);
             this.model.on('change:_css', this.update_css, this);
 

IPython/html/widgets/widget.py

@@ -341,19 +341,26 b' class Widget(LoggingConfigurable):'
         """Called when a msg is received from the front-end"""
         data = msg['content']['data']
         method = data['method']
-        if not method in ['backbone', 'custom']:
-            self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method)
 
         # Handle backbone sync methods CREATE, PATCH, and UPDATE all in one.
-        if method == 'backbone' and 'sync_data' in data:
-            sync_data = data['sync_data']
-            self.set_state(sync_data) # handles all methods
+        if method == 'backbone':
+            if 'sync_data' in data:
+                sync_data = data['sync_data']
+                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
+        # Handle a custom msg from the front-end.
         elif method == 'custom':
             if 'content' in data:
                 self._handle_custom_msg(data['content'])
 
+        # Catch remainder.
+        else:
+            self.log.error('Unknown front-end to back-end widget msg with method "%s"' % method)
+
     def _handle_custom_msg(self, content):
         """Called when a custom msg is received."""
         self._msg_callbacks(self, content)
@@ -368,7 +375,7 b' class Widget(LoggingConfigurable):'
         # 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.
+            # 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)