examples/widgets/Part 4 - Styles.ipynb

{
 "metadata": {
  "cell_tags": [
   [
    "<None>",
    null
   ]
  ],
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[< Back to Part 3](Part 3 - Placement.ipynb) or [Index](index.ipynb)"
     ]
    },
    {
     "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
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "CSS"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "When trying to design an attractive widget GUI, styling becomes important.  Most Widgets views are DOM (document object model) elements that can be controlled with CSS.  There are two helper methods defined on widget that allow the manipulation of the widget's CSS.  The first is the `set_css` method, whos doc string is displayed below.  This method allows one or more CSS attributes to be set at once.  "
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.set_css.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Set one or more CSS properties of the widget.\n",
        "\n",
        "        This function has two signatures:\n",
        "        - set_css(css_dict, selector='')\n",
        "        - set_css(key, value, selector='')\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        css_dict : dict\n",
        "            CSS key/value pairs to apply\n",
        "        key: unicode\n",
        "            CSS key\n",
        "        value\n",
        "            CSS value\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector to use to apply the CSS key/value.  If no selector \n",
        "            is provided, an empty selector is used.  An empty selector makes the \n",
        "            front-end try to apply the css to a default element.  The default\n",
        "            element is an attribute unique to each view, which is a DOM element\n",
        "            of the view that should be styled with common CSS (see \n",
        "            `$el_to_style` in the Javascript code).\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The second is `get_css` which allows CSS attributes that have been set to be read.  Note that this method will only read CSS attributes that have been set using the `set_css` method.  `get_css`'s doc string is displayed below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.get_css.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Get a CSS property of the widget.\n",
        "\n",
        "        Note: This function does not actually request the CSS from the \n",
        "        front-end;  Only properties that have been set with set_css can be read.\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        key: unicode\n",
        "            CSS key\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector used when the CSS key/value was set.\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Below is an example that applies CSS attributes to a container to emphasize text."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "label = widgets.LatexWidget()\n",
      "label.value = \"$\\\\textbf{ALERT:} Hello World!$\"\n",
      "container = widgets.ContainerWidget(children=[label])\n",
      "\n",
      "# set_css used to set a single CSS attribute.\n",
      "container.set_css('border', '3px solid black') # Border the container\n",
      "\n",
      "# set_css used to set multiple CSS attributes.\n",
      "container.set_css({'padding': '6px', # Add padding to the container\n",
      "                   'background': 'yellow'}) # Fill the container yellow\n",
      "\n",
      "display(container)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "DOM Classes"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In some cases it's necessary to apply DOM classes to your widgets.  DOM classes allow DOM elements to be indentified by Javascript and CSS.  The notebook defines its own set of classes to stylize its elements.  The `add_class` widget method allows you to add DOM classes to your widget's definition.  The `add_class` method's doc string can be seen below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.add_class.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Add class[es] to a DOM element.\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        class_names: unicode or list\n",
        "            Class name(s) to add to the DOM element(s).\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector to select the DOM element(s) that the class(es) will\n",
        "            be added to.\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Since `add_class` if a DOM operation, **it will only affect widgets that have already been displayed**.  `add_class` must be called after the widget has been displayed.  Extending the example above, the corners of the container can be rounded by adding the `corner-all` notebook class to the container (as seen below).  "
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "container = widgets.ContainerWidget()\n",
      "container.set_css({'border': '3px solid black',\n",
      "                   'padding': '6px', \n",
      "                   'background': 'yellow'}) \n",
      "\n",
      "label = widgets.LatexWidget()\n",
      "label.value = \"$\\\\textbf{ALERT:} Hello World!$\"\n",
      "container.children = [label]\n",
      "display(container)\n",
      "container.add_class('corner-all') # Must be called AFTER display"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The IPython notebook uses bootstrap for styling.  The example above can be simplified by using a bootstrap class (as seen below).  Bootstrap documentation can be found at http://getbootstrap.com/\u200e ."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "label = widgets.LatexWidget(value = \"$\\\\textbf{ALERT:} Hello World!$\")\n",
      "display(label)\n",
      "\n",
      "# Apply twitter bootstrap alert class to the label.\n",
      "label.add_class(\"alert\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The example below shows how bootstrap classes can be used to change button apearance."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# List of the bootstrap button styles\n",
      "button_classes = ['Default', 'btn-primary', 'btn-info', 'btn-success', \n",
      "                  'btn-warning', 'btn-danger', 'btn-inverse', 'btn-link']\n",
      "\n",
      "# Create each button and apply the style.  Also add margin to the buttons so they space\n",
      "# themselves nicely.\n",
      "for i in range(8):\n",
      "    button = widgets.ButtonWidget(description=button_classes[i])\n",
      "    button.set_css(\"margin\", \"5px\")\n",
      "    display(button)\n",
      "    if i > 0: # Don't add a class the first button.\n",
      "        button.add_class(button_classes[i])\n",
      "    "
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It's also useful to be able to remove DOM classes from widgets.  The `remove_class` widget method allows you to remove classes from widgets that have been displayed.  Like `add_class`, it must be called after the widget has been displayed.  The doc string of `remove_class` can be seen below."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.remove_class.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Remove class[es] from a DOM element.\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        class_names: unicode or list\n",
        "            Class name(s) to remove from  the DOM element(s).\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector to select the DOM element(s) that the class(es) will\n",
        "            be removed from.\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The example below animates an alert using different bootstrap styles."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import time\n",
      "label = widgets.LatexWidget(value = \"$\\\\textbf{ALERT:} Hello World!$\")\n",
      "display(label)\n",
      "\n",
      "# Apply twitter bootstrap alert class to the label.\n",
      "label.add_class(\"alert\")\n",
      "\n",
      "# Animate through additional bootstrap label styles 3 times\n",
      "additional_alert_styles = ['alert-error', 'alert-info', 'alert-success']\n",
      "for i in range(3 * len(additional_alert_styles)):\n",
      "    label.add_class(additional_alert_styles[i % 3])\n",
      "    label.remove_class(additional_alert_styles[(i-1) % 3])\n",
      "    time.sleep(1)\n",
      "        "
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In [Part 5](Part 5 - Alignment.ipynb) of this [series](index.ipynb), you will learn about widget alignment."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}