<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{2. Embedding APS datasets in other documents}
-->
```{r message=FALSE, echo = FALSE}
library(AnalysisPageServer)
setup.APS.knitr()
```
# Embedding APS datasets in other documents
AnalysisPageServer datasets can be embedded within other (HTML) documents.
```{r results = "hide", echo = FALSE}
## Since the filenames have some randomness, this is just
## a trick to keep the output directory clean if the file
## is knitted more than once.
plotdir <- "embed-example"
if(file.exists(plotdir))
unlink(dir(plotdir, full = TRUE))
```
## Embedding within a knitr document
AnalysisPageServer datasets can be embedded within knitr documents such
as the one you are reading.
To do so, first call `setup.APS.knitr()` to set things up.
The main purpose of this call is to include some javascript and CSS
that makes the interactivity work.
See the documentation
of that function for more details:
```{r eval = FALSE}
library(AnalysisPageServer)
setup.APS.knitr()
```
A few notes about `setup.APS.knitr()`:
1. By default this function makes a table of contents
based on your header elements. Turn this off with `include.toc=FALSE`.
1. It also includes some custom styling. This puts the table of contents in the margin on the left
and the body of your document to the right of that. For example, this document was created with
this default styling. You can control this behavior with the `include.css` argument.
1. It is recommended to use `message=FALSE, echo=FALSE` for this setup block.
Whether you use default or custom styling, after your call to `setup.APS.knitr()` at the
top of your document you can proceed as you normally would. At the point you want
to insert an AnalysisPageServer dataset, make a call to `embed.APS.dataset()`.
In typical usage the first argument is a code block wrapped in `{`curly brackets`}` that contains
your plotting code. You also have to
pass the data. This can either be the return value of the code block, or you can provide
it explicity as the second argument:
```{r eval = FALSE}
x <- seq(0, 2*pi, length = 100)
y <- sin(x) + rnorm(100)/10
col <- adjustcolor(heat.colors(100), alpha.f = 0.6)
embed.APS.dataset({
plot(x, y, col = col, pch = 19)
},
df = data.frame(x=x, y=y, X=x, Y=y),
title = "A shaky sine curve",
data.subdir = "embed-example")
```
```{r echo = FALSE}
## Remember this to show later
x <- seq(0, 2*pi, length = 100)
y <- sin(x) + rnorm(100)/10
col <- adjustcolor(heat.colors(100), alpha.f = 0.6)
div.html <- embed.APS.dataset({
plot(x, y,
col = col,
pch = 19)
},
df = data.frame(x=x, y=y, X=x, Y=y),
title = "A shaky sine curve",
data.subdir = "embed-example")
div.html
```
You can have two datasets on the same page. In the next example we also hide the sidebar
and data table with `show.sidebar = FALSE` and `show.table = FALSE`, and pass in a little extra
styling to get some margins on the sides.
```{r}
x <- rep(1:nrow(volcano), each = ncol(volcano))
y <- rep(1:ncol(volcano), nrow(volcano))
volcano.cells <- data.frame(x = x, y = y, Height = as.vector(t(volcano)))
embed.APS.dataset({
image(volcano, xaxt = "n", yaxt = "n", main = "Maunga Whau Volcano")
},
df = volcano.cells,
title = "", data.subdir = "embed-example",
show.table = FALSE, show.sidebar = FALSE,
show.xy = TRUE,
extra.div.attr = c(style = "width:60%; margin:0 auto"))
```
The `<div>` element to which the extra attributes, such as styling, are applied is the outer container that holds the plot, the
sidebar, and the table. The current version does not support custom styling of the sub-elements.
Omit the first argument to just show the table:
```{r}
embed.APS.dataset(df = iris,
title = "Iris data with no plot", data.subdir = "embed-example")
```
## Embedding within any HTML document
In order to embed an AnalysisPageServer dataset into an HTML document
you first have to copy the "front end" files, including CSS, Javascript
other resources, into the directory where your HTML document will live.
If you are going to write more than one HTML document to the same directory
then you only have to do this once. The `copy.front.end()` function
does this for you. For example,
```{r eval = FALSE}
basedir <- dirname(html.file)
copy.front.end(basedir)
```
Next you must include header lines in your HTML file
to bring in the CSS, Javascript and other
resources required by the front end.
These are returned by this function call:
```{r}
cat(custom.html.headers())
```
Normally they would appear within the `<head>` section of your document.
After that, use the `embed.APS.dataset()` function as described above
to make plots or datasets. Be careful to include `outdir = basedir` so it
knows where to write the SVG and JSON files. Otherwise they would end up in the
current directory, which might not work. Aside from writing those files, `embed.APS.dataset`
returns a `<div>` each time you call it, and
you can then lay these elements out as you like within your HTML document.
Here is an example of what that looks like:
```{r echo = FALSE}
cat(div.html)
```
The `embed.APS.dataset()` accepts a few arguments
that allow you to control the inclusion of the table, of
the sidebar, or to add extra HTML classes or attributes to the `<div>`.
-------------
## Next
[Walk through interactive functionality on basic example](Interactivity.html)