Author: Bhaskar V. Karambelkar
Date: 2017-12-19

# Using widgetframe

#### Bhaskar V. Karambelkar

#### 2017-12-19

The `widgetframe` package eases embedding of `htmlwidgets` inside various HTML based R Markdown documents using iframes. To make the iframes responsive it uses NPR’s Pymjs library.

This package provides two primary functions, `frameableWidget`, and `frameWidget`. `frameableWidget` is used to add extra code to a `htmlwidgets` instance, which allows it to be rendered inside a responsive iframe. `frameWidget` returns a new `htmlwidgets` instance, which wraps and displays content of another `htmlwidgets` instance (e.g. `leaflet`, `DT` etc.) inside a responsive iframe.

### Current Status

For each of the document type below you can find fully working example code in the Github Repo.

- Works With
  - Flex Dashboard: Demo.
  - RMarkdown + knitr: Demo.
  - RMarkdown Website: Demo.
  - Xaringan Presentations: Demo.
    (May also work with other RMarkdown + knitr based presentations.)
  - Bookdown gitbook: (Needs a Makefile for assembly). Demo.
  - blogdown: Demo.

- Does not (yet) work with
  - Shiny: See Github Issue
  - Crosstalk: See Github Issue

### Installation

Avaliable on CRAN and can be installed using …

    install.packages('widgetframe')

Or install the dev version from Github using `devtools` …

    if(!require(devtools)) {
      install.packages('devtools')
    }
    devtools::install_github('bhaskarvk/widgetframe')

### Usage

#### `frameableWidget` function.

The `frameableWidget` function should be used when you need a HTML which can be embedded in an external CMS like WordPress or Blogger, or a static HTML website.

    library(leaflet)
    library(widgetframe)
    l <- leaflet() %>% addTiles()
    htmlwidgets::saveWidget(frameableWidget(l),'leaflet.html')

The resulting `leaflet.html` file contains the necessary Pym.js Child initialization code and will work inside a regular iFrame or better yet a Pym.js responsive iFrame. It is expected that the site which is going to embed this widget’s content has the necessary Pymjs Parent initialization code as described here. The HTML dependencies of the widget (CSS/JS files) will be either inlined or kept external depending on the `seflcontained` argument to `saveWidget`.

#### `frameWidget` function

`frameWidget` function takes an existing `htmlwidgets` instance such as `leaflet` or `DT` etc., wraps it and returns a new `htmlwidgets` instance, which when rendered, displays the input wrapped `htmlwdigets` instance inside a responsive iFrame. This function can be used to knit htmlwidgets such that they are unaffected by the parent HTML file’s CSS. This could be useful in bookdown or R Markdown Websites to embed widgets such that they are unaffected by the site’s global CSS/JS.

    ```{r}
    library(leaflet)
    library(widgetframe)
    l <- leaflet(height=300) %>% addTiles() %>% setView(0,0,1)
    frameWidget(l)
    ```

    ```{r}
    library(dygraphs)
    ts <- dygraph(nhtemp, main = “New Haven Temperatures”,
                  height=250, width=‘95%’)
    frameWidget(ts)
    ```

To know more about how `widgetframe` and `knitr`/`rmarkdown` work together, see the `widgetframe` and `knitr` vignette.