diff --git a/README.Rmd b/README.Rmd index 0055d05..f74db39 100644 --- a/README.Rmd +++ b/README.Rmd @@ -16,11 +16,14 @@ knitr::opts_chunk$set( # openxlsx2Extras -[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + -The goal of openxlsx2Extras is to extend the functionality of the {openxlsx2} R package. +The goal of openxlsx2Extras is to extend the functionality of the [{openxlsx2} R package](https://github.com/JanMarvin/openxlsx2). + +This package is *very* early stages so expect things to change and break as I learn more about {openxlsx2} and figure out the appropriate design for this package. ## Installation @@ -32,20 +35,63 @@ pak::pkg_install("elipousson/openxlsx2Extras") ## Example -This is a basic example which shows how to use `wb_save_ext()` to set a filename based on the workbook title: - ```{r} library(openxlsx2) library(openxlsx2Extras) +``` -withr::with_tempdir({ - wb_workbook( +As of December 2024, the main types of functions in `{openxlsx2Extras}` include: + +- Wrapper functions for existing `{openxlsx2}` functions that add some extra features, e.g. `wb_save_ext()` wraps `openxlsx2::wb_save()` +- Convenience functions for multiple `{openxlsx2}` for convenience and more concise code, e.g. `openxlsx2Extras::wb_new_workbook()` combines `openxlsx2::wb_workbook()` and `openxlsx2::wb_add_worksheet()` +- Other functions that support Markdown formatted text (`wb_add_marquee_text()`), lists of workbooks (`map_wb()`), lists of data frames (`wb_as_df_list()`), and coercion of more kinds of objects into spreadsheet-friendly formats (`prep_wb_data()`) + +For example, `wb_save_ext()` allows users to set a filename based on the workbook title: + +```{r} +wb <- wb_workbook( title = "Title used for output file" - ) |> - wb_add_worksheet() |> - wb_save_ext() + ) + +wb <- wb$add_worksheet() +withr::with_tempdir({ + wb_save_ext(wb) fs::dir_ls() }) ``` +`wb_new_workbook()` supports creating multiple worksheets in a single function call (recycling additional arguments like `tab_color` to match the length of `sheet_names`): + +```{r} +wb_new_workbook( + title = "Workbook created with wb_new_workbook", + sheet_names = c("First sheet", "Second sheet"), + tab_color = c(wb_color("orange"), wb_color("yellow")) +) +``` + +## Related Projects + +Packages extending [openxlsx](https://github.com/ycphs/openxlsx) + +- `tablexlsx` [ddotta/tablexlsx](https://github.com/ddotta/tablexlsx) + +- `a11ytables` [co-analysis/a11ytables](https://github.com/co-analysis/a11ytables){.uri}: generate best-practice stats spreadsheets for publication + +- `gtopenxlsx` [yannsay/gtopenxlsx](https://github.com/yannsay/gtopenxlsx): tables to xlsx format through openxlsx + +Packages extending [openxlsx2](https://github.com/JanMarvin/openxlsx2) + +- `flexlsx`: [pteridin/flexlsx](https://github.com/pteridin/flexlsx) add flextables to Excel files + +- `a11ytables2`: [matt-dray/a11ytables2](https://github.com/matt-dray/a11ytables2): generate best-practice stats spreadsheets for publication + +Packages extending [readxl](https://readxl.tidyverse.org) + +- `forgts` [luisDVA/forgts](https://github.com/luisDVA/forgts){.uri}: reads a spreadsheet and its formatting information to produce gt tables with the same cell and text formatting as the input file. + +Packages for working with Microsoft Office files + +- `officer` [davidgohel/officer](https://github.com/davidgohel/officer/){.uri}: office documents from R +- `officerExtras` [elipousson/officerExtras](https://github.com/elipousson/officerExtras){.uri}: A R package with {officer} helper functions. diff --git a/README.md b/README.md index ca1e83c..ac47a39 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,15 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + The goal of openxlsx2Extras is to extend the functionality of the -{openxlsx2} R package. +[{openxlsx2} R package](https://github.com/JanMarvin/openxlsx2). + +This package is *very* early stages so expect things to change and break +as I learn more about {openxlsx2} and figure out the appropriate design +for this package. ## Installation @@ -24,21 +29,92 @@ pak::pkg_install("elipousson/openxlsx2Extras") ## Example -This is a basic example which shows how to use `wb_save_ext()` to set a -filename based on the workbook title: - ``` r library(openxlsx2) library(openxlsx2Extras) +``` -withr::with_tempdir({ - wb_workbook( +As of December 2024, the main types of functions in `{openxlsx2Extras}` +include: + +- Wrapper functions for existing `{openxlsx2}` functions that add some + extra features, e.g. `wb_save_ext()` wraps `openxlsx2::wb_save()` +- Convenience functions for multiple `{openxlsx2}` for convenience and + more concise code, e.g. `openxlsx2Extras::wb_new_workbook()` combines + `openxlsx2::wb_workbook()` and `openxlsx2::wb_add_worksheet()` +- Other functions that support Markdown formatted text + (`wb_add_marquee_text()`), lists of workbooks (`map_wb()`), lists of + data frames (`wb_as_df_list()`), and coercion of more kinds of objects + into spreadsheet-friendly formats (`prep_wb_data()`) + +For example, `wb_save_ext()` allows users to set a filename based on the +workbook title: + +``` r +wb <- wb_workbook( title = "Title used for output file" - ) |> - wb_add_worksheet() |> - wb_save_ext() + ) +wb <- wb$add_worksheet() + +withr::with_tempdir({ + wb_save_ext(wb) fs::dir_ls() }) #> Title used for output file.xlsx ``` + +`wb_new_workbook()` supports creating multiple worksheets in a single +function call (recycling additional arguments like `tab_color` to match +the length of `sheet_names`): + +``` r +wb_new_workbook( + title = "Workbook created with wb_new_workbook", + sheet_names = c("First sheet", "Second sheet"), + tab_color = c(wb_color("orange"), wb_color("yellow")) +) +#> A Workbook object. +#> +#> Worksheets: +#> Sheets: First sheet, Second sheet +#> Write order: 1, 2 +``` + +## Related Projects + +Packages extending [openxlsx](https://github.com/ycphs/openxlsx) + +- `tablexlsx` [ddotta/tablexlsx](https://github.com/ddotta/tablexlsx) + +- `a11ytables` co-analysis/a11ytables: generate best-practice stats + spreadsheets for publication + +- `gtopenxlsx` + [yannsay/gtopenxlsx](https://github.com/yannsay/gtopenxlsx): tables to + xlsx format through openxlsx + +Packages extending [openxlsx2](https://github.com/JanMarvin/openxlsx2) + +- `flexlsx`: [pteridin/flexlsx](https://github.com/pteridin/flexlsx) add + flextables to Excel files + +- `a11ytables2`: + [matt-dray/a11ytables2](https://github.com/matt-dray/a11ytables2): + generate best-practice stats spreadsheets for publication + +Packages extending [readxl](https://readxl.tidyverse.org) + +- `forgts` luisDVA/forgts: reads a spreadsheet and its formatting + information to produce gt tables with the same cell and text + formatting as the input file. + +Packages for working with Microsoft Office files + +- `officer` davidgohel/officer: office documents from R +- `officerExtras` elipousson/officerExtras: A R package with {officer} + helper functions.