Merge pull request #5652 from jhamrick/placeholder

Add placeholder attribute to text widgets

docs/source/whatsnew/pr/textwidget-placeholder.rst

@@ -0,0 +1,3 b''
+* `TextWidget` and `TextareaWidget` objects now include a
+  `placeholder` attribute, for displaying placeholder text before the
+  user has typed anything.

IPython/html/static/widgets/js/widget_string.js

@@ -71,6 +71,11 b' define(["widgets/js/widget"], function(WidgetManager){'
             this.update(); // Set defaults.
 
             this.model.on('msg:custom', $.proxy(this._handle_textarea_msg, this));
+            this.model.on('change:placeholder', function(model, value, options) {
+                this.update_placeholder(value);
+            }, this);
+
+            this.update_placeholder();
         },
 
         _handle_textarea_msg: function (content){
@@ -80,6 +85,13 b' define(["widgets/js/widget"], function(WidgetManager){'
             }
         },
 
+        update_placeholder: function(value) {
+            if (!value) {
+                value = this.model.get('placeholder');
+            }
+            this.$textbox.attr('placeholder', value);
+        },
+
         scroll_to_bottom: function (){
             // Scroll the text-area view to the bottom.
             this.$textbox.scrollTop(this.$textbox[0].scrollHeight);
@@ -141,6 +153,18 b' define(["widgets/js/widget"], function(WidgetManager){'
                 .appendTo(this.$el);
             this.$el_to_style = this.$textbox; // Set default element to style
             this.update(); // Set defaults.
+            this.model.on('change:placeholder', function(model, value, options) {
+                this.update_placeholder(value);
+            }, this);
+
+            this.update_placeholder();
+        },
+
+        update_placeholder: function(value) {
+            if (!value) {
+                value = this.model.get('placeholder');
+            }
+            this.$textbox.attr('placeholder', value);
         },
         
         update: function(options){

IPython/html/tests/widgets/widget_string.js

@@ -7,8 +7,8 b' casper.notebook_test(function () {'
     this.execute_cell_then(index);
 
     var string_index = this.append_cell(
-        'string_widget = [widgets.TextWidget(value = "xyz"),\n' +
-        '    widgets.TextareaWidget(value = "xyz"),\n' +
+        'string_widget = [widgets.TextWidget(value = "xyz", placeholder = "abc"),\n' +
+        '    widgets.TextareaWidget(value = "xyz", placeholder = "def"),\n' +
         '    widgets.HTMLWidget(value = "xyz"),\n' +
         '    widgets.LatexWidget(value = "$\\\\LaTeX{}$")]\n' +
         '[display(widget) for widget in string_widget]\n'+
@@ -41,5 +41,13 b' casper.notebook_test(function () {'
         this.test.assert(this.cell_element_exists(string_index, 
             '.widget-area .widget-subarea div span.MathJax_Preview'),
             'MathJax parsed the LaTeX successfully.');
+
+        this.test.assert(this.cell_element_function(index, 
+            '.widget-area .widget-subarea .widget-hbox textarea', 'attr', ['placeholder'])=='def',
+            'Python set textarea placeholder.');
+
+        this.test.assert(this.cell_element_function(index, 
+            '.widget-area .widget-subarea .widget-hbox-single input[type=text]', 'attr', ['placeholder'])=='abc',
+            'Python set textbox placehoder.');
     });
-});
  No newline at end of file
+});

IPython/html/widgets/widget_string.py

@@ -23,6 +23,7 b' class _StringWidget(DOMWidget):'
     value = Unicode(help="String value", sync=True)
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
+    placeholder = Unicode("", help="Placeholder text to display when nothing has been typed", sync=True)
 
 
 class HTMLWidget(_StringWidget):

examples/Interactive Widgets/Widget Basics.ipynb

@@ -7,7 +7,7 b''
    ]
   ],
   "name": "",
-  "signature": "sha256:9a70b52f0b16861d1cd6a8342b233247958977a52bde8d3efd69d21131ce1926"
+  "signature": "sha256:5ac3a85c8bb2f9bb3cd63b524bbb626ab1531176b43a109d13f5d7794f805eee"
  },
  "nbformat": 3,
  "nbformat_minor": 0,
@@ -31,7 +31,7 b''
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 1
+     "prompt_number": 2
     },
     {
      "cell_type": "heading",
@@ -298,6 +298,39 b''
       }
      ],
      "prompt_number": 10
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "Some widgets have special attributes. For example, text boxes and text areas can specify the `placeholder` attribute, which will set \"placeholder\" text to be displayed before the user has typed anything:"
+     ]
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "mytextwidget = widgets.TextWidget()\n",
+      "mytextwidget.placeholder = \"type something here\"\n",
+      "display(mytextwidget)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 4
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [
+      "mytextareawidget = widgets.TextareaWidget()\n",
+      "mytextareawidget.placeholder = \"your text here\"\n",
+      "display(mytextareawidget)"
+     ],
+     "language": "python",
+     "metadata": {},
+     "outputs": [],
+     "prompt_number": 5
     }
    ],
    "metadata": {}