Custom tags (#73)

Author: mwouts

CHANGELOG.md

@@ -1,3 +1,10 @@
+0.4.7 (2022-04-13)
+==================
+
+Added
+-----
+- Additional `tags` like e.g. captions are supported (#10).
+
 0.4.6 (2022-03-29)
 ==================
 

docs/advanced_parameters.md

@@ -5,7 +5,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.11.5
+    jupytext_version: 1.13.8
 kernelspec:
   display_name: itables
   language: python
@@ -91,6 +91,19 @@ opt.classes = ["display", "cell-border"]
 df
 ```
 
+## Table captions
+
+You can set additional `tags` like a [caption](https://datatables.net/blog/2014-11-07) on the table with the `tags` option:
+
+```{code-cell}
+show(df, tags='<caption>Countries from the World Bank Database</caption>')
+```
+
+The position of the caption can be set explicitly as in the datatables example above (note that the default position may depend on how you render the notebook):
+```{code-cell}
+show(df, tags='<caption style="caption-side: top">Countries from the World Bank Database</caption>')
+```
+
 ## Float precision
 
 Floats are rounded using `pd.options.display.float_format`. Please change that format according to your preference.

environment.yml

@@ -6,7 +6,7 @@ dependencies:
   - python
   - jupyter
   - jupyterlab
-  - jupytext
+  - jupytext>=1.13.8
   - markdown-it-py>=2.0
   - nbconvert
   - ipykernel

itables/javascript.py

@@ -63,7 +63,7 @@ def _formatted_values(df):
     return formatted_df.values.tolist()
 
 
-def _table_header(df, table_id, show_index, classes, style):
+def _table_header(df, table_id, show_index, classes, style, tags):
     """This function returns the HTML table header. Rows are not included."""
     # Generate table head using pandas.to_html(), see issue 63
     pattern = re.compile(r".*<thead>(.*)</thead>", flags=re.MULTILINE | re.DOTALL)
@@ -80,7 +80,7 @@ def _table_header(df, table_id, show_index, classes, style):
     else:
         style = ""
 
-    return f'<table id="{table_id}" class="{classes}"{style}><thead>{thead}</thead><tbody>{tbody}</tbody></table>'
+    return f'<table id="{table_id}" class="{classes}"{style}>{tags}<thead>{thead}</thead><tbody>{tbody}</tbody></table>'
 
 
 def eval_functions_dumps(obj):
@@ -124,6 +124,7 @@ def _datatables_repr_(df=None, tableId=None, **kwargs):
     # These options are used here, not in DataTable
     classes = kwargs.pop("classes")
     style = kwargs.pop("style")
+    tags = kwargs.pop("tags")
     showIndex = kwargs.pop("showIndex")
     maxBytes = kwargs.pop("maxBytes", 0)
     maxRows = kwargs.pop("maxRows", 0)
@@ -155,7 +156,7 @@ def _datatables_repr_(df=None, tableId=None, **kwargs):
     if not showIndex:
         df = df.set_index(pd.RangeIndex(len(df.index)))
 
-    table_header = _table_header(df, tableId, showIndex, classes, style)
+    table_header = _table_header(df, tableId, showIndex, classes, style, tags)
     output = replace_value(
         output,
         '<table id="table_id"><thead><tr><th>A</th></tr></thead></table>',

itables/options.py

@@ -10,6 +10,9 @@
 """Default table style"""
 style = "max-width:100%"
 
+"""Additional tags like e.g. caption"""
+tags = ""
+
 """Maximum bytes for displaying a table"""
 maxBytes = 2**16
 

itables/version.py

@@ -1,3 +1,3 @@
 """ITables' version number"""
 
-__version__ = "0.4.6"
+__version__ = "0.4.7"