---
title: "03. Outputs"
author: "Chris Bailiss"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{03. Outputs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## In This Vignette

* Overview
* Example Table
* Output as Plain Text
* Output as HTML
* Output in Excel
* Output as an R Matrix
* Output as an R Data Frame
* Further Reading

## Overview

The `basictabler` package supports outputting a table in a number of different forms:

- A htmlwidget for R-Studio - using `tbl$renderTable()` to render the table into the "Viewer" tab in R-Studio,
- A htmlwidget for Shiny applications - using `basictabler(tbl)` to render the table into the Shiny app,
- As HTML - using either:
    + `tbl$getHtml()` to retrieve a character variable containing HTML, or
    + `tbl$saveHtml()` to save the HTML to a file.
- As plain text - using `tbl` to output to the console or `tbl$asCharacter` to retrieve as a character value.
- Into an Excel Worksheet.

Sometimes it is desirable to retrieve the table as a more standard data type that is easier to work with in R code.  A table can be converted to either a matrix or a data frame.  Often neither data type is a perfect representation of your table - which option is better will depend upon your use case.

## Example Table

The following table is used as the basis of the examples in the rest of this vignette:

```{r, message=FALSE, warning=FALSE}
# data for the table
saleIds <- c(5334, 5336, 5338)
items <- c("Apple", "Orange", "Banana")
quantities <- c(5, 8, 6)
prices <- c(0.34452354, 0.4732543, 1.3443243)

# construct the table
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(saleIds, items, quantities, prices), 
            firstColumnAsRowHeaders=TRUE,
            explicitColumnHeaders=c("Sale ID", "Item", "Quantity", "Price"),
            columnFormats=list(NULL, NULL, NULL, "%.2f"))
tbl$renderTable()
```

## Output as Plain Text

A table is outputted to the console as plain text simply by using `tbl`:

```{r, message=FALSE, warning=FALSE, comment=""}
# data for the table
saleIds <- c(5334, 5336, 5338)
items <- c("Apple", "Orange", "Banana")
quantities <- c(5, 8, 6)
prices <- c(0.34452354, 0.4732543, 1.3443243)

# construct the table
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(saleIds, items, quantities, prices), 
            firstColumnAsRowHeaders=TRUE,
            explicitColumnHeaders=c("Sale ID", "Item", "Quantity", "Price"),
            columnFormats=list(NULL, NULL, NULL, "%.2f"))

# output table
tbl
```

Alternatively, the plain text representation of the table can be retrieved as a character value using `tbl$asCharacter`.

## Output as HTML

### Rendering a htmlwidget

A table is outputted as a htmlwidget simply by calling `tbl$renderTable()`.  There are numerous examples throughout these vignettes, including the example directly above.

For outputting as a htmlwidget in a Shiny application, use `basictabler(tbl)`.

### Retrieving HTML

To retrieve the HTML of a table, use `tbl$getHtml()`.  This returns a list of html tag objects built using the htmltools package.  This object can be converted to a simple character variable using `as.character()` or as illustrated below.  The CSS declarations for a table can be retrieved using `tbl$getCss()` - also illustrated below.

```{r, message=FALSE, warning=FALSE, comment=""}
# data for the table
saleIds <- c(5334, 5336, 5338)
items <- c("Apple", "Orange", "Banana")
quantities <- c(5, 8, 6)
prices <- c(0.34452354, 0.4732543, 1.3443243)

# construct the table
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(saleIds, items, quantities, prices), 
            firstColumnAsRowHeaders=TRUE,
            explicitColumnHeaders=c("Sale ID", "Item", "Quantity", "Price"),
            columnFormats=list(NULL, NULL, NULL, "%.2f"))

#out the HTML and CSS
cat(paste(tbl$getHtml(), sep="", collapse="\n"))
cat(tbl$getCss())
```

## Output in Excel

Please see the [Excel Export](v07-excelexport.html) vignette.

## Output as an R Matrix

Converting a table to a matrix can be accomplished as follows:

```{r, message=FALSE, warning=FALSE, eval=TRUE, comment=""}
# data for the table
saleIds <- c(5334, 5336, 5338)
items <- c("Apple", "Orange", "Banana")
quantities <- c(5, 8, 6)
prices <- c(0.34452354, 0.4732543, 1.3443243)

# construct the table
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(saleIds, items, quantities, prices), 
            firstColumnAsRowHeaders=TRUE,
            explicitColumnHeaders=c("Sale ID", "Item", "Quantity", "Price"),
            columnFormats=list(NULL, NULL, NULL, "%.2f"))

# output as matrix
tbl$asMatrix()
```

The `firstRowAsColumnNames` and `firstColumnAsRowNames` parameters control how the names in the matrix are set.  The `rawValue` parameter specifies whether the matrix should contain the raw values or the formatted values.

```{r, message=FALSE, warning=FALSE, eval=TRUE, comment=""}
# data for the table
saleIds <- c(5334, 5336, 5338)
items <- c("Apple", "Orange", "Banana")
quantities <- c(5, 8, 6)
prices <- c(0.34452354, 0.4732543, 1.3443243)

# construct the table
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(saleIds, items, quantities, prices), 
            firstColumnAsRowHeaders=TRUE,
            explicitColumnHeaders=c("Sale ID", "Item", "Quantity", "Price"),
            columnFormats=list(NULL, NULL, NULL, "%.2f"))

# output as matrix
tbl$asMatrix(firstRowAsColumnNames=TRUE, firstColumnAsRowNames=TRUE, rawValue=TRUE)
```

## Output as an R Data Frame

The `asDataFrame()` function returns a data frame with the same layout as the table, e.g. a table with a body consisting of 10 rows and 2 columns will result in a data frame also containing 10 rows and 2 columns.

Again, the `firstRowAsColumnNames` and `firstColumnAsRowNames` parameters control how the names in the data frame are set and the `rawValue` parameter specifies whether the matrix should contain the raw values or the formatted values.

```{r, message=FALSE, warning=FALSE, eval=TRUE, comment=""}
# data for the table
saleIds <- c(5334, 5336, 5338)
items <- c("Apple", "Orange", "Banana")
quantities <- c(5, 8, 6)
prices <- c(0.34452354, 0.4732543, 1.3443243)

# construct the table
library(basictabler)
tbl <- BasicTable$new()
tbl$addData(data.frame(saleIds, items, quantities, prices), 
            firstColumnAsRowHeaders=TRUE,
            explicitColumnHeaders=c("Sale ID", "Item", "Quantity", "Price"),
            columnFormats=list(NULL, NULL, NULL, "%.2f"))

# output as data frame
df <- tbl$asDataFrame(firstRowAsColumnNames=TRUE, rawValue=TRUE)
df
str(df)
```

## Further Reading

The full set of vignettes is:

1. [Introduction](v01-introduction.html)
2. [Working with Cells](v02-workingwithcells.html)
3. [Outputs](v03-outputs.html)
4. [Styling](v04-styling.html)
5. [Finding and Formatting](v05-findingandformatting.html)
6. [Shiny](v06-shiny.html)
7. [Excel Export](v07-excelexport.html)
