---
title: "Printing (HTML)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Printing (HTML)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Basic printing

If a tabulation function is called from the top level, it should print out its table(s) on its own. 

As usual, first, let's start up the package and pick a survey to analyze:

```{r, results='asis'}
library(surveytable)
set_survey(namcs2019sv)
```

Now, when a tabulation function is called from the top level, it prints. You don't need to do anything extra.

```{r, results='asis'}
tab("AGER")
```

If a tabulation function is called not from the top level, such as from within a loop or another function, you do need to call `print()` explicitly for it to print. For example:

```{r, results='asis'}
for (vr in c("AGER", "SEX")) {
  print( tab_subset(vr, "MAJOR", "Preventive care") )
}
```

# Create HTML or PDF tables

Using a Quarto document, you can create tables in many different formats, such as HTML or PDF. Here is a straightforward example of what a Quarto document might look like: 

<!-- https://yihui.org/knitr/faq/ --> 

````{verbatim}
---
title: "My tables"
author: "Me"
format: html
---

# Welcome 

As usual, first, let's start up the package and pick a survey to analyze:

```{r, results='asis'}
library(surveytable)
set_survey(namcs2019sv)
```

# Tables

Take a look at this table:

```{r, results='asis'}
tab("AGER")
```
````

Note the `format` setting, which specifies that this document will create HTML tables. Also note that you do have to add the `results='asis'` argument to the code chunks that print tables. 

# Print using various table-making packages

Use the `output` argument of `set_opts()` to select a table-making package. By default (`output = "auto"`), `surveytable` automatically selects a package depending on whether the output is to the screen (`huxtable`), HTML (`gt`), or PDF (`kableExtra`). You can also explicitly select one of these packages.

Changing the table-making package has a couple of uses:

* Use `as_object()` to generate an object from your favorite table-making package, customize this object, and then finally print it, so the table looks exactly the way you want it to look.
* Print to destinations other than the screen, HTML, or PDF.

## `huxtable`

```{r}
set_opts(output = "huxtable")
```

This is what printing to the screen looks like.

```r
tab("AGER")
```
```{r, echo=FALSE}
print(tab("AGER"), destination = "")
```

To create HTML tables from an R Markdown notebook or a Quarto document, add the `results='asis'` argument to the code chunk, like so:

````{verbatim}
```{r, results='asis'}
tab("AGER")
```
````

```{r, results='asis', echo=FALSE}
tab("AGER")
```

## `gt`

```{r}
set_opts(output = "gt")
```

With `gt`, printing to the screen and to HTML look the same. Here is what printing to the screen looks like:

```r
tab("AGER")
```
```{r, results='asis', echo=FALSE}
print(tab("AGER"), destination = "")
```

Here is HTML:

````{verbatim}
```{r, results='asis'}
tab("AGER")
```
````

```{r, results='asis', echo=FALSE}
tab("AGER")
```


## `kableExtra`

```{r}
set_opts(output = "kableExtra")
```

We have not implemented screen printing with `kableExtra` yet. Try one of the other packages.

Here is HTML:

````{verbatim}
```{r, results='asis'}
tab("AGER")
```
````

```{r, results='asis', echo=FALSE}
tab("AGER")
```

## `auto`

`auto` is the default option. It automatically selects one of the above packages depending on whether the output is to the screen (`huxtable`), HTML (`gt`), or PDF (`kableExtra`).

```{r}
set_opts(output = "auto")
```

Screen output (this should use `huxtable`):

```r
tab("AGER")
```
```{r, echo=FALSE}
print(tab("AGER"), destination = "")
```

HTML output (this should use `gt`):

````{verbatim}
```{r, results='asis'}
tab("AGER")
```
````

```{r, results='asis', echo=FALSE}
tab("AGER")
```

# Advanced printing

## The proper approach

Advanced users can add functionality to use **any** table-making package that they want. For more information, see `help("surveytable-options")`.

## The "quick-and-dirty" approach

The tabulation functions return either:

* for a single table, a data frame, with certain attributes set; or
* for more than one table, a list of such data frames. 

You can convert a single table to a `data.frame` with `as.data.frame()`, like so:

```{r}
tab("AGER") |> as.data.frame()
```

Alternatively, you can pass this data frame to your favorite table-making package. This example passes it to `gt`:

```{r}
set_opts(count = "1k")
tab("AGER") |> gt::gt()
```

The reason that this is the "quick-and-dirty" approach is that the output it creates is not as nice as conventional tables, described above. The output does not have table title (which has important information about the variable and the survey), table footer (which has important information about sample size and low-precision estimates), and it does not format the estimates. Nevertheless, there could be situations in which this approach is helpful, such as 

* extracting an exact value from a table using `as.data.frame()`; or 
* quickly using your favorite table-making package.

# Save the tables

## Save to a CSV file

All tabulation functions have an argument called `csv`. Use it to specify the name of a CSV (comma-separated values) file, like so:

```r
tab("AGER", csv = "myfile.csv")
```

```{r, results='asis', echo=FALSE}
tab("AGER")
```

Open this CSV file in Excel or your favorite text editor or spreadsheet. 

## Save to an R data file

Use the built-in `saveRDS()` function to save a table to an R data file:

```r
tab("AGER") |> saveRDS("myfile.rds")
```

You can later load this data file back into R. To print the table, just load the file, like so:

```r
readRDS("myfile.rds")
```

```{r, results='asis', echo=FALSE}
tab("AGER")
```

# Suppress printing

There are times when you might want to prevent the tabulation functions from printing tables. If you are saving the tables to a CSV file anyway, you might not need screen printing. 

As mentioned above, if the tabulation functions are called from within a loop without using the `print()` command, they won't print. 

An easy way to suppress printing when the tabulation functions are called from the top level is to assign the output to some variable. For example, this will save the table to a CSV file, but won't print it to the screen:

```r
tmp = tab("AGER", csv = "myfile.csv")
```