Download Buttons and Other Extensions

Download Buttons and Other Extensions#

DataTables comes with a series of extensions, which are supported by ITables since v2.0. A selection of these extensions are included in ITables.

As usual, we activate ITables with:

from itables import init_notebook_mode, show

init_notebook_mode()

and then, we create a few example dataframes:

Hide code cell source 
import string

import numpy as np
import pandas as pd

from itables.sample_dfs import get_countries

df = get_countries(html=False)
# Add columns for the searchPanes demo
df["climate_zone"] = np.where(
    df["latitude"].abs() < 23.43615,
    "Tropical",
    np.where(
        df["latitude"].abs() < 35,
        "Sub-tropical",
        # Artic circle is 66.563861 but there is no capital there => using 64
        np.where(df["latitude"].abs() < 64, "Temperate", "Frigid"),
    ),
)
df["hemisphere"] = np.where(df["latitude"] > 0, "North", "South")
wide_df = pd.DataFrame(
    {
        letter: np.random.normal(size=100)
        for letter in string.ascii_lowercase + string.ascii_uppercase
    }
)

Tip

The rocket icon at the top of the page will let you run this notebook in Binder!

Buttons#

The DataTables buttons let you copy the table data, or export it as CSV or Excel files.

To display the buttons, you need to pass a buttons argument to the show function:

show(df, buttons=["copyHtml5", "csvHtml5", "excelHtml5"])
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

You can also specify a layout modifier that will decide the location of the buttons (the default is layout={"topStart": "buttons"}). And if you want to keep the pagination control too, you can add "pageLength" to the list of buttons.

As always, it is possible to set default values for these parameters by setting these on itables.options. For instance, set

opt.buttons = ["copyHtml5", "csvHtml5", "excelHtml5"]

to get the buttons for all tables.

By default, the exported file name is the name of the HTML page. To change it, set a title option on the buttons, like here:

show(
    df,
    buttons=[
        "pageLength",
        {"extend": "csvHtml5", "title": "Countries"},
        {"extend": "excelHtml5", "title": "Countries"},
    ],
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

Tip

Only the filtered or selected rows are exported to CSV/Excel. To filter the rows you can use the simple search box, the SearchPanes and SearchBuilder options, or the select extension.

Warning

At the moment, the CSV and Excel buttons don’t work well with large tables in some browsers. Please subscribe to #251 if you wish to receive updates on this.

Warning

The PDF button is not included in ITables’ DataTable bundle. This is because the required PDF libraries have a large footprint on the bundle size. Still, you can add it to your custom bundle, see the next chapter.

Column Visibility#

The column visibility buttons of DataTables let you select which columns are visible.

show(
    # column visibility works best with a flat header
    df.reset_index(),
    buttons=["columnsToggle"],
)
code region country capital longitude latitude climate_zone hemisphere
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

Tip

The column visibility button is available under many forms.

Check-out buttons=["colvis"] for a single button. Extend the colvis button with the collection layout.

As always, when porting examples from DataTables to ITables, you will have to convert the JavaScript notation (left) to Python (right) as in the below:

buttons: [
    {
        extend: 'colvis',
        collectionLayout: 'fixed columns',
        popoverTitle: 'Column visibility control'
    }
]

buttons = [
    {
        "extend": "colvis",
        "collectionLayout": "fixed columns",
        "popoverTitle": "Column visibility control"
    }
]

SearchPanes#

SearchPanes is an extension that lets you select rows based on unique values. In the example below we have activated the cascade filtering through the searchPanes.cascadePanes argument. Note that, in Jupyter, the searchPanes.layout argument is required (otherwise the search panes are too wide).

show(
    df,
    layout={"top1": "searchPanes"},
    searchPanes={"layout": "columns-3", "cascadePanes": True, "columns": [1, 6, 7]},
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

Warning

When searching, please keep in mind that ITables will downsample your table if it is larger than maxBytes, so you might not see the full dataset - pay attention to the downsampling message at the bottom left of the table.

SearchBuilder#

SearchBuilder let you build complex search queries. You just need to add it to the layout by passing e.g. layout={"top1": "searchBuilder"}.

It is possible to set a predefined search, as we do in the below:

show(
    df,
    layout={"top1": "searchBuilder"},
    searchBuilder={
        "preDefined": {
            "criteria": [
                {"data": "climate_zone", "condition": "=", "value": ["Sub-tropical"]}
            ]
        }
    },
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

FixedColumns#

FixedColumn is an extension that let you fix some columns as you scroll horizontally.

show(
    wide_df,
    fixedColumns={"start": 1, "end": 2},
    scrollX=True,
)
a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

KeyTable#

With the KeyTable extension you can navigate in a table using the arrow keys:

show(df, keys=True)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)

Tip

You can activate this option for all your tables with

import itables.options as opt

opt.keys = True

Warning

The KeyTable extension works in Jupyter Book (try it here in the documentation) but not in JupyterLab.

RowGroup#

Use the RowGroup extension to group the data according to the content of one colum. Optionally, you can hide the content of that column to avoid duplicating the information.

show(
    df.sort_values("region"),
    rowGroup={"dataSrc": 1},
    columnDefs=[{"targets": 1, "visible": False}],
)
region country capital longitude latitude climate_zone hemisphere
code
Loading ITables v2.2.4 from the init_notebook_mode cell... (need help?)