# 03. Outputs

#### Chris Bailiss

#### 2020-03-07

## 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:

    # 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`:

    # 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

    Sale ID    Item  Quantity  Price
       5334   Apple         5   0.34
       5336  Orange         8   0.47
       5338  Banana         6   1.34

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.

    # 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"))

    <table class="Table">
      <tr>
        <th class="ColumnHeader">Sale ID</th>
        <th class="ColumnHeader">Item</th>
        <th class="ColumnHeader">Quantity</th>
        <th class="ColumnHeader">Price</th>
      </tr>
      <tr>
        <th class="RowHeader">5334</th>
        <td class="Cell">Apple</td>
        <td class="Cell">5</td>
        <td class="Cell">0.34</td>
      </tr>
      <tr>
        <th class="RowHeader">5336</th>
        <td class="Cell">Orange</td>
        <td class="Cell">8</td>
        <td class="Cell">0.47</td>
      </tr>
      <tr>
        <th class="RowHeader">5338</th>
        <td class="Cell">Banana</td>
        <td class="Cell">6</td>
        <td class="Cell">1.34</td>
      </tr>
    </table>

    cat(tbl$getCss())

    .Table {border-collapse: collapse; }
    .ColumnHeader {font-family: Arial; font-size: 0.75em; padding: 2px; border: 1px solid lightgray; vertical-align: middle; text-align: center; font-weight: bold; background-color: #F2F2F2; }
    .RowHeader {font-family: Arial; font-size: 0.75em; padding: 2px 8px 2px 2px; border: 1px solid lightgray; vertical-align: middle; text-align: left; font-weight: bold; background-color: #F2F2F2; }
    .Cell {font-family: Arial; font-size: 0.75em; padding: 2px 2px 2px 8px; border: 1px solid lightgray; vertical-align: middle; text-align: right; }
    .Total {font-family: Arial; font-size: 0.75em; padding: 2px 2px 2px 8px; border: 1px solid lightgray; vertical-align: middle; text-align: right; font-weight: bold; }

## Output in Excel

Please see the Excel Export vignette.

## Output as an R Matrix

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

    # 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()

         [,1]      [,2]     [,3]       [,4]
    [1,] "Sale ID" "Item"   "Quantity" "Price"
    [2,] "5334"    "Apple"  "5"        "0.34"
    [3,] "5336"    "Orange" "8"        "0.47"
    [4,] "5338"    "Banana" "6"        "1.34"

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.

    # 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)

         Item     Quantity Price
    5334 "Apple"  "5"      "0.34452354"
    5336 "Orange" "8"      "0.4732543"
    5338 "Banana" "6"      "1.3443243"

## 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.

    # 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

      Sale.ID   Item Quantity     Price
    1    5334  Apple        5 0.3445235
    2    5336 Orange        8 0.4732543
    3    5338 Banana        6 1.3443243

    str(df)

    'data.frame':   3 obs. of  4 variables:
     $ Sale.ID : num  5334 5336 5338
     $ Item    : Factor w/ 3 levels "Apple","Banana",..: 1 3 2
     $ Quantity: num  5 8 6
     $ Price   : num  0.345 0.473 1.344

## Further Reading

The full set of vignettes is:

1. Introduction
2. Working with Cells
3. Outputs
4. Styling
5. Finding and Formatting
6. Shiny
7. Excel Export