Author: Brodie Gaslam

# Embed Diffs in R Markdown Or Shiny

#### Brodie Gaslam

## Rmarkdown

### Basic Requirements

Any R chunks that produce diffs should include the `results='asis'` option, e.g.:

    ```{r, comment="", results="asis"}
    # R code here
    ```

### Embedded CSS

This is what a basic code block should look like:

    ```{r, comment="", results="asis"}
    cat(                                 # output to screen
      as.character(                      # convert to diff to character vector
        diffPrint(                       # run diff
          1:5, 2:6,
          format="html",                 # specify html output
          style=list(
            html.output="diff.w.style"   # configure html style
          )
    ) ) )
    ```

Here we use this same code as an actual markdown R code block:

    cat(
      as.character(
        diffPrint(
          1:5, 2:6,
          format="html",
          style=list(html.output="diff.w.style")
    ) ) )

    < 1:5> 2:6@@ 1 @@@@ 1 @@< [1] 1 2 3 4 5> [1] 2 3 4 5 6

This is an ugly implementation because it produces illegal HTML. The styles are directly embedded in the body of the document, outside of the HEAD tags. Although this is illegal HTML, it seems to work in most browsers. Another problem is that every diff you use in your document will inject the same CSS code over and over.

### External CSS

A better option is to provide the CSS directly by modifying the `output` portion of the YAML header:

    ---
    output:
        rmarkdown::html_vignette:
            toc: true
            css: !expr diffobj::diffobj_css()
    ---

In reality you will probably want to specify multiple CSS files, including the original `rmarkdown` one:

    ---
    output:
        rmarkdown::html_vignette:
            toc: true
            css:
              - !expr diffobj::diffobj_css()
              - !expr system.file("rmarkdown", "templates", "html_vignette", "resources", "vignette.css", package = "rmarkdown")
    ---

Once you set this up then you can use:

    cat(
      as.character(
        diffPrint(
          1:5, 2:6,
          format="html",
          style=list(html.output="diff.only")   # notice this changed
    ) ) )

    < 1:5> 2:6@@ 1 @@@@ 1 @@< [1] 1 2 3 4 5> [1] 2 3 4 5 6

This will omit the CSS, but since we include it via the YAML everything should work as expected.

### Use Options

Almost all `diffobj` parameters can be specified via options:

    options(
      diffobj.format="html",
      diffobj.style=list(html.output="diff.only")
    )

Then you can just run the diff as normal:

    cat(as.character(diffPrint(1:5, 2:6)))

    < 1:5> 2:6@@ 1 @@@@ 1 @@< [1] 1 2 3 4 5> [1] 2 3 4 5 6

## Shiny

Shiny usage is very similar to `rmarkdown`. In both cases we want to get `diffobj` to produce HTML output to embed in our document. If we are willing to embed the CSS with each diff, we can use:

    library(shiny)
    shinyApp(
      ui=fluidPage(htmlOutput('diffobj_element')),
      server=function(input, output) {
        output$diffobj_element <- renderUI({
          HTML(
            as.character(
              diffPrint(
                1:5, 2:6,
                format="html",
                style=list(html.output="diff.w.style")
    ) ) )}) } )

If we have many diffs, it may be preferable to use options and external style sheet:

    options(
      diffobj.format="html",
      diffobj.style=list(html.output="diff.only")
    )
    shinyApp(
      ui=fluidPage(
        includeCSS(diffobj_css()),
        htmlOutput('diffobj_element')
      ),
      server=function(input, output) {
        output$diffobj_element <- renderUI({
          HTML(as.character(diffPrint(1:5, 2:6,)))
    }) } )

Unlike with our rmarkdown example, this CSS is included in the body of the HTML document instead of in the header, so it is technically illegal like in our embedded css example.