Browse Source

working on vignettes

master
boB Rudis 3 years ago
parent
commit
fc77b059c2
No known key found for this signature in database GPG Key ID: 2A514A4997464560
29 changed files with 505 additions and 105 deletions
  1. +1
    -0
      .gitignore
  2. +4
    -1
      DESCRIPTION
  3. +1
    -1
      NAMESPACE
  4. +8
    -2
      R/as_req.r
  5. +23
    -0
      R/docker-splash.r
  6. +5
    -2
      R/helpers.r
  7. +1
    -1
      R/render-html.r
  8. +3
    -0
      R/render-png.r
  9. +36
    -36
      R/render_file.R
  10. +3
    -1
      R/splashr-package.R
  11. +23
    -0
      R/splashr.r
  12. +17
    -0
      R/utils.r
  13. +7
    -3
      man/as_httr_req.Rd
  14. +3
    -4
      man/execute_lua.Rd
  15. +15
    -0
      man/killall_splash.Rd
  16. +0
    -38
      man/render_file.Rd
  17. +2
    -3
      man/render_har.Rd
  18. +3
    -4
      man/render_html.Rd
  19. +2
    -3
      man/render_jpeg.Rd
  20. +2
    -3
      man/render_json.Rd
  21. +7
    -3
      man/render_png.Rd
  22. +5
    -0
      man/splash.Rd
  23. +6
    -0
      man/splash_active.Rd
  24. +6
    -0
      man/splash_debug.Rd
  25. +6
    -0
      man/splash_history.Rd
  26. +6
    -0
      man/splash_perf_stats.Rd
  27. +6
    -0
      man/splash_version.Rd
  28. BIN
      vignettes/figures/splashr01.png
  29. +304
    -0
      vignettes/intro_to_splashr.Rmd

+ 1
- 0
.gitignore View File

@@ -5,3 +5,4 @@
src/*.o
src/*.so
src/*.dll
inst/doc

+ 4
- 1
DESCRIPTION View File

@@ -21,7 +21,9 @@ Suggests:
tibble,
jpeg,
png,
covr
covr,
knitr,
rmarkdown
Depends:
R (>= 3.2.0)
Imports:
@@ -42,3 +44,4 @@ Imports:
HARtools,
lubridate
RoxygenNote: 6.0.1
VignetteBuilder: knitr

+ 1
- 1
NAMESPACE View File

@@ -35,8 +35,8 @@ export(is_post)
export(is_svg)
export(is_xhr)
export(is_xml)
export(killall_splash)
export(renderHARviewer)
export(render_file)
export(render_har)
export(render_html)
export(render_jpeg)


+ 8
- 2
R/as_req.r View File

@@ -1,9 +1,15 @@
#' Create an httr verb request function from an HAR request
#'
#' This function is very useful if you used `splashr` to find XHR requests in a dynamic
#' page and want to be able to make a call directly to that XHR resource. Once you
#' identify the proper HAR entry, pass it to this function and fully working function
#' that makes an `httr::VERB()` request will be created and returned. The text of the function
#' will also be put onto the clipboad if `add_clip` is `TRUE``
#'
#' @md
#' @param entry HAR entry
#' @param quiet quiet
#' @param add_clip add clip
#' @param quiet quiet (no messages)
#' @param add_clip add clip (paste the function text to the clipboard)
#' @export
as_httr_req <- function(entry, quiet=TRUE, add_clip=TRUE) {



+ 23
- 0
R/docker-splash.r View File

@@ -65,6 +65,29 @@ stop_splash <- function(splash_container) {
splash_container$remove()
}

#' Prune all dead and running Splash Docker containers
#'
#' _This is a destructive function._ It will stop **any** Docker container that
#' is based on an image matching "`scrapinghub/splashr`". It's best used when you
#' had a session forcefully interuppted and had been using the R helper functions
#' to start/stop the Splash Docker container. You may want to consider using the
#' Docker command-line interface to perform this work manually.
#'
#' @export
killall_splash <- function() {

client <- docker::docker$from_env()
x <- client$containers$list(all = TRUE)

for (cntnr in x) {
if (grepl("scrapinghub/splash", cntnr$image$tags[1])) {
message(sprintf("Pruning: %s...", cntnr$id))
if (cntnr$status == "running") cntnr$stop()
cntnr$remove()
}
}
}


# @param add_tempdir This is `FALSE` initially since you could try to run
# the splash image on a remote system. It has to be a local one for this to work.


+ 5
- 2
R/helpers.r View File

@@ -5,10 +5,13 @@
#' @family splash_har_helpers
#' @return A `raw` vector of the content or `NULL`
#' @export
get_response_body <- function(har_resp_obj) {
get_response_body <- function(har_resp_obj, type=c("raw", "text")) {
type <- match.arg(type, c("raw", "text"))
resp <- har_resp_obj$response$content$text
if (resp == "") return(NULL)
openssl::base64_decode(resp)
tmp <- openssl::base64_decode(resp)
if (type == "text") tmp <- readBin(tmp, "character")
tmp
}

#' Retrieve or test content type of a HAR request object


+ 1
- 1
R/render-html.r View File

@@ -1,6 +1,6 @@
#' Return the HTML of the javascript-rendered page.
#'
#' Similar to `rvest::read_html`.
#' Similar (i.e. a dynamic equivalent) to `rvest::read_html`.
#'
#' @md
#' @param splash_obj Object created by a call to [splash()]


+ 3
- 0
R/render-png.r View File

@@ -8,6 +8,9 @@
#' @references [Splash docs](http://splash.readthedocs.io/en/stable/index.html)
#' @inheritParams render_html
#' @export
#' @examples \dontrun{
#' render_png(url = "https://httpbin.org/")
#' }
render_png <- function(
splash_obj = splash_local, url, base_url=NULL, width, height,
timeout=30, resource_timeout, wait=0, render_all=TRUE,


+ 36
- 36
R/render_file.R View File

@@ -1,37 +1,37 @@
#' Return the HTML or image (png) of the javascript-rendered page in a local file
#'
#' The suggested use-case for this is rendering a widget
#'
#' TODO Test if container is running
#' TODO Enable passing in of an htmlwidget and use saveWidget
#'
#' @md
#' @param splash_obj Object created by a call to [splash()]
#' @param file_path Absolute path to a filename on the local host. **This only works with a locally running Splash instance started with [start_splash]().**
#' @param wait seconds to wait
#' @param output either `html` or `png` to get the page content or an image capture
#' @param viewport View width and height (in pixels) of the browser viewport to render the web page. Format is "`<width>x<height>`". e.g. 800x600. Default value is 1024x768.
#' @param ... other params to [render_html()] or [render_png()]
#' @family splash_renderers
#' @return An XML document or `magick` object
#' @export
render_file <- function(splash_obj = splash_local, file_path, output=c("html", "png"), wait=0, viewport="1024x768", ...) {
wait <- check_wait(wait)
output <- match.arg(output, c("html", "png"))
file.copy(file_path, .pkgenv$temp_dir)
fil <- basename(file_path)
URL <- sprintf("http://localhost:9999/%s", fil)
if (output == "html") {
render_html(splash_obj, URL, wait=wait, viewport=viewport, ...)
} else {
render_png(splash_obj, URL, wait=wait, viewport=viewport, ...)
}
}
# Return the HTML or image (png) of the javascript-rendered page in a local file
#
# The suggested use-case for this is rendering a widget
#
# TODO Test if container is running
# TODO Enable passing in of an htmlwidget and use saveWidget
#
# @md
# @param splash_obj Object created by a call to [splash()]
# @param file_path Absolute path to a filename on the local host. **This only works with a locally running Splash instance started with [start_splash]().**
# @param wait seconds to wait
# @param output either `html` or `png` to get the page content or an image capture
# @param viewport View width and height (in pixels) of the browser viewport to render the web page. Format is "`<width>x<height>`". e.g. 800x600. Default value is 1024x768.
# @param ... other params to [render_html()] or [render_png()]
# @family splash_renderers
# @return An XML document or `magick` object
# @export
# render_file <- function(splash_obj = splash_local, file_path, output=c("html", "png"), wait=0, viewport="1024x768", ...) {
#
# wait <- check_wait(wait)
#
# output <- match.arg(output, c("html", "png"))
#
# file.copy(file_path, .pkgenv$temp_dir)
#
# fil <- basename(file_path)
#
# URL <- sprintf("http://localhost:9999/%s", fil)
#
# if (output == "html") {
# render_html(splash_obj, URL, wait=wait, viewport=viewport, ...)
# } else {
# render_png(splash_obj, URL, wait=wait, viewport=viewport, ...)
# }
#
# }


+ 3
- 1
R/splashr-package.R View File

@@ -3,7 +3,9 @@
#' 'Splash' <https://github.com/scrapinghub/splash> is a 'JavaScript' rendering service.
#' It’s a lightweight web browser with an 'HTTP' API, implemented in 'Python' using 'Twisted'
#' and 'QT' and provides some of the core functionality of the 'RSelenium' or 'seleniumPipes'
#' R pacakges in a lightweight footprint. Some of 'Splash' features include the ability to process
#' R pacakges in a lightweight footprint.
#'
#' Some of 'Splash' features include the ability to process
#' multiple webpages in parallel; retrieving 'HTML' results and/or take screenshots; disabling
#' images or use 'Adblock Plus' rules to make rendering faster; executing custom 'JavaScript' in
#' page context; getting detailed rendering info in 'HAR' format.


+ 23
- 0
R/splashr.r View File

@@ -5,6 +5,9 @@ splash_url <- function(splash_obj) { sprintf("http://%s:%s", splash_obj$host, sp
#' @param host host or IP address
#' @param port port the server is running on (default is 8050)
#' @export
#' @examples \dontrun{
#' sp <- splash()
#' }
splash <- function(host, port=8050L) {
list(host=host, port=port)
}
@@ -22,6 +25,10 @@ s_GET <- purrr::safely(GET)
#' @family splash_info_functions
#' @return `TRUE` if Slash server is running, otherwise `FALSE`
#' @export
#' @examples \dontrun{
#' sp <- splash()
#' splash_active(sp)
#' }
splash_active <- function(splash_obj = splash_local) {

res <- s_GET(splash_url(splash_obj), path="_ping")
@@ -48,6 +55,10 @@ splash_active <- function(splash_obj = splash_local) {
#' @param splash_obj A splash connection object
#' @family splash_info_functions
#' @export
#' @examples \dontrun{
#' sp <- splash()
#' splash_version(sp)
#' }
splash_version <- function(splash_obj = splash_local) {
execute_lua(splash_obj, '
function main(splash)
@@ -62,6 +73,10 @@ end
#' @param splash_obj A splash connection object
#' @family splash_info_functions
#' @export
#' @examples \dontrun{
#' sp <- splash()
#' splash_history(sp)
#' }
splash_history <- function(splash_obj = splash_local) {
execute_lua(splash_obj, '
function main(splash)
@@ -77,6 +92,10 @@ end
#' @param splash_obj A splash connection object
#' @family splash_info_functions
#' @export
#' @examples \dontrun{
#' sp <- splash()
#' splash_perf_stats(sp)
#' }
splash_perf_stats <- function(splash_obj = splash_local) {
execute_lua(splash_obj, '
function main(splash)
@@ -91,6 +110,10 @@ end
#' @param splash_obj A splash connection object
#' @family splash_info_functions
#' @export
#' @examples \dontrun{
#' sp <- splash()
#' splash_debug(sp)
#' }
splash_debug <- function(splash_obj = splash_local) {

httr::GET(splash_url(splash_obj), path="_debug") %>%


+ 17
- 0
R/utils.r View File

@@ -0,0 +1,17 @@
#' Convert a Base64 encoded string into an R object
#'
#' A simple wrapper around calls to `openssl::base64_decode()` and
#' `jsonlite::fromJSON()`.
#'
#' @md
#' @param x a string
#' @param flatten flatten JSON structures upon conversion?
#' @param ... passed on to `jsonlite::fromJSON()`
#' @export
json_fromb64 <- function(x, flatten=TRUE, ...) {

tmp <- openssl::base64_decode(x)
tmp <- readBin(tmp, "character")
jsonlite::fromJSON(tmp, flatten=flatten, ...)

}

+ 7
- 3
man/as_httr_req.Rd View File

@@ -9,10 +9,14 @@ as_httr_req(entry, quiet = TRUE, add_clip = TRUE)
\arguments{
\item{entry}{HAR entry}

\item{quiet}{quiet}
\item{quiet}{quiet (no messages)}

\item{add_clip}{add clip}
\item{add_clip}{add clip (paste the function text to the clipboard)}
}
\description{
Create an httr verb request function from an HAR request
This function is very useful if you used \code{splashr} to find XHR requests in a dynamic
page and want to be able to make a call directly to that XHR resource. Once you
identify the proper HAR entry, pass it to this function and fully working function
that makes an \code{httr::VERB()} request will be created and returned. The text of the function
will also be put onto the clipboad if \code{add_clip} is `TRUE``
}

+ 3
- 4
man/execute_lua.Rd View File

@@ -54,8 +54,7 @@ member_scores
}
}
\seealso{
Other splash_renderers: \code{\link{render_file}},
\code{\link{render_har}}, \code{\link{render_html}},
\code{\link{render_jpeg}}, \code{\link{render_json}},
\code{\link{render_png}}
Other splash_renderers: \code{\link{render_har}},
\code{\link{render_html}}, \code{\link{render_jpeg}},
\code{\link{render_json}}, \code{\link{render_png}}
}

+ 15
- 0
man/killall_splash.Rd View File

@@ -0,0 +1,15 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/docker-splash.r
\name{killall_splash}
\alias{killall_splash}
\title{Prune all dead and running Splash Docker containers}
\usage{
killall_splash()
}
\description{
_This is a destructive function._ It will stop **any** Docker container that
is based on an image matching "`scrapinghub/splashr`". It's best used when you
had a session forcefully interuppted and had been using the R helper functions
to start/stop the Splash Docker container. You may want to consider using the
Docker command-line interface to perform this work manually.
}

+ 0
- 38
man/render_file.Rd View File

@@ -1,38 +0,0 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/render_file.R
\name{render_file}
\alias{render_file}
\title{Return the HTML or image (png) of the javascript-rendered page in a local file}
\usage{
render_file(splash_obj = splash_local, file_path, output = c("html", "png"),
wait = 0, viewport = "1024x768", ...)
}
\arguments{
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}

\item{file_path}{Absolute path to a filename on the local host. \strong{This only works with a locally running Splash instance started with \url{start_splash}.}}

\item{output}{either \code{html} or \code{png} to get the page content or an image capture}

\item{wait}{seconds to wait}

\item{viewport}{View width and height (in pixels) of the browser viewport to render the web page. Format is "\code{<width>x<height>}". e.g. 800x600. Default value is 1024x768.}

\item{...}{other params to \code{\link[=render_html]{render_html()}} or \code{\link[=render_png]{render_png()}}}
}
\value{
An XML document or \code{magick} object
}
\description{
The suggested use-case for this is rendering a widget
}
\details{
TODO Test if container is running
TODO Enable passing in of an htmlwidget and use saveWidget
}
\seealso{
Other splash_renderers: \code{\link{execute_lua}},
\code{\link{render_har}}, \code{\link{render_html}},
\code{\link{render_jpeg}}, \code{\link{render_json}},
\code{\link{render_png}}
}

+ 2
- 3
man/render_har.Rd View File

@@ -74,7 +74,6 @@ is incredibly detailed, full of information on every component loaded.
}
\seealso{
Other splash_renderers: \code{\link{execute_lua}},
\code{\link{render_file}}, \code{\link{render_html}},
\code{\link{render_jpeg}}, \code{\link{render_json}},
\code{\link{render_png}}
\code{\link{render_html}}, \code{\link{render_jpeg}},
\code{\link{render_json}}, \code{\link{render_png}}
}

+ 3
- 4
man/render_html.Rd View File

@@ -68,14 +68,13 @@ to be processed first by \code{xml2}. If you choose \code{raw_html=TRUE} you'll
character vector.
}
\description{
Similar to \code{rvest::read_html}.
Similar (i.e. a dynamic equivalent) to \code{rvest::read_html}.
}
\references{
\href{http://splash.readthedocs.io/en/stable/index.html}{Splash docs}
}
\seealso{
Other splash_renderers: \code{\link{execute_lua}},
\code{\link{render_file}}, \code{\link{render_har}},
\code{\link{render_jpeg}}, \code{\link{render_json}},
\code{\link{render_png}}
\code{\link{render_har}}, \code{\link{render_jpeg}},
\code{\link{render_json}}, \code{\link{render_png}}
}

+ 2
- 3
man/render_jpeg.Rd View File

@@ -79,7 +79,6 @@ Return a image (in JPEG format) of the javascript-rendered page.
}
\seealso{
Other splash_renderers: \code{\link{execute_lua}},
\code{\link{render_file}}, \code{\link{render_har}},
\code{\link{render_html}}, \code{\link{render_json}},
\code{\link{render_png}}
\code{\link{render_har}}, \code{\link{render_html}},
\code{\link{render_json}}, \code{\link{render_png}}
}

+ 2
- 3
man/render_json.Rd View File

@@ -111,7 +111,6 @@ overwhelmed with data. Use \code{\link[=str]{str()}} to inspect various portions
}
\seealso{
Other splash_renderers: \code{\link{execute_lua}},
\code{\link{render_file}}, \code{\link{render_har}},
\code{\link{render_html}}, \code{\link{render_jpeg}},
\code{\link{render_png}}
\code{\link{render_har}}, \code{\link{render_html}},
\code{\link{render_jpeg}}, \code{\link{render_png}}
}

+ 7
- 3
man/render_png.Rd View File

@@ -70,12 +70,16 @@ a \link{magick} image object
\description{
Return a image (in PNG format) of the javascript-rendered page.
}
\examples{
\dontrun{
render_png(url = "https://httpbin.org/")
}
}
\references{
\href{http://splash.readthedocs.io/en/stable/index.html}{Splash docs}
}
\seealso{
Other splash_renderers: \code{\link{execute_lua}},
\code{\link{render_file}}, \code{\link{render_har}},
\code{\link{render_html}}, \code{\link{render_jpeg}},
\code{\link{render_json}}
\code{\link{render_har}}, \code{\link{render_html}},
\code{\link{render_jpeg}}, \code{\link{render_json}}
}

+ 5
- 0
man/splash.Rd View File

@@ -19,4 +19,9 @@ splash_local
\description{
Configure parameters for connecting to a Splash server
}
\examples{
\dontrun{
sp <- splash()
}
}
\keyword{datasets}

+ 6
- 0
man/splash_active.Rd View File

@@ -15,6 +15,12 @@ splash_active(splash_obj = splash_local)
\description{
Test if a Splash server is up
}
\examples{
\dontrun{
sp <- splash()
splash_active(sp)
}
}
\seealso{
Other splash_info_functions: \code{\link{splash_debug}},
\code{\link{splash_history}},


+ 6
- 0
man/splash_debug.Rd View File

@@ -15,6 +15,12 @@ splash_debug(splash_obj = splash_local)
\description{
Retrieve debug-level info for a Splash server
}
\examples{
\dontrun{
sp <- splash()
splash_debug(sp)
}
}
\seealso{
Other splash_info_functions: \code{\link{splash_active}},
\code{\link{splash_history}},


+ 6
- 0
man/splash_history.Rd View File

@@ -12,6 +12,12 @@ splash_history(splash_obj = splash_local)
\description{
Get information about requests/responses for the pages loaded
}
\examples{
\dontrun{
sp <- splash()
splash_history(sp)
}
}
\seealso{
Other splash_info_functions: \code{\link{splash_active}},
\code{\link{splash_debug}},


+ 6
- 0
man/splash_perf_stats.Rd View File

@@ -12,6 +12,12 @@ splash_perf_stats(splash_obj = splash_local)
\description{
Get Splash performance-related statistics
}
\examples{
\dontrun{
sp <- splash()
splash_perf_stats(sp)
}
}
\seealso{
Other splash_info_functions: \code{\link{splash_active}},
\code{\link{splash_debug}}, \code{\link{splash_history}},


+ 6
- 0
man/splash_version.Rd View File

@@ -12,6 +12,12 @@ splash_version(splash_obj = splash_local)
\description{
Get Splash version information
}
\examples{
\dontrun{
sp <- splash()
splash_version(sp)
}
}
\seealso{
Other splash_info_functions: \code{\link{splash_active}},
\code{\link{splash_debug}}, \code{\link{splash_history}},


BIN
vignettes/figures/splashr01.png View File

Before After
Width: 1024  |  Height: 2761  |  Size: 490KB

+ 304
- 0
vignettes/intro_to_splashr.Rmd View File

@@ -0,0 +1,304 @@
---
title: "Introduction to splashr"
author: "Bob Rudis"
date: "`r Sys.Date()`"
output:
rmarkdown::html_vignette:
toc: true
vignette: >
%\VignetteIndexEntry{Introduction to splashr}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---

Capturing information/conent from internet resources can be a tricky endeavour. Along with the many legal + ethical issues there are an increasing numbner of sites that render content dynamically, either through `XMLHttpRequests` (XHR) or on-page JavaScript (JS) rendering of
in-page content. There are also many sites that make it difficult to fill-in form data programmatically.

There are ways to capture these types of resources in R. One way is via the [`RSelenium`](https://CRAN.R-project.org/package=RSelenium) ecosystem of packages. Another is with packages such as [`webshot`](https://CRAN.R-project.org/package=webshot). One can also write custom [`phantomjs`](http://phantomjs.org/) scripts and post-process the HTML output.

The `splashr` package provides tooling around another web-scraping ecosystem: [Splash](https://scrapinghub.com/splash). A Splash environment is fundamentally a headless web browser based on the QT WebKit library. Unlike the Selenium ecosystem, Splash is not based on the [WebDriver](https://www.w3.org/TR/webdriver/) protocol, but has a custom HTTP API that provides both similar and different idioms for accessing and maniuplating web content.

## Getting Started

Before you can use `splashr` you will need access to a Splash environment. You can either:

- [pay for instances](https://app.scrapinghub.com/account/signup/);
- [get a Splash server running locally by hand](https://github.com/scrapinghub/splash), or
- use Splash in a [Docker](https://www.docker.com/) container.

The package and this document are going to steer you into using Docker containers. Docker is free for macOS, Windows and Linux systems, plus most major cloud computing providers have support for Docker containers. If you don't have Docker installed, then your first step should be to get Docker going and [verifying your setup](https://docs.docker.com/get-started/).

Once you have Docker working, you can follow the [Splash installation guidance](https://splash.readthedocs.io/en/stable/install.html) to manually obtain, start and stop Splash docker containers. _There must be a running, accessible Splash instance for `splashr` to work_.

If you're comfortable trying to get a working Python environment working on your system, you can also use the Splash Docker helper functions that come with this package:

- `install_splash()` will perform the same operation as `docker pull ...`
- `start_splash()` will perform the same operation as `docker run ...`, and
- `stop_splash()` will stop and remove the conainter object returned by `start_splash()`

Follow the vignettes in the [`docker`](https://CRAN.R-project.org/package=docker) package to get the `docker` package up and running.

The remainder of this document assumes that you have a Splash instance up and running on your localhost.

## Scraping Bascis --- `render_` functions

Splash (and, hence, `splashr`) has a feature-rich API that ranges from quick-and-easy to complex-detailed-and-powerful. We'll start with some easy basics. First make sure Splash is running:

```
library(splashr)

splash_active()
## Status of splash instance on [http://localhost:8050]: ok. Max RSS: 74.42578 Mb
##
## [1] TRUE
```

THe first action we'll perform may surprise you. We're going to take a screenshot of the <https://analytics.usa.gov/> site. Why that site? First, the Terms of Service allow for scraping. Second, it has a great deal of dynamic content. And, third, we can validate our scraping findings with a direct data download (which will be an exercise left to the reader).

Enough words. Let's see what this site looks like!

```
library(magick)

render_png(url = "https://analytics.usa.gov/", wait = 5)
## format width height colorspace filesize
## 1 PNG 1024 2761 sRGB 531597
```

<img style="max-widgh:100%" width="100%" src="figures/splashr01.png"/>

Let's decompose what we just did:

1. We called `render_png()` function. The job of this function is to --- by default -- take a "screenshot" of the fully rendered page content at a specified URL.
1. We passed in the `url = ` parameter. The default first parameter is a `splashr` object created by the `splash()`. However, since it's highly likely most folks will be running a Splash server locally with the default configuration, most `splashr` functions will use an inherent, "`splash_local`" object if you're willing to use named parameters for all other parameter values.
1. We passed in a `wait = ` parameter, asking the Splash server to wait for a few seconds to give the content time to render. This is an important consideration which we'll go into later in this document.
1. `splashr` passed on our command to the running Splash instance and the Splash server sent back a PNG file which the `splashr` package read in with the help of the `magick` package. If you're operating in RStudio you'll see the above image in the viewer. Alternatively, you can do:

```
image_browse(render_png(url = "https://analytics.usa.gov/", wait = 5))
```

to see the image if you're in another R environment. NOTE: web page screenshots can be captured in PNG or JPEG format by choosing the appropriate `render_` function.

Now that we've validated that we're getting the content we want, we can do something a bit more useful, like retrieve the HTML content of the page:

```
pg <- render_html(url = "https://analytics.usa.gov/")
pg
## {xml_document}
## <html lang="en">
## [1] <head>\n<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\n<!--\n\n Hi! Welcome to our source code.\n\n This d ...
## [2] <body>\n <!-- Google Tag Manager (noscript) -->\n<noscript>&lt;iframe src="https://www.googletagmanager.com/ns.html?id=GTM-MQSGZS"\ ...
```

The `render_html()` function behaves a great deal like `xml2::read_html()` function except that it's just retrieving the current web page [HTML DOM](https://www.w3schools.com/js/js_htmldom.asp). What do we mean by that? Well, unlike `httr::GET()` or `xml2::read_html()`, the Splash environment is a bona-fide browser environment, just like Chrome, Safari or Firefox. It's always running (until you shut down the Splash server). That means any active JS on the page can be modifying the content (like ticking a time counter or updating stock prices, etc). We didn't specify a `wait = ` delay this time, but it's generally a good idea to do that for very dynamic sites. This particular site seems update the various tables and charts every 10 seconds to show "live" stats.

We can work with that `pg` content just like we would with `rvest` / `xml2`. Let's look at the visitor total from the past 90 days:

```
library(rvest)

html_text(html_nodes(pg, "span#total_visitors"))
## [1] "2.37 billion"
```

If we tried to read that value with plain, ol' `read_html` here's what we'd get:

```
pg2 <- read_html("https://analytics.usa.gov/")
html_text(html_nodes(pg2, "span#total_visitors"))
## [1] "..."
```

Not exactly helpful.

So, with just a small example, we've seen that it's pretty simple to pull dyanmic content out of a web site with just a few more steps than `read_html()` requires.

But, we can do even more with these `render_` functions.

## Your Own Private 'Developer Tools'

Anyone performing scraping operations likely knows about each browser's "developer tools" environment. If you're not familiar with them you can get a quick primer [on their secrets](http://devtoolsecrets.com/) before continuing with this vignette.

The devtools inspector lets you see --- amongst other items -- network resources that were pulled down with the web page. So, while `read_html()` just gets the individual HTML file for a web site, its Splash devtools counterpart --- `render_har()` --- is pulling every image, JS file, CSS sheet, etc that can be rendered in QT WebKit. We can see what the USA.Gov Analytics site is making us load with it:

```
har <- render_har(url = "https://analytics.usa.gov/")
har
## --------HAR VERSION--------
## HAR specification version: 1.2
## --------HAR CREATOR--------
## Created by: Splash
## version: 3.0
## --------HAR BROWSER--------
## Browser: QWebKit
## version: 602.1
## --------HAR PAGES--------
## Page id: 1 , Page title: analytics.usa.gov | The US government's web traffic.
## --------HAR ENTRIES--------
## Number of entries: 29
## REQUESTS:
## Page: 1
## Number of entries: 29
## - https://analytics.usa.gov/
## - https://analytics.usa.gov/css/vendor/css/uswds.v0.9.1.css
## - https://analytics.usa.gov/css/public_analytics.css
## - https://analytics.usa.gov/js/vendor/d3.v3.min.js
## - https://analytics.usa.gov/js/vendor/q.min.js
## ........
## - https://analytics.usa.gov/data/live/top-downloads-yesterday.json
## - https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-bold-webfont.woff2
## - https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-regular-webfont.woff2
## - https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-light-webfont.woff2
## - https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-italic-webfont.woff2
```

A "HAR" is an HTTP Archive and `splashr` works with the R [`hartools`](https://CRAN.R-project.org/package=HARtools) package to provide access to the elements loaded with a Splash QT WebKit page request. We can see all of them if we perform a manual inspection:

```
for (e in har$log$entries) cat(e$request$url, "\n")
## https://analytics.usa.gov/
## https://analytics.usa.gov/css/vendor/css/uswds.v0.9.1.css
## https://analytics.usa.gov/css/public_analytics.css
## https://analytics.usa.gov/js/vendor/d3.v3.min.js
## https://analytics.usa.gov/js/vendor/q.min.js
## https://analytics.usa.gov/css/google-fonts.css
## https://analytics.usa.gov/js/vendor/uswds.v0.9.1.js
## https://analytics.usa.gov/js/index.js
## https://www.googletagmanager.com/gtm.js?id=GTM-MQSGZS
## https://www.google-analytics.com/analytics.js
## https://analytics.usa.gov/css/img/arrow-down.svg
## https://analytics.usa.gov/data/live/realtime.json
## https://analytics.usa.gov/data/live/today.json
## https://analytics.usa.gov/data/live/devices.json
## https://analytics.usa.gov/data/live/browsers.json
## https://analytics.usa.gov/data/live/ie.json
## https://analytics.usa.gov/data/live/os.json
## https://analytics.usa.gov/data/live/windows.json
## https://analytics.usa.gov/data/live/top-cities-realtime.json
## https://analytics.usa.gov/data/live/top-countries-realtime.json
## https://analytics.usa.gov/data/live/top-countries-realtime.json
## https://analytics.usa.gov/data/live/top-pages-realtime.json
## https://analytics.usa.gov/data/live/top-domains-7-days.json
## https://analytics.usa.gov/data/live/top-domains-30-days.json
## https://analytics.usa.gov/data/live/top-downloads-yesterday.json
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-bold-webfont.woff2
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-regular-webfont.woff2
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-light-webfont.woff2
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-italic-webfont.woff2
```

With just a visual inspection, we can see there are JSON files being loaded at some point that likely contain some of the data we're. The content for each of them can be available to us in the HAR object if we specify the `response_body = TRUE` parameter:

```
har <- render_har(url = "https://analytics.usa.gov/", wait = 5, response_body = TRUE)
for (e in har$log$entries) {
cat(sprintf("%s => [%s] is %s bytes\n",
e$request$url, e$response$content$mimeType,
scales::comma(e$response$content$size)))
}
## https://analytics.usa.gov/ => [text/html] is 19,718 bytes
## https://analytics.usa.gov/css/vendor/css/uswds.v0.9.1.css => [text/css] is 64,676 bytes
## https://analytics.usa.gov/css/public_analytics.css => [text/css] is 13,932 bytes
## https://analytics.usa.gov/js/vendor/d3.v3.min.js => [application/x-javascript] is 150,760 bytes
## https://analytics.usa.gov/js/vendor/q.min.js => [application/x-javascript] is 41,625 bytes
## https://analytics.usa.gov/css/google-fonts.css => [text/css] is 112,171 bytes
## https://analytics.usa.gov/js/vendor/uswds.v0.9.1.js => [application/x-javascript] is 741,447 bytes
## https://analytics.usa.gov/js/index.js => [application/x-javascript] is 29,868 bytes
## https://www.googletagmanager.com/gtm.js?id=GTM-MQSGZS => [] is 0 bytes
## https://www.google-analytics.com/analytics.js => [] is 0 bytes
## https://analytics.usa.gov/css/img/arrow-down.svg => [image/svg+xml] is 780 bytes
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-bold-webfont.woff2 => [font/woff2] is 23,368 bytes
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-regular-webfont.woff2 => [font/woff2] is 23,684 bytes
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-light-webfont.woff2 => [font/woff2] is 23,608 bytes
## https://analytics.usa.gov/css/vendor/fonts/sourcesanspro-italic-webfont.woff2 => [font/woff2] is 17,472 bytes
## https://analytics.usa.gov/data/live/realtime.json => [application/json] is 357 bytes
## https://analytics.usa.gov/data/live/today.json => [application/json] is 2,467 bytes
## https://analytics.usa.gov/data/live/devices.json => [application/json] is 625 bytes
## https://analytics.usa.gov/data/live/browsers.json => [application/json] is 4,697 bytes
## https://analytics.usa.gov/data/live/ie.json => [application/json] is 944 bytes
## https://analytics.usa.gov/data/live/os.json => [application/json] is 1,378 bytes
## https://analytics.usa.gov/data/live/windows.json => [application/json] is 978 bytes
## https://analytics.usa.gov/data/live/top-cities-realtime.json => [application/json] is 604,096 bytes
## https://analytics.usa.gov/data/live/top-countries-realtime.json => [application/json] is 15,179 bytes
## https://analytics.usa.gov/data/live/top-pages-realtime.json => [application/json] is 3,565 bytes
## https://analytics.usa.gov/data/live/top-domains-7-days.json => [application/json] is 1,979 bytes
## https://analytics.usa.gov/data/live/top-domains-30-days.json => [application/json] is 5,915 bytes
## https://analytics.usa.gov/data/live/top-downloads-yesterday.json => [application/json] is 25,751 bytes
```

I happen to know that the `devices.json` file has the visitor counts and we can retrieve it from the HAR object directly with some helpers:

```
har_entries(har)[[18]] %>%
get_response_body("text") %>%
jsonlite::fromJSON() %>%
str()
## List of 5
## $ name : chr "devices"
## $ query :List of 8
## ..$ start-date : chr "90daysAgo"
## ..$ end-date : chr "yesterday"
## ..$ dimensions : chr "ga:date,ga:deviceCategory"
## ..$ metrics : chr "ga:sessions"
## ..$ sort : chr "ga:date"
## ..$ start-index : int 1
## ..$ max-results : int 10000
## ..$ samplingLevel: chr "HIGHER_PRECISION"
## $ meta :List of 2
## ..$ name : chr "Devices"
## ..$ description: chr "90 days of desktop/mobile/tablet visits for all sites."
## $ totals :List of 2
## ..$ visits : num 2.37e+09
## ..$ devices:List of 3
## .. ..$ desktop: int 1303660363
## .. ..$ mobile : int 924913139
## .. ..$ tablet : int 137183761
## $ taken_at: chr "2017-08-27T10:00:02.175Z"
```

Now, if we wanted to make that request on our own, we could fiddle with the various `list` element details to build our own `httr` function, or we could make use of another helper to automatigally build an `httr` function for us:

```
library(httr)

req <- as_httr_req(har_entries(har)[[18]])
req() %>%
content(as="parsed") %>%
str()
## Output is the same as previous block
```

The text of the function is also put on the clipboard by default, so you can paste it right into a script or package for use later on:

```
httr::VERB(verb = "GET", url = "https://analytics.usa.gov/data/live/devices.json",
httr::add_headers(`User-Agent` = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/602.1 (KHTML, like Gecko) splash Version/9.0 Safari/602.1",
Accept = "application/json,*/*",
Referer = "https://analytics.usa.gov/"))
```

## The Full Monty

One final `render_` function is the `render_json()` function. Let's see what it does before explaining it:

```
json <- render_json(url = "https://analytics.usa.gov/", wait = 5, png = TRUE, response_body = TRUE)

str(json, 1)
## List of 10
## $ frameName : chr ""
## $ requestedUrl: chr "https://analytics.usa.gov/"
## $ geometry :List of 4
## $ png : chr "iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAYAAAC6uhUNAAAACXBIWXMAAA9hAAAPYQGoP6dpAAAgAElEQVR4AeydBZxUVRvGX7pTEBURBCWkVEQ"| __truncated__
## $ html : chr "<!DOCTYPE html><html lang=\"en\"><!-- Initalize title and data source variables --><head>\n <!--\n\n Hi! We"| __truncated__
## $ title : chr "analytics.usa.gov | The US government's web traffic."
## $ history :List of 1
## $ url : chr "https://analytics.usa.gov/"
## $ childFrames : list()
## $ har :List of 1
## ..- attr(*, "class")= chr [1:2] "har" "list"
## - attr(*, "class")= chr [1:2] "splash_json" "list"
```

The function name corresponds to the [Splash HTTP API call](https://splash.readthedocs.io/en/stable/api.html). It is actally returning JSON => a JSON object holding pretty much everything associated with the page. Think of it as a one-stop-shop function if you want a screen shot, page content and HAR resources with just one call.

Loading…
Cancel
Save