Merge pull request #5652 from jhamrick/placeholder

Add placeholder attribute to text widgets

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

@@ -0,0 +1,3
+* `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

@@ -1,222 +1,246
 //----------------------------------------------------------------------------
 //  Copyright (C) 2013 The IPython Development Team
 //
 //  Distributed under the terms of the BSD License.  The full license is in
 //  the file COPYING, distributed as part of this software.
 //----------------------------------------------------------------------------
 
 //============================================================================
 // StringWidget
 //============================================================================
 
 /**
  * @module IPython
  * @namespace IPython
  **/
 
 define(["widgets/js/widget"], function(WidgetManager){
 
     var HTMLView = IPython.DOMWidgetView.extend({  
         render : function(){
             // Called when view is rendered.
             this.update(); // Set defaults.
         },
         
         update : function(){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             this.$el.html(this.model.get('value')); // CAUTION! .html(...) CALL MANDITORY!!!
             return HTMLView.__super__.update.apply(this);
         },
     });
     WidgetManager.register_widget_view('HTMLView', HTMLView);
 
 
     var LatexView = IPython.DOMWidgetView.extend({  
         render : function(){
             // Called when view is rendered.
             this.update(); // Set defaults.
         },
         
         update : function(){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             this.$el.text(this.model.get('value'));
             MathJax.Hub.Queue(["Typeset",MathJax.Hub,this.$el.get(0)]);
 
             return LatexView.__super__.update.apply(this);
         }, 
     });
     WidgetManager.register_widget_view('LatexView', LatexView);
 
 
     var TextareaView = IPython.DOMWidgetView.extend({  
         render: function(){
             // Called when view is rendered.
             this.$el
                 .addClass('widget-hbox');
             this.$label = $('<div />')
                 .appendTo(this.$el)
                 .addClass('widget-hlabel')
                 .hide();
             this.$textbox = $('<textarea />')
                 .attr('rows', 5)
                 .addClass('widget-text')
                 .appendTo(this.$el);
             this.$el_to_style = this.$textbox; // Set default element to style
             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){
             // Handle when a custom msg is recieved from the back-end.
             if (content.method == "scroll_to_bottom") {
                 this.scroll_to_bottom();                
             }
         },
 
+        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);
         },
 
         update: function(options){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             if (options === undefined || options.updated_view != this) {
                 this.$textbox.val(this.model.get('value'));
 
                 var disabled = this.model.get('disabled');
                 this.$textbox.prop('disabled', disabled);
 
                 var description = this.model.get('description');
                 if (description.length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     this.$label.show();
                 }
             }
             return TextareaView.__super__.update.apply(this);
         },
         
         events: {
             // Dictionary of events and their handlers.
             "keyup textarea" : "handleChanging",
             "paste textarea" : "handleChanging",
             "cut textarea"   : "handleChanging"
         },
         
         handleChanging: function(e) { 
             // Handles and validates user input.
             
             // Calling model.set will trigger all of the other views of the 
             // model to update.
             this.model.set('value', e.target.value, {updated_view: this});
             this.touch();
         },
     });
     WidgetManager.register_widget_view('TextareaView', TextareaView);
 
 
     var TextView = IPython.DOMWidgetView.extend({  
         render: function(){
             // Called when view is rendered.
             this.$el
                 .addClass('widget-hbox-single');
             this.$label = $('<div />')
                 .addClass('widget-hlabel')
                 .appendTo(this.$el)
                 .hide();
             this.$textbox = $('<input type="text" />')
                 .addClass('input')
                 .addClass('widget-text')
                 .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){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             if (options === undefined || options.updated_view != this) {
                 if (this.$textbox.val() != this.model.get('value')) {
                     this.$textbox.val(this.model.get('value'));
                 }
 
                 var disabled = this.model.get('disabled');
                 this.$textbox.prop('disabled', disabled);
 
                 var description = this.model.get('description');
                 if (description.length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     this.$label.show();
                 }
             }
             return TextView.__super__.update.apply(this);
         },
         
         events: {
             // Dictionary of events and their handlers.
             "keyup input"    : "handleChanging",
             "paste input"    : "handleChanging",
             "cut input"      : "handleChanging",
             "keypress input" : "handleKeypress",
             "blur input" : "handleBlur",
             "focusout input" : "handleFocusOut"
         },
         
         handleChanging: function(e) { 
             // Handles user input.
 
             // Calling model.set will trigger all of the other views of the 
             // model to update.
             this.model.set('value', e.target.value, {updated_view: this});
             this.touch();
         },
         
         handleKeypress: function(e) { 
             // Handles text submition
             if (e.keyCode == 13) { // Return key
                 this.send({event: 'submit'});
                 event.stopPropagation();
                 event.preventDefault();
                 return false;
             }
         },
 
         handleBlur: function(e) { 
             // Prevent a blur from firing if the blur was not user intended.
             // This is a workaround for the return-key focus loss bug.
             // TODO: Is the original bug actually a fault of the keyboard
             // manager?
             if (e.relatedTarget === null) {
                 event.stopPropagation();
                 event.preventDefault();
                 return false;
             }
         },
 
         handleFocusOut: function(e) { 
             // Prevent a blur from firing if the blur was not user intended.
             // This is a workaround for the return-key focus loss bug.
             if (e.relatedTarget === null) {
                 event.stopPropagation();
                 event.preventDefault();
                 return false;
             }
         },
     });
     WidgetManager.register_widget_view('TextView', TextView);
 });

IPython/html/tests/widgets/widget_string.js

@@ -1,45 +1,53
 // Test widget string class
 casper.notebook_test(function () {
     index = this.append_cell(
         'from IPython.html import widgets\n' + 
         'from IPython.display import display, clear_output\n' +
         'print("Success")');
     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'+
         'print("Success")');
     this.execute_cell_then(string_index, function(index){
 
         this.test.assertEquals(this.get_output_cell(index).text, 'Success\n', 
             'Create string widget cell executed with correct output.');
 
         this.test.assert(this.cell_element_exists(index, 
             '.widget-area .widget-subarea'),
             'Widget subarea exists.');
 
         this.test.assert(this.cell_element_exists(index, 
             '.widget-area .widget-subarea .widget-hbox-single input[type=text]'),
             'Textbox exists.');
 
         this.test.assert(this.cell_element_exists(index, 
             '.widget-area .widget-subarea .widget-hbox textarea'),
             'Textarea exists.');
 
         this.test.assert(this.cell_element_function(index, 
             '.widget-area .widget-subarea .widget-hbox textarea', 'val')=='xyz',
             'Python set textarea value.');
 
         this.test.assert(this.cell_element_function(index, 
             '.widget-area .widget-subarea .widget-hbox-single input[type=text]', 'val')=='xyz',
             'Python set textbox value.');
 
         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

@@ -1,72 +1,73
 """StringWidget class.  
 
 Represents a unicode string using a widget.
 """
 #-----------------------------------------------------------------------------
 # 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 .widget import DOMWidget, CallbackDispatcher
 from IPython.utils.traitlets import Unicode, Bool
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 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):
     _view_name = Unicode('HTMLView', sync=True)
 
 
 class LatexWidget(_StringWidget):
     _view_name = Unicode('LatexView', sync=True)
 
 
 class TextareaWidget(_StringWidget):
     _view_name = Unicode('TextareaView', sync=True)
 
     def scroll_to_bottom(self):
         self.send({"method": "scroll_to_bottom"})
 
 
 class TextWidget(_StringWidget):
     _view_name = Unicode('TextView', sync=True)
 
     def __init__(self, **kwargs):
         super(TextWidget, self).__init__(**kwargs)
         self._submission_callbacks = CallbackDispatcher()
         self.on_msg(self._handle_string_msg)
 
     def _handle_string_msg(self, _, content):
         """Handle a msg from the front-end.
 
         Parameters
         ----------
         content: dict
             Content of the msg."""
         if content.get('event', '') == 'submit':
             self._submission_callbacks(self)
 
     def on_submit(self, callback, remove=False):
         """(Un)Register a callback to handle text submission.
 
         Triggered when the user clicks enter.
 
         Parameters
         ----------
         callback: callable
             Will be called with exactly one argument: the Widget instance
         remove: bool (optional)
             Whether to unregister the callback"""
         self._submission_callbacks.register_callback(callback, remove=remove)

examples/Interactive Widgets/Widget Basics.ipynb

@@ -1,306 +1,339
 {
  "metadata": {
   "cell_tags": [
    [
     "<None>",
     null
    ]
   ],
   "name": "",
-  "signature": "sha256:9a70b52f0b16861d1cd6a8342b233247958977a52bde8d3efd69d21131ce1926"
+  "signature": "sha256:5ac3a85c8bb2f9bb3cd63b524bbb626ab1531176b43a109d13f5d7794f805eee"
  },
  "nbformat": 3,
  "nbformat_minor": 0,
  "worksheets": [
   {
    "cells": [
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "To use IPython widgets in the notebook, the widget namespace needs to be imported."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "from IPython.html import widgets # Widget definitions\n",
       "from IPython.display import display # Used to display widgets in the notebook"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
-     "prompt_number": 1
+     "prompt_number": 2
     },
     {
      "cell_type": "heading",
      "level": 1,
      "metadata": {},
      "source": [
       "Basic Widgets"
      ]
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "IPython comes with basic widgets that represent common interactive controls.  These widgets are\n",
       "\n",
       "- CheckboxWidget\n",
       "- ToggleButtonWidget\n",
       "- FloatSliderWidget\n",
       "- BoundedFloatTextWidget\n",
       "- FloatProgressWidget\n",
       "- FloatTextWidget\n",
       "- ImageWidget\n",
       "- IntSliderWidget\n",
       "- BoundedIntTextWidget\n",
       "- IntProgressWidget\n",
       "- IntTextWidget\n",
       "- ToggleButtonsWidget\n",
       "- RadioButtonsWidget\n",
       "- DropdownWidget\n",
       "- SelectWidget\n",
       "- HTMLWidget\n",
       "- LatexWidget\n",
       "- TextareaWidget\n",
       "- TextWidget\n",
       "- ButtonWidget\n",
       "\n",
       "A few special widgets are also included, that can be used to capture events and change how other widgets are displayed.  These widgets are\n",
       "\n",
       "- ContainerWidget\n",
       "- PopupWidget\n",
       "- AccordionWidget\n",
       "- TabWidget\n",
       "\n",
       "To see the complete list of widgets, one can execute the following"
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "[widget for widget in dir(widgets) if widget.endswith('Widget')]"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "metadata": {},
        "output_type": "pyout",
        "prompt_number": 2,
        "text": [
         "['AccordionWidget',\n",
         " 'BoundedFloatTextWidget',\n",
         " 'BoundedIntTextWidget',\n",
         " 'ButtonWidget',\n",
         " 'CheckboxWidget',\n",
         " 'ContainerWidget',\n",
         " 'DOMWidget',\n",
         " 'DropdownWidget',\n",
         " 'FloatProgressWidget',\n",
         " 'FloatSliderWidget',\n",
         " 'FloatTextWidget',\n",
         " 'HTMLWidget',\n",
         " 'ImageWidget',\n",
         " 'IntProgressWidget',\n",
         " 'IntSliderWidget',\n",
         " 'IntTextWidget',\n",
         " 'LatexWidget',\n",
         " 'PopupWidget',\n",
         " 'RadioButtonsWidget',\n",
         " 'SelectWidget',\n",
         " 'TabWidget',\n",
         " 'TextWidget',\n",
         " 'TextareaWidget',\n",
         " 'ToggleButtonWidget',\n",
         " 'ToggleButtonsWidget',\n",
         " 'Widget']"
        ]
       }
      ],
      "prompt_number": 2
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "The basic widgets all have sensible default values.  Create a *FloatSliderWidget* without displaying it:"
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mywidget = widgets.FloatSliderWidget()"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 3
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "Constructing a widget does not display it on the page.  To display a widget, the widget must be passed to the IPython `display(object)` method or must be returned as the last item in the cell.  `mywidget` is displayed by"
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "display(mywidget)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 4
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "or"
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mywidget"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 5
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "It's important to realize that widgets are not the same as output, even though they are displayed with `display`.  Widgets are drawn in a special widget area.  That area is marked with a close button which allows you to collapse the widgets.  Widgets cannot be interleaved with output.  Doing so would break the ability to make simple animations using `clear_output`.\n",
       "\n",
       "Widgets are manipulated via special instance attributes (traitlets).  The names of these traitlets are listed in the widget's `keys` attribute (as seen below).  A few of these attributes are common to most widgets.  The basic attributes are `value`, `description`, `visible`, and `disabled`.  `_css` and `_view_name` are private attributes that exist in all widgets and should not be modified."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mywidget.keys"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "metadata": {},
        "output_type": "pyout",
        "prompt_number": 6,
        "text": [
         "['_view_name',\n",
         " 'orientation',\n",
         " 'min',\n",
         " 'max',\n",
         " '_css',\n",
         " 'value',\n",
         " 'disabled',\n",
         " 'visible',\n",
         " 'step',\n",
         " 'description']"
        ]
       }
      ],
      "prompt_number": 6
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "Changing a widget's attribute will automatically update that widget everywhere it is displayed in the notebook.  Here, the `value` attribute of `mywidget` is set.  The slider shown above updates automatically with the new value.  Syncing also works in the other direction - changing the value of the displayed widget will update the property's value."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mywidget.value = 25.0"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 7
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "After changing the widget's value in the notebook by hand to 0.0 (sliding the bar to the far left)."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mywidget.value"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "metadata": {},
        "output_type": "pyout",
        "prompt_number": 8,
        "text": [
         "25.0"
        ]
       }
      ],
      "prompt_number": 8
     },
     {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
       "Widget values can also be set with kwargs during the construction of the widget (as seen below)."
      ]
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mysecondwidget = widgets.RadioButtonsWidget(values=[\"Item A\", \"Item B\", \"Item C\"], value=\"Item A\")\n",
       "display(mysecondwidget)"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [],
      "prompt_number": 9
     },
     {
      "cell_type": "code",
      "collapsed": false,
      "input": [
       "mysecondwidget.value"
      ],
      "language": "python",
      "metadata": {},
      "outputs": [
       {
        "metadata": {},
        "output_type": "pyout",
        "prompt_number": 10,
        "text": [
         "'Item A'"
        ]
       }
      ],
      "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": {}
   }
  ]
 }
  No newline at end of file