Clarified API for the create_model function,

Also added a test!

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

@@ -187,29 +187,22 @@ define([
 
     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, comm: comm});
+        return this.create_model({model_name: msg.content.data.model_name, comm: comm});
     };
 
-    WidgetManager.prototype.create_model = function (model_name, target_name, init_state_callback) {
+    WidgetManager.prototype.create_model = function (options) {
         // Create and return a new widget model.
         //
-        // Parameters
-        // ----------
-        // model_name: string
-        //      Target name of the widget model to create.
-        // target_name: string
-        //      Target name of the widget in the back-end.
-        // init_state_callback: (optional) callback
-        //      Called when the first state push from the back-end is 
-        //      recieved.
-        return this._create_model({
-            model_name: model_name, 
-            target_name: target_name,
-            init_state_callback: init_state_callback});
-    };
-
-    WidgetManager.prototype._create_model = function (options) {
-        // Create and return a new widget model.
+        // Minimally, one must provide the model_name and target_name
+        // parameters to create a model from Javascript.
+        //
+        // Example
+        // --------
+        // JS:
+        // window.slider = IPython.notebook.kernel.widget_manager.create_model({
+        //      model_name: 'WidgetModel', 
+        //      target_name: 'IPython.html.widgets.widget_int.IntSlider',
+        //      init_state_callback: function(model) { console.log('Create success!', model); }});
         //
         // Parameters
         // ----------
@@ -222,7 +215,8 @@ define([
         //      comm: (optional) Comm
         //      init_state_callback: (optional) callback
         //          Called when the first state push from the back-end is 
-        //          recieved.
+        //          recieved.  Allows you to modify the model after it's
+        //          complete state is filled and synced.
 
         // Create a comm if it wasn't provided.
         var comm = options.comm;

IPython/html/tests/widgets/manager.js

@@ -0,0 +1,36 @@
+// Test the widget manager.
+casper.notebook_test(function () {
+    var index;
+    var slider = {};
+    
+    this.then(function () {
+    
+        // Check if the WidgetManager class is defined.
+        this.test.assert(this.evaluate(function() {
+            return IPython.WidgetManager !== undefined; 
+        }), 'WidgetManager class is defined');
+
+        // Check if the widget manager has been instantiated.
+        this.test.assert(this.evaluate(function() {
+            return IPython.notebook.kernel.widget_manager !== undefined; 
+        }), 'Notebook widget manager instantiated');
+
+        // Try creating a widget from Javascript.
+        slider.id = this.evaluate(function() {
+            var slider = IPython.notebook.kernel.widget_manager.create_model({
+                 model_name: 'WidgetModel', 
+                 target_name: 'IPython.html.widgets.widget_int.IntSlider',
+                 init_state_callback: function(model) { console.log('Create success!', model); }});
+            return slider.id;
+        });
+    });
+
+    index = this.append_cell(
+        'from IPython.html.widgets import Widget\n' + 
+        'widget = Widget.widgets.values()[0]\n' +
+        'print(widget.model_id)');
+    this.execute_cell_then(index, function(index) {
+        var output = this.get_output_cell(index).text.trim();
+        this.test.assertEquals(output, slider.id, "Widget created from the front-end.");
+    });
+});

IPython/html/tests/widgets/widget.js

@@ -38,14 +38,6 @@ var recursive_compare = function(a, b) {
 // Test the widget framework.
 casper.notebook_test(function () {
     var index;
-    
-    this.then(function () {
-    
-        // Check if the WidgetManager class is defined.
-        this.test.assert(this.evaluate(function() {
-            return IPython.WidgetManager !== undefined; 
-        }), 'WidgetManager class is defined');
-    });
 
     index = this.append_cell(
         'from IPython.html import widgets\n' + 
@@ -54,10 +46,6 @@ casper.notebook_test(function () {
     this.execute_cell_then(index);
 
     this.then(function () {
-        // Check if the widget manager has been instantiated.
-        this.test.assert(this.evaluate(function() {
-            return IPython.notebook.kernel.widget_manager !== undefined; 
-        }), 'Notebook widget manager instantiated');
 
         // Functions that can be used to test the packing and unpacking APIs
         var that = this;