Notebook

In [1]:

from IPython.html import widgets # Widget definitions
from IPython.display import display # Used to display widgets in the notebook

CSS¶

When trying to design an attractive widget GUI, styling becomes important. Most widget views are DOM (document object model) elements that can be controlled with CSS. There are two helper methods that allow the manipulation of the widget's CSS. The first is the Widget.set_css method. This method allows one or more CSS attributes to be set at once.

In [2]:

print(widgets.DOMWidget.set_css.__doc__)

Set one or more CSS properties of the widget.

        This function has two signatures:
        - set_css(css_dict, selector='')
        - set_css(key, value, selector='')

        Parameters
        ----------
        css_dict : dict
            CSS key/value pairs to apply
        key: unicode
            CSS key
        value:
            CSS value
        selector: unicode (optional, kwarg only)
            JQuery selector to use to apply the CSS key/value.  If no selector 
            is provided, an empty selector is used.  An empty selector makes the 
            front-end try to apply the css to a default element.  The default
            element is an attribute unique to each view, which is a DOM element
            of the view that should be styled with common CSS (see 
            `$el_to_style` in the Javascript code).

The second is get_css which allows CSS attributesto be read. Note that this method will only read CSS attributes that have been set using the set_css method.

In [3]:

print(widgets.DOMWidget.get_css.__doc__)

Get a CSS property of the widget.

        Note: This function does not actually request the CSS from the 
        front-end;  Only properties that have been set with set_css can be read.

        Parameters
        ----------
        key: unicode
            CSS key
        selector: unicode (optional)
            JQuery selector used when the CSS key/value was set.

Below is an example that applies CSS attributes to a container to emphasize text.

In [4]:

label = widgets.LatexWidget()
label.value = "$\\textbf{ALERT:} Hello World!$"
container = widgets.ContainerWidget(children=[label])

# set_css used to set a single CSS attribute.
container.set_css('border', '3px solid black') # Border the container

# set_css used to set multiple CSS attributes.
container.set_css({'padding': '6px', # Add padding to the container
                   'background': 'yellow'}) # Fill the container yellow

display(container)

CSS Classes¶

In some cases, it is necessary to apply CSS classes to your widgets. CSS classes allow DOM elements to be indentified in Javascript and CSS. The notebook defines its own set of classes to stylize its elements. The add_class widget method allows you to add CSS classes to your widget.

In [5]:

print(widgets.DOMWidget.add_class.__doc__)

Add class[es] to a DOM element.

        Parameters
        ----------
        class_names: unicode or list
            Class name(s) to add to the DOM element(s).
        selector: unicode (optional)
            JQuery selector to select the DOM element(s) that the class(es) will
            be added to.

Since add_class is 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 CSS class to the container.

In [6]:

container = widgets.ContainerWidget()
container.set_css({'border': '3px solid black',
                   'padding': '6px', 
                   'background': 'yellow'}) 

label = widgets.LatexWidget()
label.value = "$\\textbf{ALERT:} Hello World!$"
container.children = [label]
display(container)
container.add_class('corner-all') # Must be called AFTER display

The IPython notebook uses bootstrap for styling. The example above can be simplified by using a bootstrap class:

In [7]:

label = widgets.LatexWidget(value = "$\\textbf{ALERT:} Hello World!$")
display(label)

# Apply twitter bootstrap alert class to the label.
label.add_class("alert")

The example below shows how bootstrap classes can be used to change button apearance.

In [8]:

# List of the bootstrap button styles
button_classes = ['Default', 'btn-primary', 'btn-info', 'btn-success', 
                  'btn-warning', 'btn-danger', 'btn-inverse', 'btn-link']

# Create each button and apply the style.  Also add margin to the buttons so they space
# themselves nicely.
for i in range(8):
    button = widgets.ButtonWidget(description=button_classes[i])
    button.set_css("margin", "5px")
    display(button)
    if i > 0: # Don't add a class the first button.
        button.add_class(button_classes[i])
    

It is also useful to be able to remove CSS classes from widgets. The remove_class 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.

In [9]:

print(widgets.DOMWidget.remove_class.__doc__)

Remove class[es] from a DOM element.

        Parameters
        ----------
        class_names: unicode or list
            Class name(s) to remove from  the DOM element(s).
        selector: unicode (optional)
            JQuery selector to select the DOM element(s) that the class(es) will
            be removed from.

The example below animates an alert using different bootstrap styles.

In [10]:

import time
label = widgets.LatexWidget(value = "$\\textbf{ALERT:} Hello World!$")
display(label)

# Apply twitter bootstrap alert class to the label.
label.add_class("alert")

# Animate through additional bootstrap label styles 3 times
additional_alert_styles = ['alert-error', 'alert-info', 'alert-success']
for i in range(3 * len(additional_alert_styles)):
    label.add_class(additional_alert_styles[i % 3])
    label.remove_class(additional_alert_styles[(i-1) % 3])
    time.sleep(1)
        