Persistence API,

This is a combination of 10 commits.
Enable widget instanciation from front-end.

Address @minrk 's review comments.

Make API that allows users to persist widget state easily.

Added support for view persistence

Started adding support for model persistence.

Half way there!

Finished persistence API.

Move persistence code into the widget framework.

Fin.

Bug fixes

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

@@ -1,573 +1,602 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 /**
  *
  *
  * @module codecell
  * @namespace codecell
  * @class CodeCell
  */
 
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/keyboard',
     'notebook/js/cell',
     'notebook/js/outputarea',
     'notebook/js/completer',
     'notebook/js/celltoolbar',
     'codemirror/lib/codemirror',
     'codemirror/mode/python/python',
     'notebook/js/codemirror-ipython'
 ], function(IPython, $, utils, keyboard, cell, outputarea, completer, celltoolbar, CodeMirror, cmpython, cmip) {
     "use strict";
     
     var Cell = cell.Cell;
 
     /* local util for codemirror */
     var posEq = function(a, b) {return a.line == b.line && a.ch == b.ch;};
 
     /**
      *
      * function to delete until previous non blanking space character
      * or first multiple of 4 tabstop.
      * @private
      */
     CodeMirror.commands.delSpaceToPrevTabStop = function(cm){
         var from = cm.getCursor(true), to = cm.getCursor(false), sel = !posEq(from, to);
         if (!posEq(from, to)) { cm.replaceRange("", from, to); return; }
         var cur = cm.getCursor(), line = cm.getLine(cur.line);
         var tabsize = cm.getOption('tabSize');
         var chToPrevTabStop = cur.ch-(Math.ceil(cur.ch/tabsize)-1)*tabsize;
         from = {ch:cur.ch-chToPrevTabStop,line:cur.line};
         var select = cm.getRange(from,cur);
         if( select.match(/^\ +$/) !== null){
             cm.replaceRange("",from,cur);
         } else {
             cm.deleteH(-1,"char");
         }
     };
 
     var keycodes = keyboard.keycodes;
 
     var CodeCell = function (kernel, options) {
         /**
          * Constructor
          *
          * A Cell conceived to write code.
          *
          * Parameters:
          *  kernel: Kernel instance
          *      The kernel doesn't have to be set at creation time, in that case
          *      it will be null and set_kernel has to be called later.
          *  options: dictionary
          *      Dictionary of keyword arguments.
          *          events: $(Events) instance 
          *          config: dictionary
          *          keyboard_manager: KeyboardManager instance 
          *          notebook: Notebook instance
          *          tooltip: Tooltip instance
          */
         this.kernel = kernel || null;
         this.notebook = options.notebook;
         this.collapsed = false;
         this.events = options.events;
         this.tooltip = options.tooltip;
         this.config = options.config;
 
         // create all attributed in constructor function
         // even if null for V8 VM optimisation
         this.input_prompt_number = null;
         this.celltoolbar = null;
         this.output_area = null;
         // Keep a stack of the 'active' output areas (where active means the 
         // output area that recieves output).  When a user activates an output
         // area, it gets pushed to the stack.  Then, when the output area is
         // deactivated, it's popped from the stack.  When the stack is empty,
         // the cell's output area is used.
         this.active_output_areas = [];
         var that = this;
         Object.defineProperty(this, 'active_output_area', {
             get: function() {
                 if (that.active_output_areas && that.active_output_areas.length > 0) {
                     return that.active_output_areas[that.active_output_areas.length-1];
                 } else {
                     return that.output_area;
                 }
             },
         });
 
         this.last_msg_id = null;
         this.completer = null;
-
+        this.widget_views = [];
 
         var config = utils.mergeopt(CodeCell, this.config);
         Cell.apply(this,[{
             config: config, 
             keyboard_manager: options.keyboard_manager, 
             events: this.events}]);
 
         // Attributes we want to override in this subclass.
         this.cell_type = "code";
         this.element.focusout(
             function() { that.auto_highlight(); }
         );
     };
 
     CodeCell.options_default = {
         cm_config : {
             extraKeys: {
                 "Tab" :  "indentMore",
                 "Shift-Tab" : "indentLess",
                 "Backspace" : "delSpaceToPrevTabStop",
                 "Cmd-/" : "toggleComment",
                 "Ctrl-/" : "toggleComment"
             },
             mode: 'ipython',
             theme: 'ipython',
             matchBrackets: true
         }
     };
 
     CodeCell.msg_cells = {};
 
     CodeCell.prototype = Object.create(Cell.prototype);
 
     /**
      * @method push_output_area
      */
     CodeCell.prototype.push_output_area = function (output_area) {
         this.active_output_areas.push(output_area);
     };
 
     /**
      * @method pop_output_area
      */
     CodeCell.prototype.pop_output_area = function (output_area) {
         var index = this.active_output_areas.lastIndexOf(output_area);
         if (index > -1) {
             this.active_output_areas.splice(index, 1);
         }
     };
 
     /**
      * @method auto_highlight
      */
     CodeCell.prototype.auto_highlight = function () {
         this._auto_highlight(this.config.cell_magic_highlight);
     };
 
     /** @method create_element */
     CodeCell.prototype.create_element = function () {
         Cell.prototype.create_element.apply(this, arguments);
 
         var cell =  $('<div></div>').addClass('cell code_cell');
         cell.attr('tabindex','2');
 
         var input = $('<div></div>').addClass('input');
         var prompt = $('<div/>').addClass('prompt input_prompt');
         var inner_cell = $('<div/>').addClass('inner_cell');
         this.celltoolbar = new celltoolbar.CellToolbar({
             cell: this, 
             notebook: this.notebook});
         inner_cell.append(this.celltoolbar.element);
         var input_area = $('<div/>').addClass('input_area');
         this.code_mirror = new CodeMirror(input_area.get(0), this.cm_config);
         this.code_mirror.on('keydown', $.proxy(this.handle_keyevent,this))
         $(this.code_mirror.getInputField()).attr("spellcheck", "false");
         inner_cell.append(input_area);
         input.append(prompt).append(inner_cell);
 
         var widget_area = $('<div/>')
             .addClass('widget-area')
             .hide();
         this.widget_area = widget_area;
         var widget_prompt = $('<div/>')
             .addClass('prompt')
             .appendTo(widget_area);
         var widget_subarea = $('<div/>')
             .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>');
         cell.append(input).append(widget_area).append(output);
         this.element = cell;
         this.output_area = new outputarea.OutputArea({
             selector: output, 
             prompt_area: true, 
             events: this.events, 
             keyboard_manager: this.keyboard_manager});
         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) {
+            dummy.replaceWith(view.$el);
+            this.widget_views.push(view);
+            return view;
+        });
+    };
+
     /** @method bind_events */
     CodeCell.prototype.bind_events = function () {
         Cell.prototype.bind_events.apply(this);
         var that = this;
 
         this.element.focusout(
             function() { that.auto_highlight(); }
         );
     };
 
 
     /**
      *  This method gets called in CodeMirror's onKeyDown/onKeyPress
      *  handlers and is used to provide custom key handling. Its return
      *  value is used to determine if CodeMirror should ignore the event:
      *  true = ignore, false = don't ignore.
      *  @method handle_codemirror_keyevent
      */
 
     CodeCell.prototype.handle_codemirror_keyevent = function (editor, event) {
 
         var that = this;
         // whatever key is pressed, first, cancel the tooltip request before
         // they are sent, and remove tooltip if any, except for tab again
         var tooltip_closed = null;
         if (event.type === 'keydown' && event.which != keycodes.tab ) {
             tooltip_closed = this.tooltip.remove_and_cancel_tooltip();
         }
 
         var cur = editor.getCursor();
         if (event.keyCode === keycodes.enter){
             this.auto_highlight();
         }
 
         if (event.which === keycodes.down && event.type === 'keypress' && this.tooltip.time_before_tooltip >= 0) {
             // triger on keypress (!) otherwise inconsistent event.which depending on plateform
             // browser and keyboard layout !
             // Pressing '(' , request tooltip, don't forget to reappend it
             // The second argument says to hide the tooltip if the docstring
             // is actually empty
             this.tooltip.pending(that, true);
         } else if ( tooltip_closed && event.which === keycodes.esc && event.type === 'keydown') {
             // If tooltip is active, cancel it.  The call to
             // remove_and_cancel_tooltip above doesn't pass, force=true.
             // Because of this it won't actually close the tooltip
             // if it is in sticky mode. Thus, we have to check again if it is open
             // and close it with force=true.
             if (!this.tooltip._hidden) {
                 this.tooltip.remove_and_cancel_tooltip(true);
             }
             // If we closed the tooltip, don't let CM or the global handlers
             // handle this event.
             event.codemirrorIgnore = true;
             event.preventDefault();
             return true;
         } else if (event.keyCode === keycodes.tab && event.type === 'keydown' && event.shiftKey) {
                 if (editor.somethingSelected() || editor.getSelections().length !== 1){
                     var anchor = editor.getCursor("anchor");
                     var head = editor.getCursor("head");
                     if( anchor.line != head.line){
                         return false;
                     }
                 }
                 this.tooltip.request(that);
                 event.codemirrorIgnore = true;
                 event.preventDefault();
                 return true;
         } else if (event.keyCode === keycodes.tab && event.type == 'keydown') {
             // Tab completion.
             this.tooltip.remove_and_cancel_tooltip();
 
             // completion does not work on multicursor, it might be possible though in some cases
             if (editor.somethingSelected() || editor.getSelections().length > 1) {
                 return false;
             }
             var pre_cursor = editor.getRange({line:cur.line,ch:0},cur);
             if (pre_cursor.trim() === "") {
                 // Don't autocomplete if the part of the line before the cursor
                 // is empty.  In this case, let CodeMirror handle indentation.
                 return false;
             } else {
                 event.codemirrorIgnore = true;
                 event.preventDefault();
                 this.completer.startCompletion();
                 return true;
             }
         } 
         
         // keyboard event wasn't one of those unique to code cells, let's see
         // if it's one of the generic ones (i.e. check edit mode shortcuts)
         return Cell.prototype.handle_codemirror_keyevent.apply(this, [editor, event]);
     };
 
     // Kernel related calls.
 
     CodeCell.prototype.set_kernel = function (kernel) {
         this.kernel = kernel;
     };
 
     /**
      * Execute current code cell to the kernel
      * @method execute
      */
     CodeCell.prototype.execute = function () {
         if (!this.kernel || !this.kernel.is_connected()) {
             console.log("Can't execute, kernel is not connected.");
             return;
         }
 
         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('');
         this.widget_area.hide();
 
         this.set_input_prompt('*');
         this.element.addClass("running");
         if (this.last_msg_id) {
             this.kernel.clear_callbacks_for_msg(this.last_msg_id);
         }
         var callbacks = this.get_callbacks();
         
         var old_msg_id = this.last_msg_id;
         this.last_msg_id = this.kernel.execute(this.get_text(), callbacks, {silent: false, store_history: true});
         if (old_msg_id) {
             delete CodeCell.msg_cells[old_msg_id];
         }
         CodeCell.msg_cells[this.last_msg_id] = this;
         this.render();
         this.events.trigger('execute.CodeCell', {cell: this});
     };
     
     /**
      * Construct the default callbacks for
      * @method get_callbacks
      */
     CodeCell.prototype.get_callbacks = function () {
         var that = this;
         return {
             shell : {
                 reply : $.proxy(this._handle_execute_reply, this),
                 payload : {
                     set_next_input : $.proxy(this._handle_set_next_input, this),
                     page : $.proxy(this._open_with_pager, this)
                 }
             },
             iopub : {
                 output : function() { 
                     that.active_output_area.handle_output.apply(that.active_output_area, arguments);
                 }, 
                 clear_output : function() { 
                     that.active_output_area.handle_clear_output.apply(that.active_output_area, arguments);
                 }, 
             },
             input : $.proxy(this._handle_input_request, this)
         };
     };
     
     CodeCell.prototype._open_with_pager = function (payload) {
         this.events.trigger('open_with_text.Pager', payload);
     };
 
     /**
      * @method _handle_execute_reply
      * @private
      */
     CodeCell.prototype._handle_execute_reply = function (msg) {
         this.set_input_prompt(msg.content.execution_count);
         this.element.removeClass("running");
         this.events.trigger('set_dirty.Notebook', {value: true});
     };
 
     /**
      * @method _handle_set_next_input
      * @private
      */
     CodeCell.prototype._handle_set_next_input = function (payload) {
         var data = {'cell': this, 'text': payload.text, replace: payload.replace};
         this.events.trigger('set_next_input.Notebook', data);
     };
 
     /**
      * @method _handle_input_request
      * @private
      */
     CodeCell.prototype._handle_input_request = function (msg) {
         this.active_output_area.append_raw_input(msg);
     };
 
 
     // Basic cell manipulation.
 
     CodeCell.prototype.select = function () {
         var cont = Cell.prototype.select.apply(this);
         if (cont) {
             this.code_mirror.refresh();
             this.auto_highlight();
         }
         return cont;
     };
 
     CodeCell.prototype.render = function () {
         var cont = Cell.prototype.render.apply(this);
         // Always execute, even if we are already in the rendered state
         return cont;
     };
     
     CodeCell.prototype.select_all = function () {
         var start = {line: 0, ch: 0};
         var nlines = this.code_mirror.lineCount();
         var last_line = this.code_mirror.getLine(nlines-1);
         var end = {line: nlines-1, ch: last_line.length};
         this.code_mirror.setSelection(start, end);
     };
 
 
     CodeCell.prototype.collapse_output = function () {
         this.output_area.collapse();
     };
 
 
     CodeCell.prototype.expand_output = function () {
         this.output_area.expand();
         this.output_area.unscroll_area();
     };
 
     CodeCell.prototype.scroll_output = function () {
         this.output_area.expand();
         this.output_area.scroll_if_long();
     };
 
     CodeCell.prototype.toggle_output = function () {
         this.output_area.toggle_output();
     };
 
     CodeCell.prototype.toggle_output_scroll = function () {
         this.output_area.toggle_scroll();
     };
 
 
     CodeCell.input_prompt_classical = function (prompt_value, lines_number) {
         var ns;
         if (prompt_value === undefined || prompt_value === null) {
             ns = "&nbsp;";
         } else {
             ns = encodeURIComponent(prompt_value);
         }
         return 'In&nbsp;[' + ns + ']:';
     };
 
     CodeCell.input_prompt_continuation = function (prompt_value, lines_number) {
         var html = [CodeCell.input_prompt_classical(prompt_value, lines_number)];
         for(var i=1; i < lines_number; i++) {
             html.push(['...:']);
         }
         return html.join('<br/>');
     };
 
     CodeCell.input_prompt_function = CodeCell.input_prompt_classical;
 
 
     CodeCell.prototype.set_input_prompt = function (number) {
         var nline = 1;
         if (this.code_mirror !== undefined) {
            nline = this.code_mirror.lineCount();
         }
         this.input_prompt_number = number;
         var prompt_html = CodeCell.input_prompt_function(this.input_prompt_number, nline);
         // This HTML call is okay because the user contents are escaped.
         this.element.find('div.input_prompt').html(prompt_html);
     };
 
 
     CodeCell.prototype.clear_input = function () {
         this.code_mirror.setValue('');
     };
 
 
     CodeCell.prototype.get_text = function () {
         return this.code_mirror.getValue();
     };
 
 
     CodeCell.prototype.set_text = function (code) {
         return this.code_mirror.setValue(code);
     };
 
 
     CodeCell.prototype.clear_output = function (wait) {
         this.active_output_area.clear_output(wait);
         this.set_input_prompt();
     };
 
 
     // JSON serialization
 
     CodeCell.prototype.fromJSON = function (data) {
         Cell.prototype.fromJSON.apply(this, arguments);
         if (data.cell_type === 'code') {
             if (data.source !== undefined) {
                 this.set_text(data.source);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 this.code_mirror.clearHistory();
                 this.auto_highlight();
             }
             this.set_input_prompt(data.execution_count);
             this.output_area.trusted = data.metadata.trusted || false;
             this.output_area.fromJSON(data.outputs);
             if (data.metadata.collapsed !== undefined) {
                 if (data.metadata.collapsed) {
                     this.collapse_output();
                 } else {
                     this.expand_output();
                 }
             }
         }
     };
 
 
     CodeCell.prototype.toJSON = function () {
         var data = Cell.prototype.toJSON.apply(this);
         data.source = this.get_text();
         // is finite protect against undefined and '*' value
         if (isFinite(this.input_prompt_number)) {
             data.execution_count = this.input_prompt_number;
         } else {
             data.execution_count = null;
         }
         var outputs = this.output_area.toJSON();
         data.outputs = outputs;
         data.metadata.trusted = this.output_area.trusted;
         data.metadata.collapsed = this.output_area.collapsed;
         return data;
     };
 
     /**
      * handle cell level logic when a cell is unselected
      * @method unselect
      * @return is the action being taken
      */
     CodeCell.prototype.unselect = function () {
         var cont = Cell.prototype.unselect.apply(this);
         if (cont) {
             // When a code cell is usnelected, make sure that the corresponding
             // tooltip and completer to that cell is closed.
             this.tooltip.remove_and_cancel_tooltip(true);
             if (this.completer !== null) {
                 this.completer.close();
             }
         }
         return cont;
     };
 
     // Backwards compatability.
     IPython.CodeCell = CodeCell;
 
     return {'CodeCell': CodeCell};
 });

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

@@ -1,2526 +1,2533 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
     'notebook/js/cell',
     'notebook/js/textcell',
     'notebook/js/codecell',
     'services/sessions/session',
     'notebook/js/celltoolbar',
     'components/marked/lib/marked',
     'codemirror/lib/codemirror',
     'codemirror/addon/runmode/runmode',
     'notebook/js/mathjaxutils',
     'base/js/keyboard',
     'notebook/js/tooltip',
     'notebook/js/celltoolbarpresets/default',
     'notebook/js/celltoolbarpresets/rawcell',
     'notebook/js/celltoolbarpresets/slideshow',
     'notebook/js/scrollmanager'
 ], function (
     IPython, 
     $,
     utils,
     dialog,
     cellmod,
     textcell,
     codecell,
     session, 
     celltoolbar,
     marked,
     CodeMirror,
     runMode,
     mathjaxutils,
     keyboard,
     tooltip,
     default_celltoolbar,
     rawcell_celltoolbar,
     slideshow_celltoolbar,
     scrollmanager
     ) {
     "use strict";
 
     var Notebook = function (selector, options) {
         /**
          * Constructor
          *
          * A notebook contains and manages cells.
          *
          * Parameters:
          *  selector: string
          *  options: dictionary
          *      Dictionary of keyword arguments.
          *          events: $(Events) instance
          *          keyboard_manager: KeyboardManager instance
          *          contents: Contents instance
          *          save_widget: SaveWidget instance
          *          config: dictionary
          *          base_url : string
          *          notebook_path : string
          *          notebook_name : string
          */
         this.config = utils.mergeopt(Notebook, options.config);
         this.base_url = options.base_url;
         this.notebook_path = options.notebook_path;
         this.notebook_name = options.notebook_name;
         this.events = options.events;
         this.keyboard_manager = options.keyboard_manager;
         this.contents = options.contents;
         this.save_widget = options.save_widget;
         this.tooltip = new tooltip.Tooltip(this.events);
         this.ws_url = options.ws_url;
         this._session_starting = false;
         this.default_cell_type = this.config.default_cell_type || 'code';
 
         //  Create default scroll manager.
         this.scroll_manager = new scrollmanager.ScrollManager(this);
 
         // TODO: This code smells (and the other `= this` line a couple lines down)
         // We need a better way to deal with circular instance references.
         this.keyboard_manager.notebook = this;
         this.save_widget.notebook = this;
         
         mathjaxutils.init();
 
         if (marked) {
             marked.setOptions({
                 gfm : true,
                 tables: true,
                 // FIXME: probably want central config for CodeMirror theme when we have js config
                 langPrefix: "cm-s-ipython language-",
                 highlight: function(code, lang, callback) {
                     if (!lang) {
                         // no language, no highlight
                         if (callback) {
                             callback(null, code);
                             return;
                         } else {
                             return code;
                         }
                     }
                     utils.requireCodeMirrorMode(lang, function (spec) {
                         var el = document.createElement("div");
                         var mode = CodeMirror.getMode({}, spec);
                         if (!mode) {
                             console.log("No CodeMirror mode: " + lang);
                             callback(null, code);
                             return;
                         }
                         try {
                             CodeMirror.runMode(code, spec, el);
                             callback(null, el.innerHTML);
                         } catch (err) {
                             console.log("Failed to highlight " + lang + " code", err);
                             callback(err, code);
                         }
                     }, function (err) {
                         console.log("No CodeMirror mode: " + lang);
                         callback(err, code);
                     });
                 }
             });
         }
 
         this.element = $(selector);
         this.element.scroll();
         this.element.data("notebook", this);
         this.next_prompt_number = 1;
         this.session = null;
         this.kernel = null;
         this.clipboard = null;
         this.undelete_backup = null;
         this.undelete_index = null;
         this.undelete_below = false;
         this.paste_enabled = false;
         this.writable = false;
         // It is important to start out in command mode to match the intial mode
         // of the KeyboardManager.
         this.mode = 'command';
         this.set_dirty(false);
         this.metadata = {};
         this._checkpoint_after_save = false;
         this.last_checkpoint = null;
         this.checkpoints = [];
         this.autosave_interval = 0;
         this.autosave_timer = null;
         // autosave *at most* every two minutes
         this.minimum_autosave_interval = 120000;
         this.notebook_name_blacklist_re = /[\/\\:]/;
         this.nbformat = 4; // Increment this when changing the nbformat
         this.nbformat_minor = this.current_nbformat_minor = 0; // Increment this when changing the nbformat
         this.codemirror_mode = 'ipython';
         this.create_elements();
         this.bind_events();
         this.kernel_selector = null;
         this.dirty = null;
         this.trusted = null;
         this._fully_loaded = false;
 
         // Trigger cell toolbar registration.
         default_celltoolbar.register(this);
         rawcell_celltoolbar.register(this);
         slideshow_celltoolbar.register(this);
 
         // prevent assign to miss-typed properties.
         Object.seal(this);
     };
 
     Notebook.options_default = {
         // can be any cell type, or the special values of
         // 'above', 'below', or 'selected' to get the value from another cell.
         Notebook: {
             default_cell_type: 'code'
         }
     };
 
 
     /**
      * Create an HTML and CSS representation of the notebook.
      * 
      * @method create_elements
      */
     Notebook.prototype.create_elements = function () {
         var that = this;
         this.element.attr('tabindex','-1');
         this.container = $("<div/>").addClass("container").attr("id", "notebook-container");
         // We add this end_space div to the end of the notebook div to:
         // i) provide a margin between the last cell and the end of the notebook
         // ii) to prevent the div from scrolling up when the last cell is being
         // edited, but is too low on the page, which browsers will do automatically.
         var end_space = $('<div/>').addClass('end_space');
         end_space.dblclick(function (e) {
             var ncells = that.ncells();
             that.insert_cell_below('code',ncells-1);
         });
         this.element.append(this.container);
         this.container.append(end_space);
     };
 
     /**
      * Bind JavaScript events: key presses and custom IPython events.
      * 
      * @method bind_events
      */
     Notebook.prototype.bind_events = function () {
         var that = this;
 
         this.events.on('set_next_input.Notebook', function (event, data) {
             if (data.replace) {
                 data.cell.set_text(data.text);
                 data.cell.clear_output();
             } else {
                 var index = that.find_cell_index(data.cell);
                 var new_cell = that.insert_cell_below('code',index);
                 new_cell.set_text(data.text);
             }
             that.dirty = true;
         });
 
         this.events.on('unrecognized_cell.Cell', function () {
             that.warn_nbformat_minor();
         });
 
         this.events.on('unrecognized_output.OutputArea', function () {
             that.warn_nbformat_minor();
         });
 
         this.events.on('set_dirty.Notebook', function (event, data) {
             that.dirty = data.value;
         });
 
         this.events.on('trust_changed.Notebook', function (event, trusted) {
             that.trusted = trusted;
         });
 
         this.events.on('select.Cell', function (event, data) {
             var index = that.find_cell_index(data.cell);
             that.select(index);
         });
 
         this.events.on('edit_mode.Cell', function (event, data) {
             that.handle_edit_mode(data.cell);
         });
 
         this.events.on('command_mode.Cell', function (event, data) {
             that.handle_command_mode(data.cell);
         });
         
         this.events.on('spec_changed.Kernel', function(event, data) {
             that.metadata.kernelspec = 
                 {name: data.name, display_name: data.display_name};
         });
 
         this.events.on('kernel_ready.Kernel', function(event, data) {
             var kinfo = data.kernel.info_reply;
             var langinfo = kinfo.language_info || {};
             that.metadata.language_info = langinfo;
             // Mode 'null' should be plain, unhighlighted text.
             var cm_mode = langinfo.codemirror_mode || langinfo.name || 'null';
             that.set_codemirror_mode(cm_mode);
         });
 
         var collapse_time = function (time) {
             var app_height = $('#ipython-main-app').height(); // content height
             var splitter_height = $('div#pager_splitter').outerHeight(true);
             var new_height = app_height - splitter_height;
             that.element.animate({height : new_height + 'px'}, time);
         };
 
         this.element.bind('collapse_pager', function (event, extrap) {
             var time = (extrap !== undefined) ? ((extrap.duration !== undefined ) ? extrap.duration : 'fast') : 'fast';
             collapse_time(time);
         });
 
         var expand_time = function (time) {
             var app_height = $('#ipython-main-app').height(); // content height
             var splitter_height = $('div#pager_splitter').outerHeight(true);
             var pager_height = $('div#pager').outerHeight(true);
             var new_height = app_height - pager_height - splitter_height;
             that.element.animate({height : new_height + 'px'}, time);
         };
 
         this.element.bind('expand_pager', function (event, extrap) {
             var time = (extrap !== undefined) ? ((extrap.duration !== undefined ) ? extrap.duration : 'fast') : 'fast';
             expand_time(time);
         });
         
         // Firefox 22 broke $(window).on("beforeunload")
         // I'm not sure why or how.
         window.onbeforeunload = function (e) {
+            // Raise an event that allows the user to execute custom code on unload
+            try {
+                that.events.trigger('beforeunload.Notebook', {notebook: that});
+            } catch(e) {
+                console.err('Error in "beforeunload.Notebook" event handler.', e);
+            }
+
             // TODO: Make killing the kernel configurable.
             var kill_kernel = false;
             if (kill_kernel) {
                 that.session.delete();
             }
             // if we are autosaving, trigger an autosave on nav-away.
             // still warn, because if we don't the autosave may fail.
             if (that.dirty) {
                 if ( that.autosave_interval ) {
                     // schedule autosave in a timeout
                     // this gives you a chance to forcefully discard changes
                     // by reloading the page if you *really* want to.
                     // the timer doesn't start until you *dismiss* the dialog.
                     setTimeout(function () {
                         if (that.dirty) {
                             that.save_notebook();
                         }
                     }, 1000);
                     return "Autosave in progress, latest changes may be lost.";
                 } else {
                     return "Unsaved changes will be lost.";
                 }
             }
             // Null is the *only* return value that will make the browser not
             // pop up the "don't leave" dialog.
             return null;
         };
     };
     
     Notebook.prototype.warn_nbformat_minor = function (event) {
         /**
          * trigger a warning dialog about missing functionality from newer minor versions
          */
         var v = 'v' + this.nbformat + '.';
         var orig_vs = v + this.nbformat_minor;
         var this_vs = v + this.current_nbformat_minor;
         var msg = "This notebook is version " + orig_vs + ", but we only fully support up to " +
         this_vs + ".  You can still work with this notebook, but cell and output types " +
         "introduced in later notebook versions will not be available.";
 
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Newer Notebook",
             body : msg,
             buttons : {
                 OK : {
                     "class" : "btn-danger"
                 }
             }
         });
     }
 
     /**
      * Set the dirty flag, and trigger the set_dirty.Notebook event
      * 
      * @method set_dirty
      */
     Notebook.prototype.set_dirty = function (value) {
         if (value === undefined) {
             value = true;
         }
         if (this.dirty == value) {
             return;
         }
         this.events.trigger('set_dirty.Notebook', {value: value});
     };
 
     /**
      * Scroll the top of the page to a given cell.
      * 
      * @method scroll_to_cell
      * @param {Number} cell_number An index of the cell to view
      * @param {Number} time Animation time in milliseconds
      * @return {Number} Pixel offset from the top of the container
      */
     Notebook.prototype.scroll_to_cell = function (cell_number, time) {
         var cells = this.get_cells();
         time = time || 0;
         cell_number = Math.min(cells.length-1,cell_number);
         cell_number = Math.max(0             ,cell_number);
         var scroll_value = cells[cell_number].element.position().top-cells[0].element.position().top ;
         this.element.animate({scrollTop:scroll_value}, time);
         return scroll_value;
     };
 
     /**
      * Scroll to the bottom of the page.
      * 
      * @method scroll_to_bottom
      */
     Notebook.prototype.scroll_to_bottom = function () {
         this.element.animate({scrollTop:this.element.get(0).scrollHeight}, 0);
     };
 
     /**
      * Scroll to the top of the page.
      * 
      * @method scroll_to_top
      */
     Notebook.prototype.scroll_to_top = function () {
         this.element.animate({scrollTop:0}, 0);
     };
 
     // Edit Notebook metadata
 
     Notebook.prototype.edit_metadata = function () {
         var that = this;
         dialog.edit_metadata({
             md: this.metadata, 
             callback: function (md) {
                 that.metadata = md;
             },
             name: 'Notebook',
             notebook: this,
             keyboard_manager: this.keyboard_manager});
     };
 
     // Cell indexing, retrieval, etc.
 
     /**
      * Get all cell elements in the notebook.
      * 
      * @method get_cell_elements
      * @return {jQuery} A selector of all cell elements
      */
     Notebook.prototype.get_cell_elements = function () {
         return this.container.find(".cell").not('.cell .cell');
     };
 
     /**
      * Get a particular cell element.
      * 
      * @method get_cell_element
      * @param {Number} index An index of a cell to select
      * @return {jQuery} A selector of the given cell.
      */
     Notebook.prototype.get_cell_element = function (index) {
         var result = null;
         var e = this.get_cell_elements().eq(index);
         if (e.length !== 0) {
             result = e;
         }
         return result;
     };
 
     /**
      * Try to get a particular cell by msg_id.
      * 
      * @method get_msg_cell
      * @param {String} msg_id A message UUID
      * @return {Cell} Cell or null if no cell was found.
      */
     Notebook.prototype.get_msg_cell = function (msg_id) {
         return codecell.CodeCell.msg_cells[msg_id] || null;
     };
 
     /**
      * Count the cells in this notebook.
      * 
      * @method ncells
      * @return {Number} The number of cells in this notebook
      */
     Notebook.prototype.ncells = function () {
         return this.get_cell_elements().length;
     };
 
     /**
      * Get all Cell objects in this notebook.
      * 
      * @method get_cells
      * @return {Array} This notebook's Cell objects
      */
     // TODO: we are often calling cells as cells()[i], which we should optimize
     // to cells(i) or a new method.
     Notebook.prototype.get_cells = function () {
         return this.get_cell_elements().toArray().map(function (e) {
             return $(e).data("cell");
         });
     };
 
     /**
      * Get a Cell object from this notebook.
      * 
      * @method get_cell
      * @param {Number} index An index of a cell to retrieve
      * @return {Cell} Cell or null if no cell was found.
      */
     Notebook.prototype.get_cell = function (index) {
         var result = null;
         var ce = this.get_cell_element(index);
         if (ce !== null) {
             result = ce.data('cell');
         }
         return result;
     };
 
     /**
      * Get the cell below a given cell.
      * 
      * @method get_next_cell
      * @param {Cell} cell The provided cell
      * @return {Cell} the next cell or null if no cell was found.
      */
     Notebook.prototype.get_next_cell = function (cell) {
         var result = null;
         var index = this.find_cell_index(cell);
         if (this.is_valid_cell_index(index+1)) {
             result = this.get_cell(index+1);
         }
         return result;
     };
 
     /**
      * Get the cell above a given cell.
      * 
      * @method get_prev_cell
      * @param {Cell} cell The provided cell
      * @return {Cell} The previous cell or null if no cell was found.
      */
     Notebook.prototype.get_prev_cell = function (cell) {
         var result = null;
         var index = this.find_cell_index(cell);
         if (index !== null && index > 0) {
             result = this.get_cell(index-1);
         }
         return result;
     };
     
     /**
      * Get the numeric index of a given cell.
      * 
      * @method find_cell_index
      * @param {Cell} cell The provided cell
      * @return {Number} The cell's numeric index or null if no cell was found.
      */
     Notebook.prototype.find_cell_index = function (cell) {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell") === cell) {
                 result = index;
             }
         });
         return result;
     };
 
     /**
      * Get a given index , or the selected index if none is provided.
      * 
      * @method index_or_selected
      * @param {Number} index A cell's index
      * @return {Number} The given index, or selected index if none is provided.
      */
     Notebook.prototype.index_or_selected = function (index) {
         var i;
         if (index === undefined || index === null) {
             i = this.get_selected_index();
             if (i === null) {
                 i = 0;
             }
         } else {
             i = index;
         }
         return i;
     };
 
     /**
      * Get the currently selected cell.
      * @method get_selected_cell
      * @return {Cell} The selected cell
      */
     Notebook.prototype.get_selected_cell = function () {
         var index = this.get_selected_index();
         return this.get_cell(index);
     };
 
     /**
      * Check whether a cell index is valid.
      * 
      * @method is_valid_cell_index
      * @param {Number} index A cell index
      * @return True if the index is valid, false otherwise
      */
     Notebook.prototype.is_valid_cell_index = function (index) {
         if (index !== null && index >= 0 && index < this.ncells()) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Get the index of the currently selected cell.
      
      * @method get_selected_index
      * @return {Number} The selected cell's numeric index
      */
     Notebook.prototype.get_selected_index = function () {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell").selected === true) {
                 result = index;
             }
         });
         return result;
     };
 
 
     // Cell selection.
 
     /**
      * Programmatically select a cell.
      * 
      * @method select
      * @param {Number} index A cell's index
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select = function (index) {
         if (this.is_valid_cell_index(index)) {
             var sindex = this.get_selected_index();
             if (sindex !== null && index !== sindex) {
                 // If we are about to select a different cell, make sure we are
                 // first in command mode.
                 if (this.mode !== 'command') {
                     this.command_mode();
                 }
                 this.get_cell(sindex).unselect();
             }
             var cell = this.get_cell(index);
             cell.select();
             if (cell.cell_type === 'heading') {
                 this.events.trigger('selected_cell_type_changed.Notebook',
                     {'cell_type':cell.cell_type,level:cell.level}
                 );
             } else {
                 this.events.trigger('selected_cell_type_changed.Notebook',
                     {'cell_type':cell.cell_type}
                 );
             }
         }
         return this;
     };
 
     /**
      * Programmatically select the next cell.
      *
      * @method select_next
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select_next = function () {
         var index = this.get_selected_index();
         this.select(index+1);
         return this;
     };
 
     /**
      * Programmatically select the previous cell.
      *
      * @method select_prev
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select_prev = function () {
         var index = this.get_selected_index();
         this.select(index-1);
         return this;
     };
 
 
     // Edit/Command mode
 
     /**
      * Gets the index of the cell that is in edit mode.
      *
      * @method get_edit_index
      *
      * @return index {int}
      **/
     Notebook.prototype.get_edit_index = function () {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell").mode === 'edit') {
                 result = index;
             }
         });
         return result;
     };
 
     /**
      * Handle when a a cell blurs and the notebook should enter command mode.
      *
      * @method handle_command_mode
      * @param [cell] {Cell} Cell to enter command mode on.
      **/
     Notebook.prototype.handle_command_mode = function (cell) {
         if (this.mode !== 'command') {
             cell.command_mode();
             this.mode = 'command';
             this.events.trigger('command_mode.Notebook');
             this.keyboard_manager.command_mode();
         }
     };
 
     /**
      * Make the notebook enter command mode.
      *
      * @method command_mode
      **/
     Notebook.prototype.command_mode = function () {
         var cell = this.get_cell(this.get_edit_index());
         if (cell && this.mode !== 'command') {
             // We don't call cell.command_mode, but rather call cell.focus_cell()
             // which will blur and CM editor and trigger the call to
             // handle_command_mode.
             cell.focus_cell();
         }
     };
 
     /**
      * Handle when a cell fires it's edit_mode event.
      *
      * @method handle_edit_mode
      * @param [cell] {Cell} Cell to enter edit mode on.
      **/
     Notebook.prototype.handle_edit_mode = function (cell) {
         if (cell && this.mode !== 'edit') {
             cell.edit_mode();
             this.mode = 'edit';
             this.events.trigger('edit_mode.Notebook');
             this.keyboard_manager.edit_mode();
         }
     };
 
     /**
      * Make a cell enter edit mode.
      *
      * @method edit_mode
      **/
     Notebook.prototype.edit_mode = function () {
         var cell = this.get_selected_cell();
         if (cell && this.mode !== 'edit') {
             cell.unrender();
             cell.focus_editor();
         }
     };
 
     /**
      * Focus the currently selected cell.
      *
      * @method focus_cell
      **/
     Notebook.prototype.focus_cell = function () {
         var cell = this.get_selected_cell();
         if (cell === null) {return;}  // No cell is selected
         cell.focus_cell();
     };
 
     // Cell movement
 
     /**
      * Move given (or selected) cell up and select it.
      * 
      * @method move_cell_up
      * @param [index] {integer} cell index
      * @return {Notebook} This notebook
      **/
     Notebook.prototype.move_cell_up = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i) && i > 0) {
             var pivot = this.get_cell_element(i-1);
             var tomove = this.get_cell_element(i);
             if (pivot !== null && tomove !== null) {
                 tomove.detach();
                 pivot.before(tomove);
                 this.select(i-1);
                 var cell = this.get_selected_cell();
                 cell.focus_cell();
             }
             this.set_dirty(true);
         }
         return this;
     };
 
 
     /**
      * Move given (or selected) cell down and select it
      * 
      * @method move_cell_down
      * @param [index] {integer} cell index
      * @return {Notebook} This notebook
      **/
     Notebook.prototype.move_cell_down = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i) && this.is_valid_cell_index(i+1)) {
             var pivot = this.get_cell_element(i+1);
             var tomove = this.get_cell_element(i);
             if (pivot !== null && tomove !== null) {
                 tomove.detach();
                 pivot.after(tomove);
                 this.select(i+1);
                 var cell = this.get_selected_cell();
                 cell.focus_cell();
             }
         }
         this.set_dirty();
         return this;
     };
 
 
     // Insertion, deletion.
 
     /**
      * Delete a cell from the notebook.
      * 
      * @method delete_cell
      * @param [index] A cell's numeric index
      * @return {Notebook} This notebook
      */
     Notebook.prototype.delete_cell = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (!cell.is_deletable()) {
             return this;
         }
 
         this.undelete_backup = cell.toJSON();
         $('#undelete_cell').removeClass('disabled');
         if (this.is_valid_cell_index(i)) {
             var old_ncells = this.ncells();
             var ce = this.get_cell_element(i);
             ce.remove();
             if (i === 0) {
                 // Always make sure we have at least one cell.
                 if (old_ncells === 1) {
                     this.insert_cell_below('code');
                 }
                 this.select(0);
                 this.undelete_index = 0;
                 this.undelete_below = false;
             } else if (i === old_ncells-1 && i !== 0) {
                 this.select(i-1);
                 this.undelete_index = i - 1;
                 this.undelete_below = true;
             } else {
                 this.select(i);
                 this.undelete_index = i;
                 this.undelete_below = false;
             }
             this.events.trigger('delete.Cell', {'cell': cell, 'index': i});
             this.set_dirty(true);
         }
         return this;
     };
 
     /**
      * Restore the most recently deleted cell.
      * 
      * @method undelete
      */
     Notebook.prototype.undelete_cell = function() {
         if (this.undelete_backup !== null && this.undelete_index !== null) {
             var current_index = this.get_selected_index();
             if (this.undelete_index < current_index) {
                 current_index = current_index + 1;
             }
             if (this.undelete_index >= this.ncells()) {
                 this.select(this.ncells() - 1);
             }
             else {
                 this.select(this.undelete_index);
             }
             var cell_data = this.undelete_backup;
             var new_cell = null;
             if (this.undelete_below) {
                 new_cell = this.insert_cell_below(cell_data.cell_type);
             } else {
                 new_cell = this.insert_cell_above(cell_data.cell_type);
             }
             new_cell.fromJSON(cell_data);
             if (this.undelete_below) {
                 this.select(current_index+1);
             } else {
                 this.select(current_index);
             }
             this.undelete_backup = null;
             this.undelete_index = null;
         }
         $('#undelete_cell').addClass('disabled');
     };
 
     /**
      * Insert a cell so that after insertion the cell is at given index.
      *
      * If cell type is not provided, it will default to the type of the
      * currently active cell.
      *
      * Similar to insert_above, but index parameter is mandatory
      *
      * Index will be brought back into the accessible range [0,n]
      *
      * @method insert_cell_at_index
      * @param [type] {string} in ['code','markdown', 'raw'], defaults to 'code'
      * @param [index] {int} a valid index where to insert cell
      *
      * @return cell {cell|null} created cell or null
      **/
     Notebook.prototype.insert_cell_at_index = function(type, index){
 
         var ncells = this.ncells();
         index = Math.min(index, ncells);
         index = Math.max(index, 0);
         var cell = null;
         type = type || this.default_cell_type;
         if (type === 'above') {
             if (index > 0) {
                 type = this.get_cell(index-1).cell_type;
             } else {
                 type = 'code';
             }
         } else if (type === 'below') {
             if (index < ncells) {
                 type = this.get_cell(index).cell_type;
             } else {
                 type = 'code';
             }
         } else if (type === 'selected') {
             type = this.get_selected_cell().cell_type;
         }
 
         if (ncells === 0 || this.is_valid_cell_index(index) || index === ncells) {
             var cell_options = {
                 events: this.events, 
                 config: this.config, 
                 keyboard_manager: this.keyboard_manager, 
                 notebook: this,
                 tooltip: this.tooltip
             };
             switch(type) {
             case 'code':
                 cell = new codecell.CodeCell(this.kernel, cell_options);
                 cell.set_input_prompt();
                 break;
             case 'markdown':
                 cell = new textcell.MarkdownCell(cell_options);
                 break;
             case 'raw':
                 cell = new textcell.RawCell(cell_options);
                 break;
             default:
                 console.log("Unrecognized cell type: ", type, cellmod);
                 cell = new cellmod.UnrecognizedCell(cell_options);
             }
 
             if(this._insert_element_at_index(cell.element,index)) {
                 cell.render();
                 this.events.trigger('create.Cell', {'cell': cell, 'index': index});
                 cell.refresh();
                 // We used to select the cell after we refresh it, but there
                 // are now cases were this method is called where select is
                 // not appropriate. The selection logic should be handled by the
                 // caller of the the top level insert_cell methods.
                 this.set_dirty(true);
             }
         }
         return cell;
 
     };
 
     /**
      * Insert an element at given cell index.
      *
      * @method _insert_element_at_index
      * @param element {dom_element} a cell element
      * @param [index] {int} a valid index where to inser cell
      * @private
      *
      * return true if everything whent fine.
      **/
     Notebook.prototype._insert_element_at_index = function(element, index){
         if (element === undefined){
             return false;
         }
 
         var ncells = this.ncells();
 
         if (ncells === 0) {
             // special case append if empty
             this.element.find('div.end_space').before(element);
         } else if ( ncells === index ) {
             // special case append it the end, but not empty
             this.get_cell_element(index-1).after(element);
         } else if (this.is_valid_cell_index(index)) {
             // otherwise always somewhere to append to
             this.get_cell_element(index).before(element);
         } else {
             return false;
         }
 
         if (this.undelete_index !== null && index <= this.undelete_index) {
             this.undelete_index = this.undelete_index + 1;
             this.set_dirty(true);
         }
         return true;
     };
 
     /**
      * Insert a cell of given type above given index, or at top
      * of notebook if index smaller than 0.
      *
      * default index value is the one of currently selected cell
      *
      * @method insert_cell_above
      * @param [type] {string} cell type
      * @param [index] {integer}
      *
      * @return handle to created cell or null
      **/
     Notebook.prototype.insert_cell_above = function (type, index) {
         index = this.index_or_selected(index);
         return this.insert_cell_at_index(type, index);
     };
 
     /**
      * Insert a cell of given type below given index, or at bottom
      * of notebook if index greater than number of cells
      *
      * default index value is the one of currently selected cell
      *
      * @method insert_cell_below
      * @param [type] {string} cell type
      * @param [index] {integer}
      *
      * @return handle to created cell or null
      *
      **/
     Notebook.prototype.insert_cell_below = function (type, index) {
         index = this.index_or_selected(index);
         return this.insert_cell_at_index(type, index+1);
     };
 
 
     /**
      * Insert cell at end of notebook
      *
      * @method insert_cell_at_bottom
      * @param {String} type cell type
      *
      * @return the added cell; or null
      **/
     Notebook.prototype.insert_cell_at_bottom = function (type){
         var len = this.ncells();
         return this.insert_cell_below(type,len-1);
     };
 
     /**
      * Turn a cell into a code cell.
      * 
      * @method to_code
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_code = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var source_cell = this.get_cell(i);
             if (!(source_cell instanceof codecell.CodeCell)) {
                 var target_cell = this.insert_cell_below('code',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 //metadata
                 target_cell.metadata = source_cell.metadata;
 
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
 
     /**
      * Turn a cell into a Markdown cell.
      * 
      * @method to_markdown
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_markdown = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var source_cell = this.get_cell(i);
 
             if (!(source_cell instanceof textcell.MarkdownCell)) {
                 var target_cell = this.insert_cell_below('markdown',i);
                 var text = source_cell.get_text();
 
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 // metadata
                 target_cell.metadata = source_cell.metadata;
                 // We must show the editor before setting its contents
                 target_cell.unrender();
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
                     target_cell.render();
                 }
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
 
     /**
      * Turn a cell into a raw text cell.
      * 
      * @method to_raw
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_raw = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var target_cell = null;
             var source_cell = this.get_cell(i);
 
             if (!(source_cell instanceof textcell.RawCell)) {
                 target_cell = this.insert_cell_below('raw',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 //metadata
                 target_cell.metadata = source_cell.metadata;
                 // We must show the editor before setting its contents
                 target_cell.unrender();
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
     
     Notebook.prototype._warn_heading = function () {
         /**
          * warn about heading cells being removed
          */
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Use markdown headings",
             body : $("<p/>").text(
                 'IPython no longer uses special heading cells. ' + 
                 'Instead, write your headings in Markdown cells using # characters:'
             ).append($('<pre/>').text(
                 '## This is a level 2 heading'
             )),
             buttons : {
                 "OK" : {}
             }
         });
     };
     
     /**
      * Turn a cell into a markdown cell with a heading.
      * 
      * @method to_heading
      * @param {Number} [index] A cell's index
      * @param {Number} [level] A heading level (e.g., 1 for h1)
      */
     Notebook.prototype.to_heading = function (index, level) {
         this.to_markdown(index);
         level = level || 1;
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var cell = this.get_cell(i);
             cell.set_heading_level(level);
             this.set_dirty(true);
         }
     };
 
 
     // Cut/Copy/Paste
 
     /**
      * Enable UI elements for pasting cells.
      * 
      * @method enable_paste
      */
     Notebook.prototype.enable_paste = function () {
         var that = this;
         if (!this.paste_enabled) {
             $('#paste_cell_replace').removeClass('disabled')
                 .on('click', function () {that.paste_cell_replace();});
             $('#paste_cell_above').removeClass('disabled')
                 .on('click', function () {that.paste_cell_above();});
             $('#paste_cell_below').removeClass('disabled')
                 .on('click', function () {that.paste_cell_below();});
             this.paste_enabled = true;
         }
     };
 
     /**
      * Disable UI elements for pasting cells.
      * 
      * @method disable_paste
      */
     Notebook.prototype.disable_paste = function () {
         if (this.paste_enabled) {
             $('#paste_cell_replace').addClass('disabled').off('click');
             $('#paste_cell_above').addClass('disabled').off('click');
             $('#paste_cell_below').addClass('disabled').off('click');
             this.paste_enabled = false;
         }
     };
 
     /**
      * Cut a cell.
      * 
      * @method cut_cell
      */
     Notebook.prototype.cut_cell = function () {
         this.copy_cell();
         this.delete_cell();
     };
 
     /**
      * Copy a cell.
      * 
      * @method copy_cell
      */
     Notebook.prototype.copy_cell = function () {
         var cell = this.get_selected_cell();
         this.clipboard = cell.toJSON();
         // remove undeletable status from the copied cell
         if (this.clipboard.metadata.deletable !== undefined) {
             delete this.clipboard.metadata.deletable;
         }
         this.enable_paste();
     };
 
     /**
      * Replace the selected cell with a cell in the clipboard.
      * 
      * @method paste_cell_replace
      */
     Notebook.prototype.paste_cell_replace = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_above(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             var old_cell = this.get_next_cell(new_cell);
             this.delete_cell(this.find_cell_index(old_cell));
             this.select(this.find_cell_index(new_cell));
         }
     };
 
     /**
      * Paste a cell from the clipboard above the selected cell.
      * 
      * @method paste_cell_above
      */
     Notebook.prototype.paste_cell_above = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_above(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             new_cell.focus_cell();
         }
     };
 
     /**
      * Paste a cell from the clipboard below the selected cell.
      * 
      * @method paste_cell_below
      */
     Notebook.prototype.paste_cell_below = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_below(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             new_cell.focus_cell();
         }
     };
 
     // Split/merge
 
     /**
      * Split the selected cell into two, at the cursor.
      * 
      * @method split_cell
      */
     Notebook.prototype.split_cell = function () {
         var cell = this.get_selected_cell();
         if (cell.is_splittable()) {
             var texta = cell.get_pre_cursor();
             var textb = cell.get_post_cursor();
             cell.set_text(textb);
             var new_cell = this.insert_cell_above(cell.cell_type);
             // Unrender the new cell so we can call set_text.
             new_cell.unrender();
             new_cell.set_text(texta);
         }
     };
 
     /**
      * Combine the selected cell into the cell above it.
      * 
      * @method merge_cell_above
      */
     Notebook.prototype.merge_cell_above = function () {
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
         if (!cell.is_mergeable()) {
             return;
         }
         if (index > 0) {
             var upper_cell = this.get_cell(index-1);
             if (!upper_cell.is_mergeable()) {
                 return;
             }
             var upper_text = upper_cell.get_text();
             var text = cell.get_text();
             if (cell instanceof codecell.CodeCell) {
                 cell.set_text(upper_text+'\n'+text);
             } else {
                 cell.unrender(); // Must unrender before we set_text.
                 cell.set_text(upper_text+'\n\n'+text);
                 if (render) {
                     // The rendered state of the final cell should match
                     // that of the original selected cell;
                     cell.render();
                 }
             }
             this.delete_cell(index-1);
             this.select(this.find_cell_index(cell));
         }
     };
 
     /**
      * Combine the selected cell into the cell below it.
      * 
      * @method merge_cell_below
      */
     Notebook.prototype.merge_cell_below = function () {
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
         if (!cell.is_mergeable()) {
             return;
         }
         if (index < this.ncells()-1) {
             var lower_cell = this.get_cell(index+1);
             if (!lower_cell.is_mergeable()) {
                 return;
             }
             var lower_text = lower_cell.get_text();
             var text = cell.get_text();
             if (cell instanceof codecell.CodeCell) {
                 cell.set_text(text+'\n'+lower_text);
             } else {
                 cell.unrender(); // Must unrender before we set_text.
                 cell.set_text(text+'\n\n'+lower_text);
                 if (render) {
                     // The rendered state of the final cell should match
                     // that of the original selected cell;
                     cell.render();
                 }
             }
             this.delete_cell(index+1);
             this.select(this.find_cell_index(cell));
         }
     };
 
 
     // Cell collapsing and output clearing
 
     /**
      * Hide a cell's output.
      * 
      * @method collapse_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.collapse_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.collapse_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Hide each code cell's output area.
      * 
      * @method collapse_all_output
      */
     Notebook.prototype.collapse_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.collapse_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Show a cell's output.
      * 
      * @method expand_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.expand_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.expand_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Expand each code cell's output area, and remove scrollbars.
      * 
      * @method expand_all_output
      */
     Notebook.prototype.expand_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.expand_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Clear the selected CodeCell's output area.
      * 
      * @method clear_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.clear_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.clear_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Clear each code cell's output area.
      * 
      * @method clear_all_output
      */
     Notebook.prototype.clear_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.clear_output();
             }
         });
         this.set_dirty(true);
     };
 
     /**
      * Scroll the selected CodeCell's output area.
      * 
      * @method scroll_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.scroll_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.scroll_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Expand each code cell's output area, and add a scrollbar for long output.
      * 
      * @method scroll_all_output
      */
     Notebook.prototype.scroll_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.scroll_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /** Toggle whether a cell's output is collapsed or expanded.
      * 
      * @method toggle_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.toggle_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.toggle_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Hide/show the output of all cells.
      * 
      * @method toggle_all_output
      */
     Notebook.prototype.toggle_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.toggle_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Toggle a scrollbar for long cell outputs.
      * 
      * @method toggle_output_scroll
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.toggle_output_scroll = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.toggle_output_scroll();
             this.set_dirty(true);
         }
     };
 
     /**
      * Toggle the scrolling of long output on all cells.
      * 
      * @method toggle_all_output_scrolling
      */
     Notebook.prototype.toggle_all_output_scroll = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.toggle_output_scroll();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     // Other cell functions: line numbers, ...
 
     /**
      * Toggle line numbers in the selected cell's input area.
      * 
      * @method cell_toggle_line_numbers
      */
     Notebook.prototype.cell_toggle_line_numbers = function() {
         this.get_selected_cell().toggle_line_numbers();
     };
     
     /**
      * Set the codemirror mode for all code cells, including the default for
      * new code cells.
      * 
      * @method set_codemirror_mode
      */
     Notebook.prototype.set_codemirror_mode = function(newmode){
         if (newmode === this.codemirror_mode) {
             return;
         }
         this.codemirror_mode = newmode;
         codecell.CodeCell.options_default.cm_config.mode = newmode;
         
         var that = this;
         utils.requireCodeMirrorMode(newmode, function (spec) {
             that.get_cells().map(function(cell, i) {
                 if (cell.cell_type === 'code'){
                     cell.code_mirror.setOption('mode', spec);
                     // This is currently redundant, because cm_config ends up as
                     // codemirror's own .options object, but I don't want to
                     // rely on that.
                     cell.cm_config.mode = spec;
                 }
             });
         });
     };
 
     // Session related things
 
     /**
      * Start a new session and set it on each code cell.
      * 
      * @method start_session
      */
     Notebook.prototype.start_session = function (kernel_name) {
         if (this._session_starting) {
             throw new session.SessionAlreadyStarting();
         }
         this._session_starting = true;
 
         var options = {
             base_url: this.base_url,
             ws_url: this.ws_url,
             notebook_path: this.notebook_path,
             notebook_name: this.notebook_name,
             kernel_name: kernel_name,
             notebook: this
         };
 
         var success = $.proxy(this._session_started, this);
         var failure = $.proxy(this._session_start_failed, this);
 
         if (this.session !== null) {
             this.session.restart(options, success, failure);
         } else {
             this.session = new session.Session(options);
             this.session.start(success, failure);
         }
     };
 
 
     /**
      * Once a session is started, link the code cells to the kernel and pass the 
      * comm manager to the widget manager
      *
      */
     Notebook.prototype._session_started = function (){
         this._session_starting = false;
         this.kernel = this.session.kernel;
         var ncells = this.ncells();
         for (var i=0; i<ncells; i++) {
             var cell = this.get_cell(i);
             if (cell instanceof codecell.CodeCell) {
                 cell.set_kernel(this.session.kernel);
             }
         }
     };
     Notebook.prototype._session_start_failed = function (jqxhr, status, error){
         this._session_starting = false;
         utils.log_ajax_error(jqxhr, status, error);
     };
     
     /**
      * Prompt the user to restart the IPython kernel.
      * 
      * @method restart_kernel
      */
     Notebook.prototype.restart_kernel = function () {
         var that = this;
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Restart kernel or continue running?",
             body : $("<p/>").text(
                 'Do you want to restart the current kernel?  You will lose all variables defined in it.'
             ),
             buttons : {
                 "Continue running" : {},
                 "Restart" : {
                     "class" : "btn-danger",
                     "click" : function() {
                         that.kernel.restart();
                     }
                 }
             }
         });
     };
     
     /**
      * Execute or render cell outputs and go into command mode.
      * 
      * @method execute_cell
      */
     Notebook.prototype.execute_cell = function () {
         /**
          * mode = shift, ctrl, alt
          */
         var cell = this.get_selected_cell();
         
         cell.execute();
         this.command_mode();
         this.set_dirty(true);
     };
 
     /**
      * Execute or render cell outputs and insert a new cell below.
      * 
      * @method execute_cell_and_insert_below
      */
     Notebook.prototype.execute_cell_and_insert_below = function () {
         var cell = this.get_selected_cell();
         var cell_index = this.find_cell_index(cell);
         
         cell.execute();
 
         // If we are at the end always insert a new cell and return
         if (cell_index === (this.ncells()-1)) {
             this.command_mode();
             this.insert_cell_below();
             this.select(cell_index+1);
             this.edit_mode();
             this.scroll_to_bottom();
             this.set_dirty(true);
             return;
         }
 
         this.command_mode();
         this.insert_cell_below();
         this.select(cell_index+1);
         this.edit_mode();
         this.set_dirty(true);
     };
 
     /**
      * Execute or render cell outputs and select the next cell.
      * 
      * @method execute_cell_and_select_below
      */
     Notebook.prototype.execute_cell_and_select_below = function () {
 
         var cell = this.get_selected_cell();
         var cell_index = this.find_cell_index(cell);
         
         cell.execute();
 
         // If we are at the end always insert a new cell and return
         if (cell_index === (this.ncells()-1)) {
             this.command_mode();
             this.insert_cell_below();
             this.select(cell_index+1);
             this.edit_mode();
             this.scroll_to_bottom();
             this.set_dirty(true);
             return;
         }
 
         this.command_mode();
         this.select(cell_index+1);
         this.focus_cell();
         this.set_dirty(true);
     };
 
     /**
      * Execute all cells below the selected cell.
      * 
      * @method execute_cells_below
      */
     Notebook.prototype.execute_cells_below = function () {
         this.execute_cell_range(this.get_selected_index(), this.ncells());
         this.scroll_to_bottom();
     };
 
     /**
      * Execute all cells above the selected cell.
      * 
      * @method execute_cells_above
      */
     Notebook.prototype.execute_cells_above = function () {
         this.execute_cell_range(0, this.get_selected_index());
     };
 
     /**
      * Execute all cells.
      * 
      * @method execute_all_cells
      */
     Notebook.prototype.execute_all_cells = function () {
         this.execute_cell_range(0, this.ncells());
         this.scroll_to_bottom();
     };
 
     /**
      * Execute a contiguous range of cells.
      * 
      * @method execute_cell_range
      * @param {Number} start Index of the first cell to execute (inclusive)
      * @param {Number} end Index of the last cell to execute (exclusive)
      */
     Notebook.prototype.execute_cell_range = function (start, end) {
         this.command_mode();
         for (var i=start; i<end; i++) {
             this.select(i);
             this.execute_cell();
         }
     };
 
     // Persistance and loading
 
     /**
      * Getter method for this notebook's name.
      * 
      * @method get_notebook_name
      * @return {String} This notebook's name (excluding file extension)
      */
     Notebook.prototype.get_notebook_name = function () {
         var nbname = this.notebook_name.substring(0,this.notebook_name.length-6);
         return nbname;
     };
 
     /**
      * Setter method for this notebook's name.
      *
      * @method set_notebook_name
      * @param {String} name A new name for this notebook
      */
     Notebook.prototype.set_notebook_name = function (name) {
         var parent = utils.url_path_split(this.notebook_path)[0];
         this.notebook_name = name;
         this.notebook_path = utils.url_path_join(parent, name);
     };
 
     /**
      * Check that a notebook's name is valid.
      * 
      * @method test_notebook_name
      * @param {String} nbname A name for this notebook
      * @return {Boolean} True if the name is valid, false if invalid
      */
     Notebook.prototype.test_notebook_name = function (nbname) {
         nbname = nbname || '';
         if (nbname.length>0 && !this.notebook_name_blacklist_re.test(nbname)) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Load a notebook from JSON (.ipynb).
      * 
      * @method fromJSON
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.fromJSON = function (data) {
 
         var content = data.content;
         var ncells = this.ncells();
         var i;
         for (i=0; i<ncells; i++) {
             // Always delete cell 0 as they get renumbered as they are deleted.
             this.delete_cell(0);
         }
         // Save the metadata and name.
         this.metadata = content.metadata;
         this.notebook_name = data.name;
         this.notebook_path = data.path;
         var trusted = true;
         
         // Trigger an event changing the kernel spec - this will set the default
         // codemirror mode
         if (this.metadata.kernelspec !== undefined) {
             this.events.trigger('spec_changed.Kernel', this.metadata.kernelspec);
         }
         
         // Set the codemirror mode from language_info metadata
         if (this.metadata.language_info !== undefined) {
             var langinfo = this.metadata.language_info;
             // Mode 'null' should be plain, unhighlighted text.
             var cm_mode = langinfo.codemirror_mode || langinfo.name || 'null';
             this.set_codemirror_mode(cm_mode);
         }
         
         var new_cells = content.cells;
         ncells = new_cells.length;
         var cell_data = null;
         var new_cell = null;
         for (i=0; i<ncells; i++) {
             cell_data = new_cells[i];
             new_cell = this.insert_cell_at_index(cell_data.cell_type, i);
             new_cell.fromJSON(cell_data);
             if (new_cell.cell_type == 'code' && !new_cell.output_area.trusted) {
                 trusted = false;
             }
         }
         if (trusted !== this.trusted) {
             this.trusted = trusted;
             this.events.trigger("trust_changed.Notebook", trusted);
         }
     };
 
     /**
      * Dump this notebook into a JSON-friendly object.
      * 
      * @method toJSON
      * @return {Object} A JSON-friendly representation of this notebook.
      */
     Notebook.prototype.toJSON = function () {
         /**
          * remove the conversion indicator, which only belongs in-memory
          */
         delete this.metadata.orig_nbformat;
         delete this.metadata.orig_nbformat_minor;
 
         var cells = this.get_cells();
         var ncells = cells.length;
         var cell_array = new Array(ncells);
         var trusted = true;
         for (var i=0; i<ncells; i++) {
             var cell = cells[i];
             if (cell.cell_type == 'code' && !cell.output_area.trusted) {
                 trusted = false;
             }
             cell_array[i] = cell.toJSON();
         }
         var data = {
             cells: cell_array,
             metadata: this.metadata,
             nbformat: this.nbformat,
             nbformat_minor: this.nbformat_minor
         };
         if (trusted != this.trusted) {
             this.trusted = trusted;
             this.events.trigger("trust_changed.Notebook", trusted);
         }
         return data;
     };
 
     /**
      * Start an autosave timer, for periodically saving the notebook.
      * 
      * @method set_autosave_interval
      * @param {Integer} interval the autosave interval in milliseconds
      */
     Notebook.prototype.set_autosave_interval = function (interval) {
         var that = this;
         // clear previous interval, so we don't get simultaneous timers
         if (this.autosave_timer) {
             clearInterval(this.autosave_timer);
         }
         if (!this.writable) {
             // disable autosave if not writable
             interval = 0;
         }
         
         this.autosave_interval = this.minimum_autosave_interval = interval;
         if (interval) {
             this.autosave_timer = setInterval(function() {
                 if (that.dirty) {
                     that.save_notebook();
                 }
             }, interval);
             this.events.trigger("autosave_enabled.Notebook", interval);
         } else {
             this.autosave_timer = null;
             this.events.trigger("autosave_disabled.Notebook");
         }
     };
     
     /**
      * Save this notebook on the server. This becomes a notebook instance's
      * .save_notebook method *after* the entire notebook has been loaded.
      * 
      * @method save_notebook
      */
     Notebook.prototype.save_notebook = function () {
         if (!this._fully_loaded) {
             this.events.trigger('notebook_save_failed.Notebook',
                 new Error("Load failed, save is disabled")
             );
             return;
         } else if (!this.writable) {
             this.events.trigger('notebook_save_failed.Notebook',
                 new Error("Notebook is read-only")
             );
             return;
         }
 
         // Create a JSON model to be sent to the server.
         var model = {
             type : "notebook",
             content : this.toJSON()
         };
         // time the ajax call for autosave tuning purposes.
         var start =  new Date().getTime();
 
         var that = this;
         return this.contents.save(this.notebook_path, model).then(
                 $.proxy(this.save_notebook_success, this, start),
                 function (error) {
                     that.events.trigger('notebook_save_failed.Notebook', error);
                 }
             );
     };
     
     /**
      * Success callback for saving a notebook.
      * 
      * @method save_notebook_success
      * @param {Integer} start Time when the save request start
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.save_notebook_success = function (start, data) {
         this.set_dirty(false);
         if (data.message) {
             // save succeeded, but validation failed.
             var body = $("<div>");
             var title = "Notebook validation failed";
 
             body.append($("<p>").text(
                 "The save operation succeeded," +
                 " but the notebook does not appear to be valid." +
                 " The validation error was:"
             )).append($("<div>").addClass("validation-error").append(
                 $("<pre>").text(data.message)
             ));
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title: title,
                 body: body,
                 buttons : {
                     OK : {
                         "class" : "btn-primary"
                     }
                 }
             });
         }
         this.events.trigger('notebook_saved.Notebook');
         this._update_autosave_interval(start);
         if (this._checkpoint_after_save) {
             this.create_checkpoint();
             this._checkpoint_after_save = false;
         }
     };
     
     /**
      * update the autosave interval based on how long the last save took
      * 
      * @method _update_autosave_interval
      * @param {Integer} timestamp when the save request started
      */
     Notebook.prototype._update_autosave_interval = function (start) {
         var duration = (new Date().getTime() - start);
         if (this.autosave_interval) {
             // new save interval: higher of 10x save duration or parameter (default 30 seconds)
             var interval = Math.max(10 * duration, this.minimum_autosave_interval);
             // round to 10 seconds, otherwise we will be setting a new interval too often
             interval = 10000 * Math.round(interval / 10000);
             // set new interval, if it's changed
             if (interval != this.autosave_interval) {
                 this.set_autosave_interval(interval);
             }
         }
     };
 
     /**
      * Explicitly trust the output of this notebook.
      *
      * @method trust_notebook
      */
     Notebook.prototype.trust_notebook = function () {
         var body = $("<div>").append($("<p>")
             .text("A trusted IPython notebook may execute hidden malicious code ")
             .append($("<strong>")
                 .append(
                     $("<em>").text("when you open it")
                 )
             ).append(".").append(
                 " Selecting trust will immediately reload this notebook in a trusted state."
             ).append(
                 " For more information, see the "
             ).append($("<a>").attr("href", "http://ipython.org/ipython-doc/2/notebook/security.html")
                 .text("IPython security documentation")
             ).append(".")
         );
 
         var nb = this;
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title: "Trust this notebook?",
             body: body,
 
             buttons: {
                 Cancel : {},
                 Trust : {
                     class : "btn-danger",
                     click : function () {
                         var cells = nb.get_cells();
                         for (var i = 0; i < cells.length; i++) {
                             var cell = cells[i];
                             if (cell.cell_type == 'code') {
                                 cell.output_area.trusted = true;
                             }
                         }
                         nb.events.on('notebook_saved.Notebook', function () {
                             window.location.reload();
                         });
                         nb.save_notebook();
                     }
                 }
             }
         });
     };
 
     Notebook.prototype.copy_notebook = function () {
         var that = this;
         var base_url = this.base_url;
         var w = window.open();
         var parent = utils.url_path_split(this.notebook_path)[0];
         this.contents.copy(this.notebook_path, parent).then(
             function (data) {
                 w.location = utils.url_join_encode(
                     base_url, 'notebooks', data.path
                 );
             },
             function(error) {
                 w.close();
                 that.events.trigger('notebook_copy_failed', error);
             }
         );
     };
 
     Notebook.prototype.rename = function (new_name) {
         if (!new_name.match(/\.ipynb$/)) {
             new_name = new_name + ".ipynb";
         }
 
         var that = this;
         var parent = utils.url_path_split(this.notebook_path)[0];
         var new_path = utils.url_path_join(parent, new_name);
         return this.contents.rename(this.notebook_path, new_path).then(
             function (json) {
                 that.notebook_name = json.name;
                 that.notebook_path = json.path;
                 that.session.rename_notebook(json.path);
                 that.events.trigger('notebook_renamed.Notebook', json);
             }
         );
     };
 
     Notebook.prototype.delete = function () {
         this.contents.delete(this.notebook_path);
     };
 
     /**
      * Request a notebook's data from the server.
      * 
      * @method load_notebook
      * @param {String} notebook_path A notebook to load
      */
     Notebook.prototype.load_notebook = function (notebook_path) {
         this.notebook_path = notebook_path;
         this.notebook_name = utils.url_path_split(this.notebook_path)[1];
         this.events.trigger('notebook_loading.Notebook');
         this.contents.get(notebook_path, {type: 'notebook'}).then(
             $.proxy(this.load_notebook_success, this),
             $.proxy(this.load_notebook_error, this)
         );
     };
 
     /**
      * Success callback for loading a notebook from the server.
      * 
      * Load notebook data from the JSON response.
      * 
      * @method load_notebook_success
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.load_notebook_success = function (data) {
         var failed, msg;
         try {
             this.fromJSON(data);
         } catch (e) {
             failed = e;
             console.log("Notebook failed to load from JSON:", e);
         }
         if (failed || data.message) {
             // *either* fromJSON failed or validation failed
             var body = $("<div>");
             var title;
             if (failed) {
                 title = "Notebook failed to load";
                 body.append($("<p>").text(
                     "The error was: "
                 )).append($("<div>").addClass("js-error").text(
                     failed.toString()
                 )).append($("<p>").text(
                     "See the error console for details."
                 ));
             } else {
                 title = "Notebook validation failed";
             }
 
             if (data.message) {
                 if (failed) {
                     msg = "The notebook also failed validation:";
                 } else {
                     msg = "An invalid notebook may not function properly." +
                     " The validation error was:";
                 }
                 body.append($("<p>").text(
                     msg
                 )).append($("<div>").addClass("validation-error").append(
                     $("<pre>").text(data.message)
                 ));
             }
 
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title: title,
                 body: body,
                 buttons : {
                     OK : {
                         "class" : "btn-primary"
                     }
                 }
             });
         }
         if (this.ncells() === 0) {
             this.insert_cell_below('code');
             this.edit_mode(0);
         } else {
             this.select(0);
             this.handle_command_mode(this.get_cell(0));
         }
         this.set_dirty(false);
         this.scroll_to_top();
         this.writable = data.writable || false;
         var nbmodel = data.content;
         var orig_nbformat = nbmodel.metadata.orig_nbformat;
         var orig_nbformat_minor = nbmodel.metadata.orig_nbformat_minor;
         if (orig_nbformat !== undefined && nbmodel.nbformat !== orig_nbformat) {
             var src;
             if (nbmodel.nbformat > orig_nbformat) {
                 src = " an older notebook format ";
             } else {
                 src = " a newer notebook format ";
             }
             
             msg = "This notebook has been converted from" + src +
             "(v"+orig_nbformat+") to the current notebook " +
             "format (v"+nbmodel.nbformat+"). The next time you save this notebook, the " +
             "current notebook format will be used.";
             
             if (nbmodel.nbformat > orig_nbformat) {
                 msg += " Older versions of IPython may not be able to read the new format.";
             } else {
                 msg += " Some features of the original notebook may not be available.";
             }
             msg += " To preserve the original version, close the " +
                 "notebook without saving it.";
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title : "Notebook converted",
                 body : msg,
                 buttons : {
                     OK : {
                         class : "btn-primary"
                     }
                 }
             });
         } else if (this.nbformat_minor < nbmodel.nbformat_minor) {
             this.nbformat_minor = nbmodel.nbformat_minor;
         }
         
         // Create the session after the notebook is completely loaded to prevent
         // code execution upon loading, which is a security risk.
         if (this.session === null) {
             var kernel_name;
             if (this.metadata.kernelspec) {
                 var kernelspec = this.metadata.kernelspec || {};
                 kernel_name = kernelspec.name;
             } else {
                 kernel_name = utils.get_url_param('kernel_name');
             }
             this.start_session(kernel_name);
         }
         // load our checkpoint list
         this.list_checkpoints();
         
         // load toolbar state
         if (this.metadata.celltoolbar) {
             celltoolbar.CellToolbar.global_show();
             celltoolbar.CellToolbar.activate_preset(this.metadata.celltoolbar);
         } else {
             celltoolbar.CellToolbar.global_hide();
         }
         
         if (!this.writable) {
             this.set_autosave_interval(0);
             this.events.trigger('notebook_read_only.Notebook');
         }
         
         // now that we're fully loaded, it is safe to restore save functionality
         this._fully_loaded = true;
         this.events.trigger('notebook_loaded.Notebook');
     };
 
     /**
      * Failure callback for loading a notebook from the server.
      * 
      * @method load_notebook_error
      * @param {Error} error
      */
     Notebook.prototype.load_notebook_error = function (error) {
         this.events.trigger('notebook_load_failed.Notebook', error);
         var msg;
         if (error.name === utils.XHR_ERROR && error.xhr.status === 500) {
             utils.log_ajax_error(error.xhr, error.xhr_status, error.xhr_error);
             msg = "An unknown error occurred while loading this notebook. " +
             "This version can load notebook formats " +
             "v" + this.nbformat + " or earlier. See the server log for details.";
         } else {
             msg = error.message;
         }
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title: "Error loading notebook",
             body : msg,
             buttons : {
                 "OK": {}
             }
         });
     };
 
     /*********************  checkpoint-related  *********************/
     
     /**
      * Save the notebook then immediately create a checkpoint.
      * 
      * @method save_checkpoint
      */
     Notebook.prototype.save_checkpoint = function () {
         this._checkpoint_after_save = true;
         this.save_notebook();
     };
     
     /**
      * Add a checkpoint for this notebook.
      * for use as a callback from checkpoint creation.
      * 
      * @method add_checkpoint
      */
     Notebook.prototype.add_checkpoint = function (checkpoint) {
         var found = false;
         for (var i = 0; i < this.checkpoints.length; i++) {
             var existing = this.checkpoints[i];
             if (existing.id == checkpoint.id) {
                 found = true;
                 this.checkpoints[i] = checkpoint;
                 break;
             }
         }
         if (!found) {
             this.checkpoints.push(checkpoint);
         }
         this.last_checkpoint = this.checkpoints[this.checkpoints.length - 1];
     };
     
     /**
      * List checkpoints for this notebook.
      * 
      * @method list_checkpoints
      */
     Notebook.prototype.list_checkpoints = function () {
         var that = this;
         this.contents.list_checkpoints(this.notebook_path).then(
             $.proxy(this.list_checkpoints_success, this),
             function(error) {
                 that.events.trigger('list_checkpoints_failed.Notebook', error);
             }
         );
     };
 
     /**
      * Success callback for listing checkpoints.
      * 
      * @method list_checkpoint_success
      * @param {Object} data JSON representation of a checkpoint
      */
     Notebook.prototype.list_checkpoints_success = function (data) {
         this.checkpoints = data;
         if (data.length) {
             this.last_checkpoint = data[data.length - 1];
         } else {
             this.last_checkpoint = null;
         }
         this.events.trigger('checkpoints_listed.Notebook', [data]);
     };
 
     /**
      * Create a checkpoint of this notebook on the server from the most recent save.
      * 
      * @method create_checkpoint
      */
     Notebook.prototype.create_checkpoint = function () {
         var that = this;
         this.contents.create_checkpoint(this.notebook_path).then(
             $.proxy(this.create_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_failed.Notebook', error);
             }
         );
     };
 
     /**
      * Success callback for creating a checkpoint.
      * 
      * @method create_checkpoint_success
      * @param {Object} data JSON representation of a checkpoint
      */
     Notebook.prototype.create_checkpoint_success = function (data) {
         this.add_checkpoint(data);
         this.events.trigger('checkpoint_created.Notebook', data);
     };
 
     Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) {
         var that = this;
         checkpoint = checkpoint || this.last_checkpoint;
         if ( ! checkpoint ) {
             console.log("restore dialog, but no checkpoint to restore to!");
             return;
         }
         var body = $('<div/>').append(
             $('<p/>').addClass("p-space").text(
                 "Are you sure you want to revert the notebook to " +
                 "the latest checkpoint?"
             ).append(
                 $("<strong/>").text(
                     " This cannot be undone."
                 )
             )
         ).append(
             $('<p/>').addClass("p-space").text("The checkpoint was last updated at:")
         ).append(
             $('<p/>').addClass("p-space").text(
                 Date(checkpoint.last_modified)
             ).css("text-align", "center")
         );
         
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Revert notebook to checkpoint",
             body : body,
             buttons : {
                 Revert : {
                     class : "btn-danger",
                     click : function () {
                         that.restore_checkpoint(checkpoint.id);
                     }
                 },
                 Cancel : {}
                 }
         });
     };
     
     /**
      * Restore the notebook to a checkpoint state.
      * 
      * @method restore_checkpoint
      * @param {String} checkpoint ID
      */
     Notebook.prototype.restore_checkpoint = function (checkpoint) {
         this.events.trigger('notebook_restoring.Notebook', checkpoint);
         var that = this;
         this.contents.restore_checkpoint(this.notebook_path, checkpoint).then(
             $.proxy(this.restore_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_restore_failed.Notebook', error);
             }
         );
     };
     
     /**
      * Success callback for restoring a notebook to a checkpoint.
      * 
      * @method restore_checkpoint_success
      */
     Notebook.prototype.restore_checkpoint_success = function () {
         this.events.trigger('checkpoint_restored.Notebook');
         this.load_notebook(this.notebook_path);
     };
 
     /**
      * Delete a notebook checkpoint.
      * 
      * @method delete_checkpoint
      * @param {String} checkpoint ID
      */
     Notebook.prototype.delete_checkpoint = function (checkpoint) {
         this.events.trigger('notebook_restoring.Notebook', checkpoint);
         var that = this;
         this.contents.delete_checkpoint(this.notebook_path, checkpoint).then(
             $.proxy(this.delete_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_delete_failed.Notebook', error);
             }
         );
     };
     
     /**
      * Success callback for deleting a notebook checkpoint
      * 
      * @method delete_checkpoint_success
      */
     Notebook.prototype.delete_checkpoint_success = function () {
         this.events.trigger('checkpoint_deleted.Notebook');
         this.load_notebook(this.notebook_path);
     };
 
 
     // For backwards compatability.
     IPython.Notebook = Notebook;
 
     return {'Notebook': Notebook};
 });

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

@@ -1,256 +1,367 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "underscore",
     "backbone",
     "jquery",
     "base/js/utils",
     "base/js/namespace",
-], function (_, Backbone, $, utils, IPython) {
+    "services/kernels/comm"
+], function (_, Backbone, $, utils, IPython, comm) {
     "use strict";
     //--------------------------------------------------------------------
     // WidgetManager class
     //--------------------------------------------------------------------
     var WidgetManager = function (comm_manager, notebook) {
         /**
          * Public constructor
          */
         WidgetManager._managers.push(this);
 
         // Attach a comm manager to the 
         this.keyboard_manager = notebook.keyboard_manager;
         this.notebook = notebook;
         this.comm_manager = comm_manager;
+        this.comm_target_name = 'ipython.widget';
         this._models = {}; /* Dictionary of model ids and model instances */
 
         // 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));
     };
 
     //--------------------------------------------------------------------
     // Class level
     //--------------------------------------------------------------------
     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.register_widget_model = function (model_name, model_type) {
         // 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.
         WidgetManager._view_types[view_name] = view_type;
     };
 
     //--------------------------------------------------------------------
     // Instance level
     //--------------------------------------------------------------------
     WidgetManager.prototype.display_view = function(msg, model) {
         /**
          * Displays a view for a particular model.
          */
         var that = this;
-        var cell = this.get_msg_cell(msg.parent_header.msg_id);
+        return new Promise(function(resolve, reject) {
+            var cell = that.get_msg_cell(msg.parent_header.msg_id);
         if (cell === null) {
-            return Promise.reject(new Error("Could not determine where the display" +
+                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) {
+            } else {
+                return that.display_view_in_cell(cell, model);
+            }
+        });
+    };
+
+    WidgetManager.prototype.display_view_in_cell = function(cell, model) {
+        // Displays a view in a cell.
+        return new Promise(function(resolve, reject) {
+            if (cell.display_widget_view) {
+                cell.display_widget_view(that.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));
+                    resolve(view);
+                }, function(error) { 
+                    reject(new utils.WrappedError('Could not display view', error)); 
+                });
+            } else {
+                reject(new Error('Cell does not have a `display_widget_view` method.'));
         }
+        });
     };
 
     WidgetManager.prototype._handle_display_view = function (view) {
         /**
          * Have the IPython keyboard manager disable its event
          * handling so the widget can capture keyboard input.
          * Note, this is only done on the outer most widgets.
          */
         if (this.keyboard_manager) {
             this.keyboard_manager.register_events(view.$el);
         
             if (view.additional_elements) {
                 for (var i = 0; i < view.additional_elements.length; i++) {
                     this.keyboard_manager.register_events(view.additional_elements[i]);
                 }
             } 
         }
     };
     
     WidgetManager.prototype.create_view = function(model, options) {
         /**
          * Creates a promise for a view of a given model
          *
          * Make sure the view creation is not out of order with 
          * any state updates.
          */
         model.state_change = model.state_change.then(function() {
             
             return utils.load_class(model.get('_view_name'), model.get('_view_module'),
             WidgetManager._view_types).then(function(ViewType) {
 
                 // If a view is passed into the method, use that view's cell as
                 // the cell for the view that is created.
                 options = options || {};
                 if (options.parent !== undefined) {
                     options.cell = options.parent.options.cell;
                 }
                 // Create and render the view...
                 var parameters = {model: model, options: options};
                 var view = new ViewType(parameters);
                 view.listenTo(model, 'destroy', view.remove);
                 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;
         return model.state_change;
     };
 
     WidgetManager.prototype.get_msg_cell = function (msg_id) {
         var cell = null;
         // First, check to see if the msg was triggered by cell execution.
         if (this.notebook) {
             cell = this.notebook.get_msg_cell(msg_id);
         }
         if (cell !== null) {
             return cell;
         }
         // Second, check to see if a get_cell callback was defined
         // for the message.  get_cell callbacks are registered for
         // widget messages, so this block is actually checking to see if the
         // message was triggered by a widget.
         var kernel = this.comm_manager.kernel;
         if (kernel) {
             var callbacks = kernel.get_callbacks_for_msg(msg_id);
             if (callbacks && callbacks.iopub &&
                 callbacks.iopub.get_cell !== undefined) {
                 return callbacks.iopub.get_cell();
             }
         }
         
         // Not triggered by a cell or widget (no get_cell callback 
         // exists).
         return null;
     };
 
     WidgetManager.prototype.callbacks = function (view) {
         /**
          * callback handlers specific a view
          */
         var callbacks = {};
         if (view && view.options.cell) {
 
             // Try to get output handlers
             var cell = view.options.cell;
             var handle_output = null;
             var handle_clear_output = null;
             if (cell.output_area) {
                 handle_output = $.proxy(cell.output_area.handle_output, cell.output_area);
                 handle_clear_output = $.proxy(cell.output_area.handle_clear_output, cell.output_area);
             }
 
             // Create callback dictionary using what is known
             var that = this;
             callbacks = {
                 iopub : {
                     output : handle_output,
                     clear_output : handle_clear_output,
 
                     // Special function only registered by widget messages.
                     // Allows us to get the cell for a message so we know
                     // where to add widgets if the code requires it.
                     get_cell : function () {
                         return cell;
                     },
                 },
             };
         }
         return callbacks;
     };
 
     WidgetManager.prototype.get_model = function (model_id) {
         /**
          * Get a promise for a model by model id.
          */
         return this._models[model_id];
     };
 
     WidgetManager.prototype._handle_comm_open = function (comm, msg) {
         /**
          * Handle when a comm is opened.
          */
         return this.create_model({
             model_name: msg.content.data.model_name, 
             model_module: msg.content.data.model_module, 
             comm: comm}).catch(utils.reject("Couldn't create a model.", true));
     };
 
     WidgetManager.prototype.create_model = function (options) {
         /**
          * Create and return a promise for a new widget model
          *
          * Minimally, one must provide the model_name and widget_class
          * parameters to create a model from Javascript.
          *
          * Example
          * --------
          * JS:
          * IPython.notebook.kernel.widget_manager.create_model({
          *      model_name: 'WidgetModel', 
          *      widget_class: 'IPython.html.widgets.widget_int.IntSlider'})
          *      .then(function(model) { console.log('Create success!', model); },
          *      $.proxy(console.error, console));
          *
          * Parameters
          * ----------
          * options: dictionary
          *  Dictionary of options with the following contents:
          *      model_name: string
          *          Target name of the widget model to create.
          *      model_module: (optional) string
          *          Module name of the widget model to create.
          *      widget_class: (optional) string
          *          Target name of the widget in the back-end.
          *      comm: (optional) Comm
          *
          * Create a comm if it wasn't provided.
          */
         var comm = options.comm;
         if (!comm) {
             comm = this.comm_manager.new_comm('ipython.widget', {'widget_class': options.widget_class});
         }
 
         var that = this;
         var model_id = comm.comm_id;
         var model_promise =  utils.load_class(options.model_name, options.model_module, WidgetManager._model_types)
             .then(function(ModelType) {
                 var widget_model = new ModelType(that, model_id, comm);
                 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) {
                 delete that._models[model_id];
                 var wrapped_error = new utils.WrappedError("Couldn't create model", error);
                 return Promise.reject(wrapped_error);
             });
         this._models[model_id] = model_promise;
         return model_promise;
     };
 
+    WidgetManager.prototype.get_state = function(options) {
+        // 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_alive: (optional) boolean=false
+        //          Include models that have comms with severed connections.
+        return utils.resolve_promise_dict(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 alive_flag = (options && options.not_alive) || model.comm_alive;
+                    if (displayed_flag && alive_flag) {
+                        state[model.model_id] = {
+                            model_name: model.name,
+                            model_module: model.module,
+                            views: [],
+                        };
+
+                        // Get the views that are displayed *now*.
+                        for (var id in model.views) {
+                            if (model.views.hasOwnProperty(id)) {
+                                var view = model.views[id];
+                                var cell_index = this.notebook.find_cell_index(view.options.cell);
+                                state[model.model_id].views.push(cell_index);
+                            }
+                        }
+                    }
+                }
+            }
+            return state;
+        });
+    };
+    
+    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 (new Promise(function(resolve, reject) {
+            if (that.kernel) {
+                resolve(that.kernel);
+            } else {
+                that.events.on('kernel_created.Session', function(event, data) {
+                    resolve(data.kernel);
+                });
+            }    
+        })).then(function(kernel) {
+            
+            // Recreate all the widget models for the given state.
+            that.widget_models = [];
+            for (var i = 0; i < state.length; 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, state[i].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_alive
+                // false.  Once we receive the first state push from the back-end
+                // we know the comm is alive.
+                var model = kernel.widget_manager.create_model({
+                    comm: new_comm, 
+                    model_name: state[i].model_name, 
+                    model_module: state[i].model_module}).then(function(model) {
+                        model.set_comm_alive(false);
+                        model.request_state();
+                        model.received_state.then(function() {
+                            model.set_comm_alive(true);
+                        });
+                        return model;
+                    });
+                that.widget_models.push(model);
+            }
+            return Promise.all(that.widget_models);
+
+        });
+        
+    };
+
     // Backwards compatibility.
     IPython.WidgetManager = WidgetManager;
 
     return {'WidgetManager': WidgetManager};
 });

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

@@ -1,682 +1,747 b''
 // 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){
 
     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 = {};
 
+            // Promise that is resolved when a state is received
+            // from the back-end.
+            var that = this;
+            this.received_state = new Promise(function(resolve) {
+                that._resolve_received_state = resolve;
+            });
+
             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_alive(true);
+            } else {
+                this.set_comm_alive(false);
             }
             return Backbone.Model.apply(this);
         },
 
         send: function (content, callbacks) {
             /**
              * Send a custom msg over the comm.
              */
             if (this.comm !== undefined) {
                 var data = {method: 'custom', content: content};
                 this.comm.send(data, callbacks);
                 this.pending_msgs++;
             }
         },
 
-        _handle_comm_closed: function (msg) {
+        request_state: function(callbacks) {
             /**
-             * Handle when a widget is closed.
+             * Request a state push from the back-end.
              */
-            this.trigger('comm:close');
+            if (!this.comm) {
+                console.error("Could not request_state because comm doesn't exist!");
+                return;
+            }
+            this.comm.send({method: 'request_state'}, callbacks || this.widget_manager.callbacks());
+        },
+
+        set_comm_alive: function(alive) {
+            /** 
+             * Change the comm_alive state of the model.
+             */
+            if (this.comm_alive === undefined || this.comm_alive != alive) {
+                this.comm_alive = alive;
+                this.trigger(alive ? 'comm_is_live' : 'comm_is_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() {
                         return that.set_state(msg.content.data.state);
                     }).catch(utils.reject("Couldn't process update msg for model id '" + String(that.id) + "'", true));
                     break;
                 case 'custom':
                     this.trigger('msg:custom', msg.content.data.content);
                     break;
                 case 'display':
                     this.widget_manager.display_view(msg, this);
                     break;
             }
         },
 
         set_state: function (state) {
             var that = this;
             // Handle when a widget is updated via the python side.
             return this._unpack_models(state).then(function(state) {
                 that.state_lock = state;
                 try {
                     WidgetModel.__super__.set.call(that, state);
                 } finally {
                     that.state_lock = null;
                 }
-            }).catch(utils.reject("Couldn't set model state", true));
+                that._resolve_received_state();
+                return Promise.resolve();
+            }, 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.
              *
              * 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.
              */
             var error = options.error || function() {
                 console.error('Backbone sync error:', arguments);
             };
             if (this.comm === undefined) {
                 error();
                 return false;
             }
 
             // Delete any key value pairs that the back-end already knows about.
             var attrs = (method === 'patch') ? options.attrs : model.toJSON(options);
             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];
                     }
                 }
             }
 
             // Only sync if there are attributes to send to the back-end.
             attrs = this._pack_models(attrs);
             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.
                     var data = {method: 'backbone', sync_data: attrs};
                     this.comm.send(data, 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 = {};
         },
 
         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});
         },
 
         _pack_models: function(value) {
             /**
              * Replace models with model ids recursively.
              */
             var that = this;
             var packed;
             if (value instanceof Backbone.Model) {
                 return "IPY_MODEL_" + value.id;
 
             } else if ($.isArray(value)) {
                 packed = [];
                 _.each(value, function(sub_value, key) {
                     packed.push(that._pack_models(sub_value));
                 });
                 return packed;
             } else if (value instanceof Date || value instanceof String) {
                 return value;
             } else if (value instanceof Object) {
                 packed = {};
                 _.each(value, function(sub_value, key) {
                     packed[key] = that._pack_models(sub_value);
                 });
                 return packed;
 
             } else {
                 return value;
             }
         },
 
         _unpack_models: function(value) {
             /**
              * Replace model ids with models recursively.
              */
             var that = this;
             var unpacked;
             if ($.isArray(value)) {
                 unpacked = [];
                 _.each(value, function(sub_value, key) {
                     unpacked.push(that._unpack_models(sub_value));
                 });
                 return Promise.all(unpacked);
             } else if (value instanceof Object) {
                 unpacked = {};
                 _.each(value, function(sub_value, key) {
                     unpacked[key] = that._unpack_models(sub_value);
                 });
                 return utils.resolve_promises_dict(unpacked);
             } else if (typeof value === 'string' && value.slice(0,10) === "IPY_MODEL_") {
                 // get_model returns a promise already
                 return this.widget_manager.get_model(value.slice(10, value.length));
             } else {
                 return Promise.resolve(value);
             }
         },
 
         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);
 
        },
     });
     widgetmanager.WidgetManager.register_widget_model('WidgetModel', WidgetModel);
 
 
     var WidgetView = Backbone.View.extend({
         initialize: function(parameters) {
             /**
              * Public constructor.
              */
             this.model.on('change',this.update,this);
             this.options = parameters.options;
             this.on('displayed', function() { 
                 this.is_displayed = true; 
             }, this);
+            this.on('remove', function() {
+                delete this.model.views[this.id];
+            }, 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
              */
         },
 
         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.
              */
             this.model.send(content, this.callbacks());
         },
 
         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.on('displayed', this.show, this);
             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.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.model.get('margin'));
                 this.update_attr('border-radius', 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 (/^\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
              */
             this.$el.toggle(value);
          },
 
         update_css: function (model, css) {
             /**
              * Update the css styling of this view.
              */
             var e = this.$el;
             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.state_change = Promise.resolve();
             this._handler_context = context || this;
             this._models = [];
             this.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.
              * returns a promise that resolves after this update is done
              */
             var remove = remove_view || this._remove_view;
             var create = create_view || this._create_view;
             if (create === undefined || remove === undefined){
                 console.error("Must define a create a remove function");
             }
             var context = context || this._handler_context;
             var added_views = [];
             var that = this;
             this.state_change = this.state_change.then(function() {
                 var i;
                  // first, skip past the beginning of the lists if they are identical
                 for (i = 0; i < new_models.length; i++) {
                     if (i >= that._models.length || new_models[i] !== that._models[i]) {
                         break;
                     }
                 }
                 var first_removed = i;
                 // Remove the non-matching items from the old list.
                 for (var j = first_removed; j < that._models.length; j++) {
                     remove.call(context, that.views[j]);
                 }
 
                 // Add the rest of the new list items.
                 for (; i < new_models.length; i++) {
                     added_views.push(create.call(context, new_models[i]));
                 }
                 // make a copy of the input array
                 that._models = new_models.slice();
                 return Promise.all(added_views).then(function(added) {
                     Array.prototype.splice.apply(that.views, [first_removed, that.views.length].concat(added));
                     return that.views;
                 });
             });
             return this.state_change;
         },
 
         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;
             this.state_change = this.state_change.then(function() {
                 for (var i = 0; i < that.views.length; i++) {
                     that._remove_view.call(that._handler_context, that.views[i]);
                 }
                 that._models = [];
                 that.views = [];
             });
             return this.state_change;
         },
     });
 
     var widget = {
         'WidgetModel': WidgetModel,
         'WidgetView': WidgetView,
         'DOMWidgetView': DOMWidgetView,
         'ViewList': ViewList,
     };
 
     // For backwards compatability.
     $.extend(IPython, widget);
 
     return widget;
 });

IPython/html/widgets/widget.py

@@ -1,481 +1,488 b''
 """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
 
 #-----------------------------------------------------------------------------
 # 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
 
 
 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(allow_none=False)
     _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.
         """
         self._send({
             "method" : "update",
             "state"  : self.get_state(key=key)
         })
 
     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.
         """
         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 = {}
         for k in keys:
             f = self.trait_metadata(k, 'to_json', self._trait_to_json)
             value = getattr(self, k)
             state[k] = f(value)
         return state
 
     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):
         """Sends a custom msg to the widget model in the front-end.
 
         Parameters
         ----------
         content : dict
             Content of the message to send.
         """
         self._send({"method": "custom", "content": content})
 
     def on_msg(self, callback, remove=False):
         """(Un)Register a custom msg receive callback.
 
         Parameters
         ----------
         callback: callable
             callback will be passed two arguments when a message arrives::
             
                 callback(widget, content)
             
         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']
-        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:
+        if method == 'backbone':
+            if 'sync_data' in data:
             sync_data = data['sync_data']
             self.set_state(sync_data) # handles all methods
 
-        # Handle a custom msg from the front-end
+        # 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'])
 
+        # 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)
 
     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
 
         Traverse lists/tuples and dicts and serialize their values as well.
         Replace any widgets with their model_id
         """
         if isinstance(x, dict):
             return {k: self._trait_to_json(v) for k, v in x.items()}
         elif isinstance(x, (list, tuple)):
             return [self._trait_to_json(v) for v in x]
         elif isinstance(x, Widget):
             return "IPY_MODEL_" + x.model_id
         else:
             return x # Value must be JSON-able
 
     def _trait_from_json(self, x):
         """Convert json values to objects
 
         Replace any strings representing valid model id values to Widget references.
         """
         if isinstance(x, dict):
             return {k: self._trait_from_json(v) for k, v in x.items()}
         elif isinstance(x, (list, tuple)):
             return [self._trait_from_json(v) for v in x]
         elif isinstance(x, string_types) and x.startswith('IPY_MODEL_') and x[10:] in Widget.widgets:
             # we want to support having child widgets at any level in a hierarchy
             # trusting that a widget UUID will not appear out in the wild
             return Widget.widgets[x[10:]]
         else:
             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):
         """Sends a message to the model in the front-end."""
         self.comm.send(msg)
 
 
 class DOMWidget(Widget):
     visible = Bool(True, help="Whether the widget is visible.", 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)
     padding = CUnicode(sync=True)
     margin = CUnicode(sync=True)
 
     color = Unicode(sync=True)
     background_color = Unicode(sync=True)
     border_color = Unicode(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', ''] + [str(100 * (i+1)) for i in range(9)], 
         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'])