The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Collaborative Report Management with tm_report_manager

This vignette demonstrates how to add collaborative report management to a teal application using the tm_report_manager module from uteals.

Overview

The tm_report_manager module extends teal.reporter with persistent, multi-user report management. It allows users to:

Library Calls

library(uteals)
library(teal)
library(teal.data)

Quick Start

Add tm_report_manager() to your teal::modules() call:

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris),
  modules = teal::modules(
    teal::example_module(),
    tm_report_manager()
  )
)

if (interactive()) {
  shinyApp(app$ui, app$server)
}

Reports are stored in a reports/ folder relative to the working directory by default.

Configuration

tm_report_manager() accepts two arguments:

Argument Default Description
reports_path "reports" Absolute or relative path where reports are stored
auto_save TRUE Whether to auto-save the active report on every card change 
tm_report_manager(
  reports_path = "/shared/network/drive/reports",
  auto_save = TRUE
)

Use an absolute path pointing to a shared network location to enable multi-user collaboration.

How It Works

Creating a Report

When a user adds the first card to the teal.reporter previewer, a modal dialog prompts them to name the new report. The report is then saved to reports_path and locked for that user.

A report directory contains:

reports/
└── My Report/
    ├── Report.json       # Report cards (teal.reporter format)
    ├── code.rds          # R code for each card (used for rebuild)
    ├── .lockfile.rds     # Username of the locking user
    ├── .creator.rds      # Username of the report creator
    └── .rebuild_time.rds # Timestamp of last rebuild

Locking

Each report can be locked by one user at a time. The lock prevents other users from saving or deleting the report. The report table shows the lock status:

Locks are automatically released when the Shiny session ends.

Auto-Save

With auto_save = TRUE (the default), any change to the active report’s cards triggers an automatic save. A progress indicator is shown during the save.

If the active report is in read-only mode, a warning notification is shown instead of saving.

Loading a Report

Click the load/eye icon next to a report in the table:

Rebuilding a Report

The rebuild action re-evaluates the R code stored for each card against the current data environment. This is useful when the underlying data has changed and you want to refresh the report output without manually re-adding cards.

Click the refresh icon next to any report to trigger a rebuild.

Merging Reports

Click Merge reports (only enabled when you have an active report) to combine cards from two or more reports into a single new report. Only reports that have saved content (a Report.json file) appear as merge candidates.

Complete Example

app <- teal::init(
  data = teal.data::teal_data(
    ADSL = teal.data::rADSL,
    code = "ADSL <- teal.data::rADSL"
  ),
  modules = teal::modules(
    teal::example_module(label = "Summary"),
    tm_report_manager(
      reports_path = "reports",
      auto_save = TRUE
    )
  )
)

if (interactive()) {
  shinyApp(app$ui, app$server)
}

Permissions Summary

The table below summarises which actions are available depending on the report state:

Action Active report Your locked report Others’ locked report Unlocked report
Edit title Yes Yes No No
Delete No Yes No Yes
Rebuild Yes Yes Yes Yes
Load / View Already active Full access Read-only Read-only
Release lock Yes Yes No N/A
Merge Yes* Yes* Yes* Yes*

* Merge requires reports to have saved content (cards).

Further Reading

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.