gdtest-tbl-explorer
A showcase site demonstrating the tbl_explorer() function from Great Docs. Each user-guide page exercises a different combination of data sources, interactive features, and display options.
Interactive table explorer showcase exercising tbl_explorer() with eight user-guide pages: basic sorting/filtering, pagination (custom page sizes, no pagination), column toggling (wide tables, subsets, toggle disabled), copy/download controls (various combinations), missing-value highlighting, minimal chrome (hide row numbers, dtypes, dimensions), tbl-explorer Quarto shortcode with CSV/TSV/JSONL files, and a side-by-side comparison of tbl_preview() vs tbl_explorer().
Source files
assets/
cities.csv
city,country,population,latitude,longitude Tokyo,Japan,13960000,35.6762,139.6503 Paris,France,2161000,48.8566,2.3522 New York,USA,8336000,40.7128,-74.0060 London,UK,8982000,51.5074,-0.1278 Sydney,Australia,5312000,-33.8688,151.2093 Berlin,Germany,3645000,52.5200,13.4050 Mumbai,India,20411000,19.0760,72.8777 São Paulo,Brazil,12330000,-23.5505,-46.6333 Cairo,Egypt,10230000,30.0444,31.2357 Toronto,Canada,2930000,43.6532,-79.3832 Seoul,South Korea,9776000,37.5665,126.9780 Mexico City,Mexico,9210000,19.4326,-99.1332
logs.jsonl
{"ts":"2025-01-15T08:30:00","level":"INFO","module":"auth","msg":"User login OK"}
{"ts":"2025-01-15T08:31:12","level":"WARN","module":"db","msg":"Slow query (3.2s)"}
{"ts":"2025-01-15T08:32:45","level":"ERROR","module":"api","msg":"Timeout /v2/users"}
{"ts":"2025-01-15T08:33:01","level":"INFO","module":"cache","msg":"Cache miss user:42"}
{"ts":"2025-01-15T08:34:20","level":"DEBUG","module":"auth","msg":"Token refresh abc123"}
{"ts":"2025-01-15T08:35:55","level":"ERROR","module":"db","msg":"Pool exhausted"}products.tsv
product category price stock rating Widget Electronics 29.99 150 4.5 Gadget Tools 49.50 80 3.8 Gizmo Kitchen 12.00 300 4.9 Doohickey Garden 8.75 0 4.2 Thingamajig Office 199.99 25 2.1 Contraption Electronics 65.00 44 3.5 Apparatus Tools 120.00 12 4.7
gdtest_tbl_explorer/
__init__.py
"""Sample data generators for table explorer demos."""
__version__ = "0.1.0"
__all__ = [
"sample_cities",
"sample_products",
"sample_wide",
"sample_missing",
"sample_large",
]
from .data import (
sample_cities,
sample_products,
sample_wide,
sample_missing,
sample_large,
)data.py
"""Functions that generate sample data for explorer demos."""
from __future__ import annotations
def sample_cities(n: int = 12) -> dict[str, list]:
"""
Generate a world cities dataset.
Parameters
----------
n
Number of rows.
Returns
-------
dict[str, list]
Column-oriented dict with city, country, population,
latitude, and longitude columns.
Examples
--------
>>> data = sample_cities(5)
>>> len(data["city"])
5
"""
cities = [
("Tokyo", "Japan", 13960000, 35.6762, 139.6503),
("Paris", "France", 2161000, 48.8566, 2.3522),
("New York", "USA", 8336000, 40.7128, -74.0060),
("London", "UK", 8982000, 51.5074, -0.1278),
("Sydney", "Australia", 5312000, -33.8688, 151.2093),
("Berlin", "Germany", 3645000, 52.5200, 13.4050),
("Mumbai", "India", 20411000, 19.0760, 72.8777),
("São Paulo", "Brazil", 12330000, -23.5505, -46.6333),
("Cairo", "Egypt", 10230000, 30.0444, 31.2357),
("Toronto", "Canada", 2930000, 43.6532, -79.3832),
("Seoul", "South Korea", 9776000, 37.5665, 126.9780),
("Mexico City", "Mexico", 9210000, 19.4326, -99.1332),
("Lagos", "Nigeria", 15400000, 6.5244, 3.3792),
("Bangkok", "Thailand", 10540000, 13.7563, 100.5018),
("Istanbul", "Turkey", 15460000, 41.0082, 28.9784),
]
rows = cities[:n]
return {
"city": [r[0] for r in rows],
"country": [r[1] for r in rows],
"population": [r[2] for r in rows],
"latitude": [r[3] for r in rows],
"longitude": [r[4] for r in rows],
}
def sample_products(n: int = 15) -> dict[str, list]:
"""
Generate a product catalog dataset.
Parameters
----------
n
Number of rows.
Returns
-------
dict[str, list]
Column-oriented dict with product, category, price,
stock, rating, and in_stock columns.
Examples
--------
>>> data = sample_products(5)
>>> len(data["product"])
5
"""
import random
random.seed(42)
products = [
"Widget", "Gadget", "Doohickey", "Thingamajig",
"Gizmo", "Whatchamacallit", "Contraption", "Apparatus",
"Device", "Instrument", "Mechanism", "Implement",
"Tool", "Utensil", "Component",
]
categories = ["Electronics", "Tools", "Kitchen", "Garden", "Office"]
rows = []
for i in range(n):
name = products[i % len(products)]
cat = random.choice(categories)
price = round(random.uniform(5.0, 250.0), 2)
stock = random.randint(0, 500)
rating = round(random.uniform(1.0, 5.0), 1)
rows.append((name, cat, price, stock, rating, stock > 0))
return {
"product": [r[0] for r in rows],
"category": [r[1] for r in rows],
"price": [r[2] for r in rows],
"stock": [r[3] for r in rows],
"rating": [r[4] for r in rows],
"in_stock": [r[5] for r in rows],
}
def sample_wide(n_rows: int = 10, n_cols: int = 15) -> dict[str, list]:
"""
Generate a wide dataset with many numeric columns.
Parameters
----------
n_rows
Number of rows.
n_cols
Number of data columns (plus an id column).
Returns
-------
dict[str, list]
Column-oriented dict with an ``id`` column and
``metric_001`` through ``metric_{n_cols:03d}``.
Examples
--------
>>> data = sample_wide(5, 8)
>>> len(data)
9
"""
import random
random.seed(7)
result = {"id": list(range(n_rows))}
for i in range(n_cols):
result[f"metric_{i+1:03d}"] = [
round(random.gauss(0, 1), 3) for _ in range(n_rows)
]
return result
def sample_missing(n: int = 12) -> dict[str, list]:
"""
Generate a dataset with scattered missing values.
Parameters
----------
n
Number of rows.
Returns
-------
dict[str, list]
Column-oriented dict with name, value, category, and
score columns. Some cells are None.
Examples
--------
>>> data = sample_missing(5)
>>> None in data["value"]
True
"""
import random
random.seed(13)
names = ["Alpha", "Beta", "Gamma", "Delta", "Epsilon",
"Zeta", "Eta", "Theta", "Iota", "Kappa",
"Lambda", "Mu"]
categories = ["A", "B", "C", None]
rows_name = [names[i % len(names)] for i in range(n)]
rows_val = [
None if random.random() < 0.25
else round(random.uniform(10, 100), 1)
for _ in range(n)
]
rows_cat = [random.choice(categories) for _ in range(n)]
rows_score = [
None if random.random() < 0.2
else random.randint(1, 100)
for _ in range(n)
]
return {
"name": rows_name,
"value": rows_val,
"category": rows_cat,
"score": rows_score,
}
def sample_large(n: int = 200) -> dict[str, list]:
"""
Generate a large dataset for pagination testing.
Parameters
----------
n
Number of rows.
Returns
-------
dict[str, list]
Column-oriented dict with id, name, department, salary,
years, and active columns.
Examples
--------
>>> data = sample_large(50)
>>> len(data["id"])
50
"""
import random
random.seed(123)
first_names = [
"Alice", "Bob", "Charlie", "Diana", "Eve", "Frank",
"Grace", "Hank", "Iris", "Jack", "Karen", "Leo",
"Mona", "Nate", "Olivia", "Paul", "Quinn", "Rosa",
]
depts = [
"Engineering", "Marketing", "Sales", "Finance",
"HR", "Operations", "Legal", "R&D",
]
return {
"id": list(range(1, n + 1)),
"name": [random.choice(first_names) for _ in range(n)],
"department": [random.choice(depts) for _ in range(n)],
"salary": [random.randint(50000, 200000) for _ in range(n)],
"years": [random.randint(1, 30) for _ in range(n)],
"active": [random.random() > 0.15 for _ in range(n)],
}user_guide/
01-basic-explorer.qmd
---
title: Basic Explorer
---
The `tbl_explorer()` function creates interactive tables with
sorting, filtering, pagination, and more.
## Default Options
Pass a dictionary and get a fully interactive table:
```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_cities
tbl_explorer(sample_cities())
```
Try clicking column headers to sort, or type in the filter box.
## With Caption
```{python}
#| echo: false
tbl_explorer(sample_cities(), caption="World Cities")
```
## Product Catalog
```{python}
#| echo: false
from gdtest_tbl_explorer import sample_products
tbl_explorer(sample_products(), caption="Product Catalog")
```02-pagination.qmd
---
title: Pagination
---
With larger datasets, `tbl_explorer()` paginates automatically.
## Default Page Size (20 rows)
```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_large
tbl_explorer(sample_large(200), caption="200 Employees")
```
## Custom Page Size (10 rows)
```{python}
#| echo: false
tbl_explorer(sample_large(200), page_size=10, caption="10 per page")
```
## Large Page Size (50 rows)
```{python}
#| echo: false
tbl_explorer(sample_large(200), page_size=50, caption="50 per page")
```
## No Pagination
Set `page_size=0` to show all rows at once:
```{python}
#| echo: false
tbl_explorer(sample_large(30), page_size=0, caption="All 30 rows")
```03-column-toggle.qmd
---
title: Column Toggling
---
Use the **Columns** dropdown in the toolbar to show/hide columns.
## Wide Table
This table has 16 columns — try hiding some:
```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_wide
tbl_explorer(sample_wide(10, 15), caption="Wide Metrics Table")
```
## Column Subset
Pre-select specific columns with `columns=`:
```{python}
#| echo: false
from gdtest_tbl_explorer import sample_cities
tbl_explorer(
sample_cities(),
columns=["city", "country", "population"],
caption="Cities — 3 columns only",
)
```
## Toggle Disabled
Set `column_toggle=False` to remove the dropdown:
```{python}
#| echo: false
tbl_explorer(
sample_cities(),
column_toggle=False,
caption="No column toggle",
)
```04-copy-download.qmd
---
title: Copy & Download
---
The toolbar includes **Copy** (TSV to clipboard) and **Download**
(CSV file) buttons.
## Full Controls
```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_products
tbl_explorer(sample_products(), caption="Copy or download this table")
```
## Copy Only (No Download)
```{python}
#| echo: false
tbl_explorer(
sample_products(),
downloadable=False,
caption="Copy button only",
)
```
## Download Only (No Copy)
```{python}
#| echo: false
tbl_explorer(
sample_products(),
copyable=False,
caption="Download button only",
)
```
## No Export Controls
```{python}
#| echo: false
tbl_explorer(
sample_products(),
copyable=False,
downloadable=False,
caption="No export buttons",
)
```05-missing-values.qmd
---
title: Missing Values
---
Missing values (`None`, `NaN`) are highlighted in red by default.
## Default Highlighting
```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_missing
tbl_explorer(sample_missing(), caption="Missing values highlighted")
```
## Highlighting Off
```{python}
#| echo: false
tbl_explorer(
sample_missing(),
highlight_missing=False,
caption="Missing values NOT highlighted",
)
```06-minimal-chrome.qmd
---
title: Minimal Chrome
---
Strip away table chrome for a clean, data-focused look.
## No Row Numbers
```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_cities
tbl_explorer(
sample_cities(),
show_row_numbers=False,
caption="No row numbers",
)
```
## No Dtype Labels
```{python}
#| echo: false
tbl_explorer(
sample_cities(),
show_dtypes=False,
caption="No dtype labels",
)
```
## No Header Banner
```{python}
#| echo: false
tbl_explorer(
sample_cities(),
show_dimensions=False,
caption="No header banner",
)
```
## Fully Minimal
No row numbers, no dtypes, no dimensions — just the data and controls:
```{python}
#| echo: false
tbl_explorer(
sample_cities(),
show_row_numbers=False,
show_dtypes=False,
show_dimensions=False,
caption="Fully minimal",
)
```
## Filter Only (No Other Controls)
```{python}
#| echo: false
tbl_explorer(
sample_cities(),
sortable=False,
column_toggle=False,
copyable=False,
downloadable=False,
caption="Filter only",
)
```07-shortcode.qmd
---
title: Shortcode Explorer
---
The `{{< tbl-explorer >}}` shortcode embeds interactive tables
from data files — no Python code cells needed.
## CSV File
{{< tbl-explorer file="assets/cities.csv" >}}
## With Caption
{{< tbl-explorer file="assets/cities.csv" caption="World Cities (shortcode)" >}}
## TSV File
{{< tbl-explorer file="assets/products.tsv" caption="Products (TSV)" >}}
## JSONL File
{{< tbl-explorer file="assets/logs.jsonl" caption="Server Logs (JSONL)" >}}
## Custom Options
{{< tbl-explorer file="assets/cities.csv" page_size="5" caption="5 per page" >}}
## No Filter
{{< tbl-explorer file="assets/cities.csv" filterable="false" caption="No filter input" >}}08-comparison.qmd
---
title: Preview vs Explorer
---
Compare the static `tbl_preview()` with the interactive
`tbl_explorer()` side by side.
## Static Preview
```{python}
#| echo: false
from great_docs import tbl_preview
from gdtest_tbl_explorer import sample_cities
tbl_preview(sample_cities(), caption="Static preview")
```
## Interactive Explorer
```{python}
#| echo: false
from great_docs import tbl_explorer
tbl_explorer(sample_cities(), caption="Interactive explorer")
```
The explorer adds a toolbar with filter, column toggle, copy,
download, and reset controls. Column headers are sortable.
The static preview is lighter and works without JavaScript.README.md
# gdtest-tbl-explorer A showcase site demonstrating the `tbl_explorer()` function from Great Docs. Each user-guide page exercises a different combination of data sources, interactive features, and display options.
great-docs.yml
{}