Title:	Interactive File Import and Export Blocks
Version:	0.1.0
Description:	Extends 'blockr.core' with interactive blocks for reading and writing data files. Supports CSV, Excel, Parquet, RDS, and other formats through a graphical interface without writing code directly. Includes file browser integration and configurable import/export options.
URL:	https://bristolmyerssquibb.github.io/blockr.io/
BugReports:	https://github.com/BristolMyersSquibb/blockr.io/issues
License:	GPL (≥ 3)
Depends:	R (≥ 4.1.0)
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
VignetteBuilder:	knitr
Imports:	blockr.core (≥ 0.1.1), readxl, shiny, readr, shinyFiles, rio, arrow, bslib, rappdirs, shinyjs, writexl, zip
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Config/testthat/parallel:	true
NeedsCompilation:	no
Packaged:	2025-12-21 14:00:27 UTC; christophsax
Author:	Christoph Sax [aut, cre], Nicolas Bennett [aut], David Granjon [aut], Mike Page [aut], Bristol Myers Squibb [fnd]
Maintainer:	Christoph Sax <christoph@cynkra.com>
Repository:	CRAN
Date/Publication:	2026-01-07 08:00:08 UTC

blockr.io: Interactive File Import and Export Blocks

Description

Extends 'blockr.core' with interactive blocks for reading and writing data files. Supports CSV, Excel, Parquet, RDS, and other formats through a graphical interface without writing code directly. Includes file browser integration and configurable import/export options.

Author(s)

Maintainer: Christoph Sax christoph@cynkra.com (ORCID)

Authors:

• Nicolas Bennett nicolas@cynkra.com

• David Granjon david@cynkra.com

• Mike Page mike@cynkra.com

Other contributors:

• Bristol Myers Squibb [funder]

See Also

Useful links:

• https://bristolmyerssquibb.github.io/blockr.io/

• Report bugs at https://github.com/BristolMyersSquibb/blockr.io/issues

Get blockr option with fallback

Description

Get blockr option with fallback

Usage

blockr_option(name, default = NULL)

CSS Utilities for blockr.io Blocks

Description

This file provides centralized CSS functions for consistent block styling. All custom classes use the ⁠.block-⁠ prefix to distinguish them from framework classes (Bootstrap, Shiny, etc.) and prevent naming conflicts.

Details

Required for all blocks:

• css_responsive_grid() - Base grid layout and block styling (REQUIRED)

Common optional utilities:

• css_single_column() - Force single-column layout (common)

• css_advanced_toggle() - Collapsible sections with toggle (optional)

• css_inline_checkbox() - Checkbox/label styling for inline layouts (optional)

Usage in block UI:

ui = function(id) {
  tagList(
    css_responsive_grid(),        # Always include first
    css_single_column("myblock"), # If single column layout needed
    css_inline_checkbox(),        # If using inline checkboxes
    # ... block-specific CSS with tags$style(HTML(...)) ...
    # ... block HTML structure ...
  )
}

Block-specific styling (unique to one block) should use tags$style(HTML(...)) directly in the block file, not added here. Only add CSS here if it's reused by 2+ blocks.

Detect file category for UI adaptation

Description

Categorizes files by extension into broad categories that determine which UI options to show (csv/excel/arrow/other).

Usage

detect_file_category(path)

Arguments

Value

Character. One of: "csv", "excel", "arrow", "other"

Extract names for variadic block arguments

Description

Helper function for variadic blocks. Processes ...args names to handle numeric indices vs named arguments.

Usage

dot_args_names(x)

Arguments

Value

Character vector of names, or NULL if all numeric

Download URL to temporary file

Description

Downloads a file from a URL to a temporary location. Extracts file extension from URL if available to help with format detection.

Usage

download_url_to_temp(url)

Arguments

Value

Path to temporary file containing downloaded data.

Generate filename for write operations

Description

Generate filename for write operations

Usage

generate_filename(filename = "", timestamp = Sys.time())

Arguments

Value

Character. Base filename without extension

Get list of file extensions supported by rio

Description

Returns a comprehensive list of file formats that can be handled by rio::import(). Used for file browser accept parameter and format validation.

Usage

get_rio_extensions()

Value

Character vector of file extensions (without dots)

Check if object is a single string

Description

Check if object is a single string

Usage

is_string(x)

Validate URL format

Description

Validate URL format

Usage

is_valid_url(url)

Unified file reading block

Description

A single block for reading files in various formats with smart UI that adapts based on detected file type. Supports "From Browser" (upload) and "From Server" (browse) modes with persistent storage for uploaded files.

Usage

new_read_block(
  path = character(),
  source = "upload",
  combine = "auto",
  args = list(),
  ...
)

Arguments

Details

File Handling Modes

The block supports three modes:

From Browser mode (upload):

• User uploads files from their computer via the browser

• Files are copied to persistent storage directory (upload_path)

• State stores permanent file paths

• Works across R sessions with state restoration

From Server mode (path):

• User picks files that already exist on the server

• No file copying, reads directly from original location

• State stores selected file paths

• When running locally, this is your computer's file system

URL mode:

• User provides a URL to a data file

• File is downloaded to temporary location each time

• Always fetches fresh data from URL

• State stores the URL (not file path)

Smart Adaptive UI

After file selection, the UI detects file type and shows relevant options:

• CSV/TSV: Delimiter, quote character, encoding options

• Excel: Sheet selection, cell range

• Other formats: Minimal or no options (handled automatically)

Multi-file Support

When multiple files are selected:

• "auto": Attempts rbind, falls back to first file if incompatible

• "rbind": Row-binds files (requires same columns)

• "cbind": Column-binds files (requires same row count)

• "first": Uses only the first file

Value

A blockr data block that reads file(s) and returns a data.frame.

Configuration

The following settings are retrieved from options and not stored in block state:

• volumes: File browser mount points. Set via options(blockr.volumes = c(name = "path")) or environment variable BLOCKR_VOLUMES. Default: c(temp = tempdir())

• upload_path: Directory for persistent file storage. Set via options(blockr.upload_path = "/path") or environment variable BLOCKR_UPLOAD_PATH. Default: rappdirs::user_data_dir("blockr")

Examples

# Create a read block for a CSV file
csv_file <- tempfile(fileext = ".csv")
write.csv(mtcars[1:5, ], csv_file, row.names = FALSE)
block <- new_read_block(path = csv_file)
block

# With custom CSV parameters
block <- new_read_block(
  path = csv_file,
  args = list(n_max = 3)
)

if (interactive()) {
  # Launch interactive app
  serve(new_read_block())
}

Unified file writing block

Description

A variadic block for writing dataframes to files in various formats. Accepts multiple input dataframes and handles single files, multi-sheet Excel, or ZIP archives depending on format and number of inputs.

Usage

new_write_block(
  directory = "",
  filename = "",
  format = "csv",
  mode = "download",
  auto_write = FALSE,
  args = list(),
  ...
)

Arguments

Details

Variadic Inputs

This block accepts multiple dataframe inputs (1 or more) similar to bind_rows_block. Inputs can be numbered ("1", "2", "3") or named ("sales_data", "inventory"). Input names are used for sheet names (Excel) or filenames (multi-file ZIP).

File Output Behavior

Single input:

• Writes single file in specified format

• Filename: ⁠{filename}.{ext}⁠ or ⁠data_{timestamp}.{ext}⁠

Multiple inputs + Excel:

• Single Excel file with multiple sheets

• Sheet names derived from input names

Multiple inputs + CSV/Arrow:

• Single ZIP file containing individual files

• Each file named from input names

Filename Behavior

Fixed filename (filename = "output"):

• Reproducible path: always writes to ⁠{directory}/output.{ext}⁠

• Overwrites file on every upstream data change

• Ideal for automated pipelines

Auto-timestamped (filename = ""):

• Unique files: ⁠{directory}/data_YYYYMMDD_HHMMSS.{ext}⁠

• Preserves history, prevents accidental overwrites

• Safe default behavior

Mode: To Browser vs To Server

To Browser mode (download):

• Exports files to your computer

• Triggers a download to your browser's download folder

• Useful for exporting results

To Server mode (browse):

• Saves files directly on the server

• User selects directory with file browser

• Files persist on server

• When running locally, this is your computer's file system

Value

A blockr transform block that writes dataframes to files

Examples

# Create a write block for CSV output
block <- new_write_block(
  directory = tempdir(),
  filename = "output",
  format = "csv"
)
block

# Write block for Excel with auto-timestamp
block <- new_write_block(
  directory = tempdir(),
  filename = "",
  format = "excel"
)

if (interactive()) {
  # Launch interactive app
  serve(new_write_block())
}

Create Arrow file reading expression

Description

Create Arrow file reading expression

Usage

read_expr_arrow(path, ...)

Arguments

Value

Expression calling arrow::read_parquet, arrow::read_feather, or arrow::read_ipc_file

Create CSV/TSV/delimited file reading expression

Description

Create CSV/TSV/delimited file reading expression

Usage

read_expr_csv(path, ...)

Arguments

Value

Expression calling readr::read_csv, readr::read_tsv, or readr::read_delim

Create Excel file reading expression

Description

Create Excel file reading expression

Usage

read_expr_excel(path, ...)

Arguments

Value

Expression calling readxl::read_excel

Create rio import expression

Description

Create rio import expression

Usage

read_expr_rio(path, ...)

Arguments

Value

Expression calling rio::import

Create expression for a single file

Description

Create expression for a single file

Usage

read_expr_single(path, file_type, ...)

Arguments

Value

A language object (expression)

Set names helper (base R doesn't export this in older versions)

Description

Set names helper (base R doesn't export this in older versions)

Usage

set_names(x, nm)

Build expression to write data to Arrow format (Parquet or Feather)

Description

Build expression to write data to Arrow format (Parquet or Feather)

Usage

write_expr_arrow(data_names, path, format = "parquet")

Arguments

Value

A language object (expression) that writes Arrow file(s)

Build expression to write data to CSV file(s)

Description

Build expression to write data to CSV file(s)

Usage

write_expr_csv(data_names, path, args = list())

Arguments

Value

A language object (expression) that writes CSV file(s)

Build expression to write data to Excel file with multiple sheets

Description

Build expression to write data to Excel file with multiple sheets

Usage

write_expr_excel(data_names, path)

Arguments

Value

A language object (expression) that writes Excel file