---
title: "Adding a custom header and footer to the landing page"
author: 
  - name: Kevin Rue-Albrecht
    affiliation:
    - University of Oxford
    email: kevin.rue-albrecht@imm.ox.ac.uk
output: 
  BiocStyle::html_document:
    self_contained: yes
    toc: true
    toc_float: true
    toc_depth: 2
    code_folding: show
date: "`r doc_date()`"
package: "`r pkg_ver('iSEEindex')`"
vignette: >
  %\VignetteIndexEntry{Adding custom header and footer to the landing page}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html
)
```

```{r, eval=!exists("SCREENSHOT"), include=FALSE}
SCREENSHOT <- function(x, ...) knitr::include_graphics(x)
```

```{r vignetteSetup, echo=FALSE, message=FALSE, warning = FALSE}
## Track time spent on making the vignette
startTime <- Sys.time()

## Bib setup
library("RefManageR")

## Write bibliography information
bib <- c(
    R = citation(),
    BiocStyle = citation("BiocStyle")[1],
    knitr = citation("knitr")[1],
    RefManageR = citation("RefManageR")[1],
    rmarkdown = citation("rmarkdown")[1],
    sessioninfo = citation("sessioninfo")[1],
    testthat = citation("testthat")[1],
    iSEEindex = citation("iSEEindex")[1]
)
```

# Custom header and footer

## Overview

By default, `r Biocpkg("iSEEindex")` creates a minimal landing page presenting users with a fluid row that contains two `shinydashboard::box()`:

- On the left, users can select a data set.
- On the right, users can select an initial configuration and launch the main app interface.

`r Biocpkg("iSEEindex")` offers the opportunity for app maintainers to add content above (i.e., header) and below (i.e., footer) that row.

That header and footer space may contain any valid UI element that will be displayed in the application UI *as is*.

## Implementation

The function `iSEEindex()` accepts header and footer content through its arguments `body.header=` and `body.footer=`.

We recommend wrapping header and footer content in `shiny::fluidRow()`, to fit naturally with the main fluid row (see above).

# Example

First, let us set up the core elements of a simple application (see `?iSEEindex`).

```{r, message=FALSE}
library("BiocFileCache")

##
# BiocFileCache ----
##

library(BiocFileCache)
bfc <- BiocFileCache(cache = tempdir())

##
# iSEEindex ----
##

dataset_fun <- function() {
  x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
  x$datasets
}

initial_fun <- function() {
  x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
  x$initial
}
```

Then, we design header and footer content, each wrapped in a `shiny::fluidRow()`.

```{r, message=FALSE}
library("shiny")
header <- fluidRow(shinydashboard::box(width = 12L, 
  column(width = 10,
    p(strong("Welcome to this demonstration app!")),
    p(
      "This is an example header that demonstrate how to use the functionality.",
      "A great place for branding and intros.",
    ),
    p("On the right, we demonstrate how other content such as images can be added to this header.")
  ),
  column(width = 2, img(src="www/iSEE.png", width = "100px", height = "120px"))
))
footer <- fluidRow(shinydashboard::box(width = 12L,
  p("This is a example footer. A great place for copyright statements and outros.", style="text-align: center;"),
  p(
    "© 2023 iSEE.",
    a("Artistic-2.0", href = "https://opensource.org/license/artistic-2-0/"),
    style="text-align: center;")
  ))
```

For the image file to be found, the containing directory must be added to the Shiny resource path as follows:

```{r, message=FALSE}
library("shiny")
addResourcePath("www", system.file(package = "iSEEindex"))
```

Finally, we supply the custom header and footer to `iSEEindex()`.

```{r, message=FALSE}
library("iSEEindex")
app <- iSEEindex(bfc, dataset_fun, initial_fun,
  body.header = header, body.footer = footer
)

if (interactive()) {
  shiny::runApp(app, port = 1234)
}
```

```{r, echo=FALSE}
SCREENSHOT("screenshots/header_footer.png", delay=20)
```


# Reproducibility

The `r Biocpkg("iSEEindex")` package `r Citep(bib[["iSEEindex"]])` was made possible thanks to:

* R `r Citep(bib[["R"]])`
* `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])`
* `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])`
* `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`
* `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])`
* `r CRANpkg("sessioninfo")` `r Citep(bib[["sessioninfo"]])`
* `r CRANpkg("testthat")` `r Citep(bib[["testthat"]])`

This package was developed using `r BiocStyle::Biocpkg("biocthis")`.


Code for creating the vignette

```{r createVignette, eval=FALSE}
## Create the vignette
library("rmarkdown")
system.time(render("header.Rmd", "BiocStyle::html_document"))

## Extract the R code
library("knitr")
knit("header.Rmd", tangle = TRUE)
```

Date the vignette was generated.

```{r reproduce1, echo=FALSE}
## Date the vignette was generated
Sys.time()
```

Wallclock time spent generating the vignette.

```{r reproduce2, echo=FALSE}
## Processing time in seconds
totalTime <- diff(c(startTime, Sys.time()))
round(totalTime, digits = 3)
```

`R` session information.

```{r reproduce3, echo=FALSE}
## Session info
library("sessioninfo")
options(width = 100)
session_info()
```



# Bibliography

This vignette was generated using `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])`
with `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])` and `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` running behind the scenes.

Citations made with `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`.

```{r vignetteBiblio, results = "asis", echo = FALSE, warning = FALSE, message = FALSE}
## Print bibliography
PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html"))
```

<!-- Links -->

[scheme-wikipedia]: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax
[iana-uri]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
[amazon-s3]: https://aws.amazon.com/s3/
[aws-cli]: https://aws.amazon.com/cli/