Auto-detect extensions from options

Description

Scans the options list for keys that imply certain extensions. For example, buttons implies Buttons, select implies Select, etc.

Usage

.dt2_detect_extensions(options)

Arguments

Value

character vector of detected extension names

Get all current library versions in DT2

Description

Core library versions here must be kept in sync with R/dt2_deps.R and tools/get-dt2-libs.sh. Extension versions are read from the registry automatically.

Usage

.dt2_lib_versions()

Value

Named character vector

Lock Bootstrap mode per document (prevents mixing core/bootstrap5)

Description

Lock Bootstrap mode per document (prevents mixing core/bootstrap5)

Usage

.dt2_lock_mode(bs)

Mapping of DT2 library names to npm package names

Description

Mapping of DT2 library names to npm package names

Usage

.dt2_npm_map()

Internal: parse DataTables server-side request (query string to list)

Description

Internal: parse DataTables server-side request (query string to list)

Usage

.dt2_parse_ssp_request(req, n_cols)

Internal: build DataTables JSON payload

Description

Internal: build DataTables JSON payload

Usage

.dt2_payload(draw, total, filtered, data_rows)

Resolve extension names with dependency ordering

Description

Resolve extension names with dependency ordering

Usage

.dt2_resolve_extensions(extensions)

Arguments

Value

ordered character vector (dependencies first)

Shell script variable names for each library

Description

Shell script variable names for each library

Usage

.dt2_shell_var_map()

Version constraints for safe updates

Description

Defines the allowed version prefix for each library. Updates are only applied within this prefix. For example, jQuery is constrained to "3." so it will never auto-upgrade to 4.x.

Usage

.dt2_version_constraints()

Details

Rationale for each constraint:

jQuery "3."

DataTables 2.x requires jQuery 3.

PDFMake "0.2."

0.3.x has breaking changes and is not available on cdnjs.

Bootstrap "5."

DataTables BS5 styling requires Bootstrap 5.

Moment "2."

Major version pin for stability.

JSZip "3."

Major version pin for stability.

DataTables extensions do NOT have explicit constraints because their major version tracks DataTables core compatibility (managed by the DataTables project itself).

Value

Named character vector. Name = library name, value = version prefix. Only libraries with constraints are included (NA = no constraint).

Fetch the latest version of an npm package within a version prefix

Description

Queries the full package metadata from npm and extracts all version strings, then returns the highest version that starts with prefix.

Usage

.npm_latest_in_range(pkg, prefix)

Arguments

Value

version string or NA

Fetch latest version of an npm package

Description

Fetch latest version of an npm package

Usage

.npm_latest_version(pkg)

Arguments

Value

version string or NA

Replace a string in a file (first occurrence only)

Description

Replace a string in a file (first occurrence only)

Usage

.patch_file(path, old, new)

Arguments

Pretty-print the update check table

Description

Pretty-print the update check table

Usage

.print_update_table(result)

Compare two version strings (a > b?)

Description

Compare two version strings (a > b?)

Usage

.version_gt(a, b)

Create a DT2 DataTable widget

Description

The main function for creating interactive DataTables. Works standalone (R Markdown, Quarto, Viewer) and inside Shiny.

Styling is controlled directly via theme, striped, hover, compact, font_scale – or a CSS class string for full control.

DataTables configuration goes in options (1:1 mapping to the JavaScript API). The two concerns are cleanly separated.

Usage

dt2(
  data,
  theme = "default",
  striped = NULL,
  hover = NULL,
  compact = NULL,
  font_scale = NULL,
  style = NULL,
  class = NULL,
  button_class = NULL,
  responsive = TRUE,
  options = list(),
  extensions = NULL,
  width = "100%",
  height = NULL,
  elementId = NULL
)

Arguments

Value

An htmlwidget object.

Examples

# Just works — beautiful defaults
dt2(iris)

# Override style inline
dt2(iris, striped = FALSE)
dt2(iris, font_scale = 0.85, compact = FALSE)

# Theme presets
dt2(iris, theme = "minimal")
dt2(iris, theme = "compact")

# Reusable theme
my_theme <- dt2_theme("clean", compact = TRUE)
dt2(iris, theme = my_theme)

# Override a preset
dt2(iris, theme = "minimal", striped = TRUE)

# CSS class override (power users)
dt2(iris, class = "table table-bordered table-dark")

# DataTables options (separate from styling)
dt2(iris, options = list(pageLength = 5, searching = FALSE))

# Disable responsive (fixed-width columns)
dt2(iris, responsive = FALSE)

# Everything composes
dt2(mtcars,
    theme = "clean",
    compact = TRUE,
    options = list(pageLength = 25))

# Buttons
dt2(mtcars, options = list(
  buttons = list("copy", "csv", "excel"),
  layout = list(topEnd = "buttons")
))

# Custom button style
dt2(mtcars,
    button_class = "btn btn-sm btn-primary",
    options = list(
      buttons = list("copy", "csv", "excel"),
      layout = list(topEnd = "buttons")
    ))

DT2 Extension Registry

Description

Declarative registry of all DataTables extensions supported by DT2. Each extension specifies its version, JS/CSS files for core mode, and optional bridge files for Bootstrap 5 mode.

Users select extensions via dt2(extensions = c("Buttons", "Responsive")). Only the selected extensions (plus required dependencies) are loaded.

Usage

.dt2_extension_registry()

Bind a DataTables v2 server-side endpoint to a widget id

Description

Bind a DataTables v2 server-side endpoint to a widget id

Usage

dt2_bind_server(
  id,
  data,
  session = shiny::getDefaultReactiveDomain(),
  handler = NULL
)

Arguments

Value

No return value, called for side effects. Registers a Shiny observer on session that responds to client-side server-processing requests for the given widget id.

Configure DataTables Buttons and (optionally) move them to a custom container

Description

Configure DataTables Buttons and (optionally) move them to a custom container

Usage

dt2_buttons(
  options = list(),
  buttons = c("copyHtml5", "csvHtml5", "excelHtml5", "pdfHtml5", "print"),
  target = NULL
)

Arguments

Details

Requires the Buttons extension. For CSV/Excel/PDF you also need JSZip and pdfMake (incl. vfs_fonts).

Value

The modified options list.

Check for DataTables library updates

Description

Queries the npm registry to compare installed library versions against the latest available versions. Version constraints are enforced to prevent incompatible major version upgrades (e.g. jQuery 3.x will not jump to 4.x).

Usage

dt2_check_updates(quiet = FALSE)

Arguments

Value

A data.frame (invisibly) with columns: library, installed, latest, latest_ok, constraint, status.

Status values:

"ok"

Library is up to date.

"UPDATE"

A compatible update is available.

"PINNED"

A new major version exists, but is blocked by the version constraint. The library is up to date within its allowed range.

"error"

Lookup failed (check your internet connection).

Examples

dt2_check_updates()

# programmatic use
updates <- dt2_check_updates(quiet = TRUE)
updates[updates$status == "UPDATE", ]

Action button per row

Description

Action button per row

Usage

dt2_col_button(
  options = list(),
  col,
  label = "Action",
  input_id_prefix = "row_btn_"
)

Arguments

Value

Updated options.

Checkbox input per row

Description

Checkbox input per row

Usage

dt2_col_checkbox(
  options = list(),
  col,
  input_id_prefix = "row_chk_",
  value_col = NULL
)

Arguments

Value

Updated options.

Simple HTML template per column (replace {{VAL}})

Description

Simple HTML template per column (replace {{VAL}})

Usage

dt2_col_template(options = list(), col, template)

Arguments

Value

Updated options.

Column align (Bootstrap 5 classes)

Description

Column align (Bootstrap 5 classes)

Usage

dt2_cols_align(options = list(), cols, align = c("left", "center", "right"))

Arguments

Value

Updated options.

Escape/unescape columns content

Description

Escape/unescape columns content

Usage

dt2_cols_escape(options = list(), cols, escape = TRUE)

Arguments

Value

Updated options.

Hide columns

Description

Hide columns

Usage

dt2_cols_hide(options = list(), cols)

Arguments

Value

Updated options.

Allow raw HTML rendering via columns.render

Description

Mark columns to render raw HTML using a JS render function.

Usage

dt2_cols_html(options = list(), cols, js_render)

Arguments

Value

Updated options.

Attach a raw JS render function to columns

Description

Provide a custom JS renderer for one or more columns. Use this when you need fine control over columns.render, including returning different outputs based on type (display/sort/filter/type).

Usage

dt2_cols_render_js(options = list(), col_specs, js_render)

Arguments

Value

Modified options.

See Also

https://datatables.net/reference/option/columns.render

Orthogonal render (display/sort/filter/type) per column

Description

Supply different renderers for each orthogonal data request. Pass an object with keys display, sort, filter, type (all optional). Each value must be a JS function.

Usage

dt2_cols_render_orthogonal(
  options = list(),
  col_specs,
  display = NULL,
  sort = NULL,
  filter = NULL,
  type = NULL
)

Arguments

Value

Modified options.

Examples

opts <- list(columns = names(iris))
opts <- dt2_cols_render_orthogonal(
  opts, "Sepal.Length",
  display = htmlwidgets::JS("function(d,t,row,meta){ return d + ' cm'; }"),
  sort    = htmlwidgets::JS("function(d,t,row,meta){ return parseFloat(d); }")
)

Column widths (CSS)

Description

Column widths (CSS)

Usage

dt2_cols_width(options = list(), map_named)

Arguments

Value

Updated options.

Build htmlwidgets dependencies for DT2

Description

Constructs the dependency list dynamically based on the requested extensions. Only loads CSS/JS for selected extensions, keeping the page lightweight.

Usage

dt2_deps(
  bs = c("bootstrap5", "core"),
  include_bs = TRUE,
  extensions = character()
)

Arguments

Details

All version numbers are read from .dt2_lib_versions() (defined in dt2_check_updates.R) so there is a single source of truth for versions.

Value

List of htmlDependency() objects in correct load order.

Redraw the table (proxy)

Description

Redraw the table (proxy)

Usage

dt2_draw(proxy)

Arguments

Value

The proxy object, returned invisibly.

List available DataTables extensions

Description

List available DataTables extensions

Usage

dt2_extensions()

Value

A data.frame with columns name, version, dir.

Examples

dt2_extensions()

Format date/time columns (DataTables renderer: datetime)

Description

Use DataTables' built-in DataTable.render.datetime to transform date/time strings for display (and preserve sortability).

Usage

dt2_format_datetime(
  options = list(),
  col_specs,
  from = NULL,
  to = "DD/MM/YYYY",
  locale = NULL,
  def = NULL
)

Arguments

Value

Modified options.

Examples

opts <- list(columns = c("when", "val"))
opts <- dt2_format_datetime(opts, "when", from = "YYYY-MM-DD",
                            to = "DD/MM/YYYY", locale = "pt-BR")

Format numeric columns (DataTables renderer: number)

Description

Add a number renderer to one or more columns using DataTables' built-in DataTable.render.number.

Usage

dt2_format_number(
  options = list(),
  col_specs,
  thousands = NULL,
  decimal = NULL,
  digits = 0,
  prefix = "",
  prefix_right = ""
)

Arguments

Value

Modified options.

Examples

opts <- list(columns = names(iris))
opts <- dt2_format_number(opts, "Sepal.Length", thousands = ".", decimal = ",",
                          digits = 2, prefix = "", prefix_right = "")

Abbreviate large numbers with fixed decimals (k / M / B)

Description

Adds a columns.render function that displays numbers as 1.2k, 3.4M, etc. This renderer lets you control the number of decimal places via digits. Use this when you want a fixed, compact style independent of locale rules.

Usage

dt2_format_number_abbrev(
  options = list(),
  col_specs,
  digits = 1,
  locale = NULL
)

Arguments

Value

The modified options list.

Examples

opts <- list(columns = names(mtcars))
opts <- dt2_format_number_abbrev(opts, c("hp","qsec"), digits = 1, locale = "pt-BR")

Format a date/time using DataTables' datetime renderer, with locale

Description

Format a date/time using DataTables' datetime renderer, with locale

Usage

dt2_format_time_format(
  options = list(),
  col_specs,
  from = NULL,
  to = "L",
  locale = "pt-br"
)

Arguments

Value

Modified options.

Relative time using moment.fromNow(), with locale

Description

Relative time using moment.fromNow(), with locale

Usage

dt2_format_time_relative(options = list(), col_specs, locale = "pt-br")

Arguments

Value

The modified options list with an updated columnDefs entry.

Language helper (either list or JSON url)

Description

Language helper (either list or JSON url)

Usage

dt2_language(options = list(), lang_list = NULL, lang_url = NULL)

Arguments

Value

Updated options.

Length menu helper

Description

Configures the entries-per-page dropdown.

Usage

dt2_length_menu(options = list(), values = c(10, 25, 50, -1), labels = NULL)

Arguments

Value

Updated options.

Examples

opts <- dt2_length_menu(values = c(5, 10, 25, -1))
dt2(iris, options = opts)

opts <- dt2_length_menu(values = c(10, 50, 100), labels = c("10", "50", "100"))
dt2(iris, options = opts)

Define initial ordering (option order)

Description

Define initial ordering (option order)

Usage

dt2_order(options = list(), ...)

Arguments

Value

Updated options.

Shiny output for DT2

Description

Place a DT2 table in a Shiny UI.

Usage

dt2_output(outputId, width = "100%", height = "auto")

Arguments

Value

An htmlwidgets Shiny output (HTML container) suitable for inclusion in a Shiny UI definition.

Create a proxy for a DT2 table

Description

Create a proxy for a DT2 table

Usage

dt2_proxy(id, session = shiny::getDefaultReactiveDomain())

Arguments

Value

A "DT2Proxy" object.

Order the table (proxy)

Description

Order the table (proxy)

Usage

dt2_proxy_order(proxy, ..., columns = NULL)

Arguments

Value

The proxy object, returned invisibly.

Page navigation (proxy)

Description

Page navigation (proxy)

Usage

dt2_proxy_page(
  proxy,
  page = c("first", "previous", "next", "last", "number"),
  number = NULL
)

Arguments

Value

The proxy, invisibly.

Global search (proxy)

Description

Global search (proxy)

Usage

dt2_proxy_search(
  proxy,
  value,
  regex = FALSE,
  smart = TRUE,
  caseInsensitive = TRUE
)

Arguments

Value

The proxy, invisibly.

Register a named JS renderer

Description

Register a named JS renderer

Usage

dt2_register_renderer(name, js)

Arguments

Value

Invisibly, the name.

Replace all data in the table (proxy)

Description

Replace all data in the table (proxy)

Usage

dt2_replace_data(proxy, data)

Arguments

Value

The proxy object, returned invisibly.

Set global search (option search)

Description

Set global search (option search)

Usage

dt2_search_global(
  options = list(),
  value,
  regex = FALSE,
  smart = TRUE,
  caseInsensitive = TRUE
)

Arguments

Value

Updated options.

Select rows (proxy; Select extension)

Description

Select rows (proxy; Select extension)

Usage

dt2_select_rows(proxy, indexes, reset = TRUE)

Arguments

Value

The proxy object, returned invisibly.

Default server-side handler (filter/order/page)

Description

Default server-side handler (filter/order/page)

Usage

dt2_ssp_handler(names)

Arguments

Value

function(data, req) -> list(draw, recordsTotal, recordsFiltered, data)

Access the current state snapshot of a DT2 table

Description

Returns a list with reason, order, search, page, selected, state reflecting the current client-side table state.

Usage

dt2_state(input, id)

Arguments

Value

A list with the current table state.

Create a reusable DT2 theme

Description

Creates a theme object that can be passed to dt2() via the theme parameter. Useful when you want the same look across many tables.

For quick one-off styling, you can also pass arguments directly to dt2() (e.g., dt2(iris, striped = FALSE)).

Usage

dt2_theme(
  preset = "default",
  striped = NULL,
  hover = NULL,
  compact = NULL,
  font_scale = NULL,
  style = NULL,
  button_class = NULL
)

Arguments

Value

A dt2_theme object (a named list).

Examples

# Create and reuse
my_theme <- dt2_theme("clean", compact = TRUE)
dt2(iris, theme = my_theme)
dt2(mtcars, theme = my_theme)

# Custom button style
dt2_theme("default", button_class = "btn btn-sm btn-primary")

# Presets
dt2_theme("minimal")
dt2_theme("compact")

Update DataTables JS/CSS libraries (developer tool)

Description

Checks for updates (respecting version constraints), patches version numbers in the source files, and optionally runs tools/get-dt2-libs.sh to download the new files.

Usage

dt2_update_libs(pkg_dir = ".", download = TRUE, dry_run = FALSE)

Arguments

Details

This function only works from the package source tree (i.e. during development). It will refuse to run from an installed package.

The workflow is:

1. Query npm for the latest compatible version of every library.

2. Patch tools/get-dt2-libs.sh (version variables).

3. Patch R/dt2_extensions.R (extension registry).

4. Patch R/dt2_check_updates.R (core lib versions).

5. Patch R/dt2_deps.R (DataTables core version).

6. Run bash tools/get-dt2-libs.sh to download the files.

Version constraints prevent incompatible upgrades:

• jQuery is pinned to 3.x (DataTables 2 requires jQuery 3).

• pdfmake is pinned to 0.2.x (0.3.x has breaking changes and is not available on cdnjs).

• Bootstrap is pinned to 5.x.

Libraries marked as "PINNED" are skipped. Only "UPDATE" items are applied.

Value

Invisibly, a data.frame with the update results.

Examples

## Not run: 
# Developer-only tool: requires the DT2 package source tree
# (DESCRIPTION, tools/get-dt2-libs.sh, R/dt2_extensions.R, ...).
# It cannot run from an installed package, so it is not executable
# in CRAN check or from a regular user session.

# from the DT2 source root:
dt2_update_libs()

# preview changes without modifying anything:
dt2_update_libs(dry_run = TRUE)

## End(Not run)

Enable Buttons (extension) and define buttons

Description

Uses the modern DataTables 2.x layout API (not the deprecated dom).

Usage

dt2_use_buttons(
  options = list(),
  buttons = c("copy", "csv", "excel", "print"),
  position = "topEnd",
  button_class = NULL
)

Arguments

Value

Updated options.

Use a named JS renderer on columns

Description

Use a named JS renderer on columns

Usage

dt2_use_renderer(options = list(), col_specs, name)

Arguments

Value

Modified options.

Observe DataTables events published by dt2.js

Description

Listen for table events (init, draw, order, search, page, select, deselect).

Usage

observe_dt2_events(input, id, handler)

Arguments

Value

No return value, called for side effects. Sets up a Shiny observer that calls handler whenever the table emits an event.

Shiny render function for DT2

Description

Render a DT2 table in a Shiny server function.

Usage

render_dt2(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A Shiny render function (closure produced by htmlwidgets::shinyRenderWidget()) that emits a DT2 widget.