The Basics of highlightHTML (original) (raw)

A more typical workflow for the highlightHTML package is to go from an (R)markdown document and compile it directly with the highlight_html function to create the output HTML file. Another benefit of this workflow, is the ability to use the table_id_inject function. This function allows the injection of CSS ids into summary tables created within R using conditional expressions. More on this function in the simple example below.

Simple Example of Package Workflow

Below is a simple example of an Rmd document that combines both elements, text markup and inserting CSS ids dynamically into a summary table using R code and the table_id_inject function. The summary table below is calculating the mean and standard deviation of the chick weights by different feed types. You can imagine creating a similar table in reports that you create.

---
title: "Rmd to HTML"
author: "Brandon LeBeau"
date: "January 13, 2017"
output: html_document
---

## Simple Markup
The `highlightHTML` packages allows for {#bggrey simple markup} to add styling to text and tables. Using the `rmarkdown` package and the `table_id_inject` function allows users to easily add markup to Rmd documents and render directly to HTML.

```{r symm, echo = FALSE, results = 'asis', message = FALSE}
library(dplyr)
library(highlightHTML)

chickwts %>%
  group_by(feed) %>%
  summarise(avg_weight = mean(weight),
            sd_weight = sd(weight)) %>%
  mutate(feed = as.character(feed)) %>%
  table_id_inject(id = c('#bggrey', '#bgblack', '#bglightred', '#textblue'), 
                conditions = c('> 270', '> 300', '> 60', '== "horsebean"'),
                variable = list('avg_weight', 'avg_weight', 'sd_weight', 'feed'),
                num_digits = 3) %>%
  knitr::kable(format = 'markdown')

The resulting summary table would look like the following in markdown:

| feed                | avg\_weight      | sd\_weight         |
| ------------------- | ---------------- | ------------------ |
| casein              | 323.583 #bgblack | 64.434 #bglightred |
| horsebean #textblue | 160.2            | 38.626             |
| linseed             | 218.75           | 52.236             |
| meatmeal            | 276.909 #bggrey  | 64.901 #bglightred |
| soybean             | 246.429          | 54.129             |
| sunflower           | 328.917 #bgblack | 48.836             |

It is worth discussing the `table_id_inject` function in more detail here. The function takes two required arguments, `id` and `conditionals` and two optional arguments, `variable` and `num_digits`. The two required arguments are a vector of CSS ids (e.g. #bggrey) and a vector of conditional expressions that are evaluated to identify the location to insert the CSS id. These two arguments must be the same length and the CSS id and conditional expression are matched by location. That is, the first element of each argument are matched, the second element of each, and so on. The optional argument, `variable`, specifies which column(s) of the data to evaluate the conditional expression on. By default this argument is empty meaning that all columns are evaluated. If a CSS id is specific to a specific column(s), this argument specified as a list can be included. Finally, the optional `num_digits` argument is used to round the numeric columns. See `round` for more details.

Finally, the Rmd file itself can be passed to the `highlight_html` function which will automatically compile the input file into an HTML output file. The `highlight_html` function takes three main arguments, the path to the input Rmd file (can also be a markdown or HTML file), the path to save the output HTML file, and the CSS styling to be used for the styling Below is the example of processing the simple example shown above.

library(highlightHTML) file <- system.file('examples', 'joss.Rmd', package = 'highlightHTML')

tags <- c('#bgblack {background-color: black; color: white;}', '#bggrey {background-color: #d3d3d3;}', '#bglightred {background-color: #FF6666;}', '#textblue {color: blue}')

highlight_html(input = file, output = tempfile(fileext = ".html"), tags = tags, browse = TRUE, render = TRUE)

```

The results HTML output file now looks like the following:

joss output

Finally, the highlight_html function has an optional argument called browse. This argument is a TRUE/FALSE flag, which defaults to TRUE, to indicate whether the HTML output file should be opened in the default browser upon successful compilation. This can be a good way to view the file to ensure the desired styling was achieved.