% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/export_with_style.R
\name{export_with_style}
\alias{export_with_style}
\title{Export Data Frame With Style}
\usage{
export_with_style(
  data_frame,
  titles = .qol_options[["titles"]],
  footnotes = .qol_options[["footnotes"]],
  var_labels = .qol_options[["var_labels"]],
  workbook = NULL,
  style = .qol_options[["excel_style"]],
  column_align = NULL,
  output = .qol_options[["output"]],
  print = .qol_options[["print"]],
  monitor = .qol_options[["monitor"]]
)
}
\arguments{
\item{data_frame}{A data frame to print.}

\item{titles}{Specify one or more table titles.}

\item{footnotes}{Specify one or more table footnotes.}

\item{var_labels}{A list in which is specified which label should be printed for
which variable instead of the variable name.}

\item{workbook}{Insert a previously created workbook to expand the sheets instead of
creating a new file.}

\item{style}{A list of options can be passed to control the appearance of 'Excel' outputs.
Styles can be created with \code{\link[=excel_output_style]{excel_output_style()}}.}

\item{column_align}{Individually align the data frame columns in the final 'Excel' output.}

\item{output}{The following output formats are available: excel and excel_nostyle.}

\item{print}{TRUE by default. If TRUE prints the output, if FALSE doesn't print anything. Can be used
if one only wants to catch the output workbook.}

\item{monitor}{FALSE by default. If TRUE outputs two charts to visualize the functions time consumption.}
}
\value{
Returns a list with the data table containing the results for the table, the formatted
'Excel' workbook and the meta information needed for styling the final table.
}
\description{
\code{\link[=export_with_style]{export_with_style()}} prints a data frame as an individually styled 'Excel' table. Titles,
footnotes and labels for variable names can optionally be added.
}
\details{
\code{\link[=export_with_style]{export_with_style()}} is based on the 'SAS' procedure Proc Print, which outputs the data frame
as is into a styled table.
}
\examples{
# Example data frame
my_data <- dummy_data(100)
set_style_options(background_color = "")

# Define style
set_style_options(column_widths = c(2, 15, 15, 15, 9))

# Define titles and footnotes. If you want to add hyperlinks you can do so by
# adding "link:" followed by the hyperlink to the main text. Linking to another
# cell works with "cell:". To link to a file use "file:" an pass the full file
# path afterwards.
set_titles("This is title number 1",
           "This is title number 2 link: https://cran.r-project.org/",
           "This is title number 3 cell: W22",
           "This is title number 4 file: C:/MyFolder/MyFile.txt")

set_footnotes("This is footnote number 1",
              "This is footnote number 2 file: C:/MyFolder/MyFile.txt",
              "This is footnote number 3 cell: W22",
              "This is footnote number 4 link: https://cran.r-project.org/")

# Print styled data frame
my_data |> export_with_style()

# Retrieve formatted workbook, original table and meta information for further usage
export_list <- my_data |> export_with_style()

# To save a table as xlsx file you have to set the path and filename in the
# style element
# Example files paths
table_file <- tempfile(fileext = ".xlsx")

# Note: Normally you would directly input the path ("C:/MyPath/") and
#       name ("MyFile.xlsx").
#       With the set_style_options you can also set a table style globally.
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> export_with_style()

# In case you have a good amount of tables, you want to combine in a single
# workbook, you can also catch the outputs and combine them afterwards in one go.
set_style_options(sheet_name = "sheet1")
tab1 <- my_data |> export_with_style(print = FALSE)

set_titles(NULL)
set_style_options(sheet_name = "sheet2")
tab2 <- my_data |> export_with_style(print = FALSE)

set_footnotes(NULL)
set_style_options(sheet_name = "sheet3")
tab3 <- my_data |> export_with_style(print = FALSE, output = "excel_nostyle")

# Every of the above tabs is a list, which contains the data table, an unstyled
# workbook and the meta information needed for the individual styling. These tabs
# can be input into the following function, which reads the meta information,
# styles each table individually and combines them as separate sheets into a
# single workbook.
combine_into_workbook(tab1, tab2, tab3)
combine_into_workbook(tab1, tab2, tab3, file = table_file)

# Manual cleanup for example
unlink(table_file)

# Global options are permanently active until the current R session is closed.
# There are also functions to reset the values manually.
reset_style_options()
reset_qol_options()
close_file()

set_print(TRUE)
set_style_options(background_color = "FFFFFF")

}
\seealso{
Creating a custom table style: \code{\link[=excel_output_style]{excel_output_style()}}, \code{\link[=modify_output_style]{modify_output_style()}},
\code{\link[=number_format_style]{number_format_style()}}, \code{\link[=modify_number_formats]{modify_number_formats()}}.

Global style options: \code{\link[=set_style_options]{set_style_options()}}, \code{\link[=set_labels]{set_labels()}}.

Other global options: \code{\link[=set_titles]{set_titles()}}, \code{\link[=set_footnotes]{set_footnotes()}}, \code{\link[=set_print]{set_print()}}, \code{\link[=set_monitor]{set_monitor()}},
\code{\link[=set_na.rm]{set_na.rm()}}, \code{\link[=set_print]{set_print()}}, \code{\link[=set_print_miss]{set_print_miss()}}, \code{\link[=set_output]{set_output()}}.

Combine Excel workbooks: \code{\link[=combine_into_workbook]{combine_into_workbook()}}.

Functions that can handle styles: \code{\link[=frequencies]{frequencies()}}, \code{\link[=crosstabs]{crosstabs()}}, \code{\link[=any_table]{any_table()}}.
}
