Add the column visibility button

mwouts · Jun 7, 2024 · a6935c2 · a6935c2
1 parent 1b42c1c
commit a6935c2
Show file tree

Hide file tree

Showing 13 changed files with 165 additions and 51 deletions.
diff --git a/docs/advanced_parameters.md b/docs/advanced_parameters.md
@@ -59,20 +59,8 @@ You can set additional `tags` on the table like e.g. a [caption](https://datatab
 show(df, "Countries from the World Bank Database")
 ```
 
-The caption appears at the bottom of the table by default (except
-in Jupyter Book). This is governed by `caption-side:bottom`
-in the [`style` option](style).
-
-You can also override the location of the caption in the caption tag itself:
-
-```{code-cell}
-:tags: [full-width]
-
-show(
-    df,
-    tags='<caption style="caption-side: bottom">Countries from the World Bank Database</caption>',
-)
-```
+The caption appears at the bottom of the table by default: this is governed by `caption-side:bottom`
+in the [`style` option](style) (but for some reason this is not effective in Jupyter Book 😕).
 
 (layout)=
 ## Table layout

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -8,6 +8,10 @@ ITables ChangeLog
 - We have added an explicit `encoding` argument in the calls to `read_text` to address an issue seen on Windows ([#252](https://github.com/mwouts/itables/issues/252)).
 - We have adjusted the codecov settings ([#280](https://github.com/mwouts/itables/pull/280))
 
+**Changed**
+- We have added a default css on `dt-container` equal to `{max-width:100%}`.
+- We have updated `datatables.net-dt` to `2.0.8`, and included the [column visibility button](https://datatables.net/extensions/buttons/examples/column_visibility/simple.html) in the `dt_for_itables` package ([#284](https://github.com/mwouts/itables/issues/284))
+
 
 2.1.0 (2024-05-27)
 ------------------

diff --git a/docs/extensions.md b/docs/extensions.md
@@ -102,6 +102,12 @@ show(
 )
 ```
 
+```{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](#searchpanes) and [SearchBuilder](#searchbuilder)
+options, or the [select](#row-selection) extension.
+```
+
 ```{warning}
 At the moment, the CSV and Excel buttons don't work well with large tables in some browsers.
 Please subscribe to [#251](https://github.com/mwouts/itables/issues/251) if you wish to receive updates on this.
@@ -112,6 +118,64 @@ The PDF button is not included in ITables' DataTable bundle. This is because the
 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](https://datatables.net/extensions/buttons/examples/column_visibility/index.html)
+buttons of DataTables let you select which columns are visible.
+
+```{code-cell}
+:tags: [full-width]
+
+show(
+    # column visibility works best with a flat header
+    df.reset_index(),
+    buttons=["columnsToggle"],
+)
+```
+
+```{tip}
+The column visibility button is available under many forms.
+
+Check-out `buttons=["colvis"]`
+for a [single](https://datatables.net/extensions/buttons/examples/column_visibility/simple.html) button.
+Extend the `colvis` button with the
+[collection layout](https://datatables.net/extensions/buttons/examples/column_visibility/layout.html).
+
+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:
+::::{grid}
+
+:::{grid-item}
+:outline:
+:columns: 6
+~~~javascript
+buttons: [
+    {
+        extend: 'colvis',
+        collectionLayout: 'fixed columns',
+        popoverTitle: 'Column visibility control'
+    }
+]
+~~~
+:::
+:::{grid-item}
+:outline:
+:columns: 6
+~~~python
+buttons = [
+    {
+        "extend": "colvis",
+        "collectionLayout": "fixed columns",
+        "popoverTitle": "Column visibility control"
+    }
+]
+~~~
+:::
+
+::::
+
+```
+
 ## SearchPanes
 
 [SearchPanes](https://datatables.net/extensions/searchpanes/) is an extension that lets you select rows based on
@@ -197,6 +261,32 @@ opt.keys = True
 The KeyTable extension works in Jupyter Book (try it here in the documentation) but not in JupyterLab.
 ```
 
+## Row selection
+
+The [select](https://datatables.net/extensions/select) extension let you select rows (or cells). When you do so,
+only the selected rows are exported
+
+```{code-cell}
+:tags: [full-width]
+
+show(df, select=True, buttons=["copyHtml5", "csvHtml5", "excelHtml5"])
+```
+
+```{tip}
+The `select` option accept multiple values, as documented [here](https://datatables.net/extensions/select):
+- `select=True` or `select="os"` let you select using single click, shift-click and ctrl-click
+- `select="single"` let you select a single row
+- `select="multi"` for single click selection of multiple rows, `select="multi+shift"`, ...
+
+With `select={"style": "os", "items": "cell"}` you can let the user select specific cells,
+however cell selection is not taken into account when exporting the data.
+```
+
+```{tip}
+At the moment it is not possible to get the selected rows back in Python. Please subscribe to
+[#250](https://github.com/mwouts/itables/issues/250) to get updates on this topic.
+```
+
 ## RowGroup
 
 Use the [RowGroup](https://datatables.net/extensions/rowgroup/) extension to group

diff --git a/packages/dt_for_itables/CHANGELOG.md b/packages/dt_for_itables/CHANGELOG.md
@@ -1,3 +1,13 @@
+# 2.0.10 (2024-06-08)
+
+**Added**
+- The default css for `dt-container` is `{max-width:100%;}`
+- We have included the `colvis` button in the package
+
+**Changed**
+- Updated `datatables.net-dt==2.0.8` and `datatables.net-select-dt==2.0.3`
+
+
 # 2.0.7 (2024-05-26)
 
 **Added**

diff --git a/packages/dt_for_itables/package-lock.json b/packages/dt_for_itables/package-lock.json
diff --git a/packages/dt_for_itables/package.json b/packages/dt_for_itables/package.json
@@ -1,9 +1,20 @@
 {
   "name": "dt_for_itables",
-  "version": "2.0.7",
+  "version": "2.0.10",
   "description": "DataTables bundle for itables",
   "main": "src/index.js",
   "typings": "src/index.d.js",
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "dt_bundle.js",
+    "dt_bundle.css",
+    "package.json",
+    "src/index.js",
+    "src/index.css",
+    "src/index.d.ts"
+  ],
   "scripts": {
     "build:js": "esbuild src/index.js --format=esm --bundle --outfile=dt_bundle.js --minify",
     "install:js": "cp dt_bundle.js dt_bundle.css  ../../src/itables/html",

diff --git a/packages/dt_for_itables/src/index.css b/packages/dt_for_itables/src/index.css
@@ -0,0 +1,3 @@
+.dt-container {
+    max-width: 100%;
+}
diff --git a/packages/dt_for_itables/src/index.js b/packages/dt_for_itables/src/index.js
@@ -4,8 +4,9 @@ import DataTable from 'datatables.net-dt';
 import 'datatables.net-dt/css/dataTables.dataTables.min.css';
 
 import 'datatables.net-buttons-dt';
-import 'datatables.net-buttons/js/buttons.html5.mjs';
-import 'datatables.net-buttons/js/buttons.print.mjs';
+import 'datatables.net-buttons/js/buttons.html5.min.mjs';
+import 'datatables.net-buttons/js/buttons.print.min.mjs';
+import 'datatables.net-buttons/js/buttons.colVis.min.mjs';
 import 'datatables.net-buttons-dt/css/buttons.dataTables.min.css';
 
 DataTable.Buttons.jszip(JSZip);
@@ -28,6 +29,8 @@ import 'datatables.net-searchpanes-dt/css/searchPanes.dataTables.min.css';
 import 'datatables.net-select-dt';
 import 'datatables.net-select-dt/css/select.dataTables.min.css';
 
+import './index.css';
+
 export { DataTable, jQuery };
 
 export default DataTable;
diff --git a/packages/itables_for_streamlit/package-lock.json b/packages/itables_for_streamlit/package-lock.json
diff --git a/src/itables/html/datatables_template.html b/src/itables/html/datatables_template.html
@@ -1,7 +1,7 @@
 <table id="table_id"><thead><tr><th>A</th></tr></thead></table>
-<link href="https://www.unpkg.com/dt_for_itables@2.0.7/dt_bundle.css" rel="stylesheet">
+<link href="https://www.unpkg.com/dt_for_itables/dt_bundle.css" rel="stylesheet">
 <script type="module">
-    import {DataTable, jQuery as $} from 'https://www.unpkg.com/dt_for_itables@2.0.7/dt_bundle.js';
+    import {DataTable, jQuery as $} from 'https://www.unpkg.com/dt_for_itables/dt_bundle.js';
 
     document.querySelectorAll("#table_id:not(.dataTable)").forEach(table => {
         // Define the table data

diff --git a/src/itables/javascript.py b/src/itables/javascript.py
@@ -10,7 +10,7 @@
 import numpy as np
 import pandas as pd
 
-from .utils import UNPKG_DT_BUNDLE_CSS, UNPKG_DT_BUNDLE_URL
+from .utils import UNPKG_DT_BUNDLE_CSS_NO_VERSION, UNPKG_DT_BUNDLE_URL_NO_VERSION
 from .version import __version__ as itables_version
 
 try:
@@ -738,17 +738,21 @@ def html_table_from_template(
     output = read_package_file("html/datatables_template.html")
     if connected:
         assert dt_url.endswith(".js")
-        output = replace_value(output, UNPKG_DT_BUNDLE_URL, dt_url)
+        output = replace_value(output, UNPKG_DT_BUNDLE_URL_NO_VERSION, dt_url)
         output = replace_value(
             output,
-            UNPKG_DT_BUNDLE_CSS,
+            UNPKG_DT_BUNDLE_CSS_NO_VERSION,
             dt_url[:-3] + ".css",
         )
     else:
-        connected_style = f'<link href="{UNPKG_DT_BUNDLE_CSS}" rel="stylesheet">\n'
+        connected_style = (
+            f'<link href="{UNPKG_DT_BUNDLE_CSS_NO_VERSION}" rel="stylesheet">\n'
+        )
         output = replace_value(output, connected_style, "")
         connected_import = (
-            "import {DataTable, jQuery as $} from '" + UNPKG_DT_BUNDLE_URL + "';"
+            "import {DataTable, jQuery as $} from '"
+            + UNPKG_DT_BUNDLE_URL_NO_VERSION
+            + "';"
         )
         local_import = (
             "const { DataTable, jQuery: $ } = await import(window."

diff --git a/src/itables/utils.py b/src/itables/utils.py
@@ -1,8 +1,10 @@
 from io import open
 from pathlib import Path
 
-UNPKG_DT_BUNDLE_URL = "https://www.unpkg.com/[email protected].7/dt_bundle.js"
+UNPKG_DT_BUNDLE_URL = "https://www.unpkg.com/[email protected].10/dt_bundle.js"
 UNPKG_DT_BUNDLE_CSS = UNPKG_DT_BUNDLE_URL.replace(".js", ".css")
+UNPKG_DT_BUNDLE_URL_NO_VERSION = "https://www.unpkg.com/dt_for_itables/dt_bundle.js"
+UNPKG_DT_BUNDLE_CSS_NO_VERSION = "https://www.unpkg.com/dt_for_itables/dt_bundle.css"
 
 
 def find_package_file(*path):

diff --git a/tests/test_javascript.py b/tests/test_javascript.py
@@ -5,14 +5,13 @@
 import requests
 
 from itables.javascript import (
-    UNPKG_DT_BUNDLE_CSS,
-    UNPKG_DT_BUNDLE_URL,
     _df_fits_in_one_page,
     _tfoot_from_thead,
     check_table_id,
     replace_value,
     to_html_datatable,
 )
+from itables.utils import UNPKG_DT_BUNDLE_CSS, UNPKG_DT_BUNDLE_URL
 
 
 def test_replace_value(