resources.qmd

# Resources {#sec-resources}

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
```


```{r}
#| label: co_box_tldr
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "b", 
  look = "default", hsize = "1.05", size = "1.0",
  header = "TLDR: Adding external files/resources", fold = TRUE,
  contents = "

<br>
  
- The **`inst/`** folder is used to store files/resources that are available when your package is installed (i.e., this folder *'will be copied recursively to the installation directory.'*)\n
  
- **`system.file()`** is the 'file path accessor' function we can use to locate files in the installed version of our app-package\n
  
- Use **`addResourcePath()`** with **`system.file()`** and **`inst/`** to include external files in your application.\n
    
**Workflow:** for a file located in `inst/www/file.png`:\n
  
\`\`\`r
# add path to app
addResourcePath('www', system.file('www', package = 'pkg'))
# use path without 'inst/' prefix in UI
img(src = 'www/shiny.png')
\`\`\`
  
  "
)
```

---

In this chapter, we'll cover how to include external resources (i.e., the images, CSS styling, JavaScript files, etc. previously served from the `www/` folder) in an app-package.

```{r}
#| label: shinypak_apps
#| echo: false
#| results: asis
#| eval: true
shinypak_apps(regex = "09", branch = "09.1_www")
```

When we launch our app, we see the Shiny logo (`shiny.png`) in the `www/` folder is not being loaded into the UI: 

```{r}
#| eval: false
#| code-fold: false
launch_app(run = 'p')
```

Shiny's internal functions previously automatically handled serving the contents of `www/`.[^load-support] Now that we’ve converted our application into a package, we’ll need to tell the application where to find these resources explicitly.[^external-common-problem]

![`www/shiny.png` is not visible when we launch the app](images/external_initial_launch_app.png){width='100%' fig-align='center'}


[^load-support]: "*The `www/` folder is a special one for Shiny. Resources your app may link to, such as images—or in this case, scripts—are placed in the `www/` folder. Shiny then knows to make these files available for access from the web browser.*" - [Shiny documentation](https://shiny.posit.co/r/articles/build/css/#other-methods)

[^external-common-problem]: This is a common problem developers encounter when converting shiny app into app-packages. See [this popular thread](https://community.rstudio.com/t/shiny-app-as-a-package-directory-structure-and-www-folder/135323/8) on Posit Community.

## Package files {.unnumbered}

While developing, we get used to accessing and interacting with our package files from the **Files** pane or **Explorer** window:

:::{.panel-tabset}

### RStudio ![](images/rstudio-icon.png){height=20}

!['Source' files for `sap` in **Files** pane](images/external_files_pane.png){width='80%'}

### Positron ![](images/positron.png){height=20}

!['Source' files for `sap` in **Explorer** window](images/external_positron_explorer_pane.png){width='80%'}

:::

However, as noted in the [data](data.qmd) chapter, the aren't the files in our *installed* package. We can use  `system.file()` and `fs::dir_tree()` to print a folder tree of our *installed* package files:

::: {layout="[50, 50]"}

::: {style="font-size: 0.90em;"} 

```{verbatim}
sap/
├── DESCRIPTION 
├── NAMESPACE 
├── R 
│   ├── data.R
│   ├── display_type.R
│   ├── mod_scatter_display.R
│   ├── mod_var_input.R
│   ├── launch_app.R
│   ├── movies_server.R
│   ├── movies_ui.R
│   └── scatter_plot.R
├── README.md
├── app.R
├── data 
│   ├── movies.RData
│   └── movies.rda
├── inst
│   └── extdata 
│       └── movies.fst
├── man
│   ├── display_type.Rd
│   ├── mod_scatter_display_server.Rd
│   ├── mod_scatter_display_ui.Rd
│   ├── mod_var_input_server.Rd
│   ├── mod_var_input_ui.Rd
│   ├── movies.Rd
│   ├── launch_app.Rd
│   ├── movies_server.Rd
│   ├── movies_ui.Rd
│   └── scatter_plot.Rd
├── sap.Rproj
└── www
    └── shiny.png
```

:::

::: {style="font-size: 0.90em;"} 

```{verbatim}
sap/
├── DESCRIPTION # <1>
├── INDEX
├── Meta # <2>
│   ├── Rd.rds
│   ├── data.rds
│   ├── features.rds
│   ├── hsearch.rds
│   ├── links.rds
│   ├── nsInfo.rds
│   └── package.rds # <2>
├── NAMESPACE # <3>
├── R # <4>
│   ├── sap
│   ├── sap.rdb
│   └── sap.rdx # <4>
├── data # <5>
│   ├── Rdata.rdb
│   ├── Rdata.rds
│   └── Rdata.rdx # <5>
├── extdata # <6>
│   └── movies.fst
├── help # <7>
│   ├── AnIndex
│   ├── aliases.rds
│   ├── sap.rdb
│   ├── sap.rdx
│   └── paths.rds # <7>
└── html # <8>
    ├── 00Index.html
    └── R.css # <8>
```
1. `DESCRIPTION` is in *both* source and installed versions, and format remains unchanged. 
2. Metadata files, such as `data.rds` and `package.rds`, are created in the `Meta/` directory  
3. `NAMESPACE` is in *both* source and installed versions, and format remains unchanged. 
4. R code in the `R/` directory is byte-compiled for improved performance, stored in `.rdb` and `.rdx` files.  
5. Datasets in the `data/` directory are serialized into a lazyload database and stored as `.rdb` and `.rdx` files in the `R/` directory.  
6. The `extdata/` folder is in *both* source and installed versions, and the `movies.fst` file remains unchanged.  
7.  `.Rd` files are processed into binary help files  
8. HTML and styling for help index  


:::

:::

Very few of the source folders and files we’ve been working with remain in the installed version of our package. An exception is the `movies.fst` file (stored in `inst/extdata/`). Hopefully seeing these two folder trees side-by-side demystifies what `devtools::install()` does. 

When we want to add non-R package files to our app (like the `shiny.png` logo), we store these files in the `inst/`folder and access them with `system.file()`.[^inst-r-pkgs] 

[^inst-r-pkgs]: Read more about sub-directories to avoid in `inst/` in [R Packages, 2ed](https://r-pkgs.org/misc.html#sec-misc-inst).

> "*The contents of the `inst/` subdirectory will be copied recursively to the installation directory. Subdirectories of `inst/` should not interfere with those used by R (currently, `R/`, `data/`, `demo/`, `exec/`, `libs/`, `man/`, `help/`, `html/` and `Meta/`, and earlier versions used `latex/`, `R-ex/`).*" - [Writing R extensions, Package subdirectories](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Package-subdirectories)

```{r}
#| label: co_box_install
#| echo: false
#| results: asis
#| eval: true
#| include: true
co_box(
  color = "b", fold = TRUE,
  look = "default", hsize = "1.15", size = "1.10",
  header = "Other Uses of the `inst/` folder", 
  contents = "
I found exploring the structure of the `inst/` folder in other packages incredibly helpful in understanding how to use this directory for package development. For example, the `inst/examples/` folder in the [`shiny` package](https://github.com/rstudio/shiny) holds a variety of Shiny apps:
  
\`\`\` sh
/path/to/install/Library/R/x86_64/4.2/library/shiny/examples/
├── 01_hello
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 02_text
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 03_reactivity
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 04_mpg
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 05_sliders
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 06_tabsets
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 07_widgets
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 09_upload
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
├── 10_download
│   ├── DESCRIPTION
│   ├── Readme.md
│   └── app.R
└── 11_timer
    ├── DESCRIPTION
    ├── Readme.md
    └── app.R
\`\`\`
  
These files are used in [`shiny::runExample()`](https://github.com/rstudio/shiny/blob/9a35b01e23fe9e95e69aeb3624554b58c7a2b74f/R/runapp.R#L477)):
  
\`\`\` r
shiny::runExample(example = '11_timer')
\`\`\`
  

")
```

## Image files {#sec-resources-image-files}

To include the contents of `www/` in our app-package, we’ll need to move `www/` into `inst/`, and then access its contents with `system.file()`.[^inst-view]

[^inst-view]: The key takeaway here is that the `inst/` subfolders and files are available *unchanged* in the installed version (with the `inst/` folder omitted.).

### [`system.file()`]{style="font-size: 0.95em;"}

We used `system.file()` in the [Data chapter](data.qmd) (see @sec-data-system-file) to access the `movies.fst` file in `inst/extdata/`. `system.file()` gives us access to the package files _on installation_ (i.e., the files we saw in the folder tree above).


```{r}
#| eval: false 
#| code-fold: show
#| code-summary: 'system.file() is accessing movies.fst from the installed location'
fst::read_fst(
  path = system.file("extdata/", "movies.fst", 
                     package = "sap")
  )
```

In essence, `movies.fst` has ‘source’ package and ‘installed’ locations.

#### Source package files {.unnumbered}


```{bash}
#| eval: false 
#| code-fold: false
inst/ # <1>
  └── extdata/
        └── movies.fst # <1>
```
1. What we see

#### Installed package files {.unnumbered}

```{bash}
#| eval: false 
#| code-fold: false
└── extdata/ # <1>
      └── movies.fst # <1>
```
1. What R sees


### [`addResourcePath()`]{style="font-size: 0.95em;"} {#sec-resources-add-resource-path}

The `addResourcePath()` function will add a “*directory of static resources to Shiny’s web server.*”[^add-resource-path-4] In `sap`, we want to add the `www` directory, which includes the `shiny.png` file.

[^add-resource-path-4]: You can read more about adding external resources in the [documentation for `addResourcePath()`](https://shiny.posit.co/r/reference/shiny/latest/resourcepaths).

:::{layout="[10,-1, 10]" layout-valign="top"}

#### [Current `www` location]{style="font-size: 0.95em;"} {.unnumbered}

``` sh
├── inst
│   └── extdata
│       └── movies.fst
└── www
    └── shiny.png
```

#### [New `www` location]{style="font-size: 0.95em;"} {.unnumbered}

``` sh
inst/
  ├── extdata/
  │   └── movies.fst
  └── www/
      └── shiny.png
```

:::

In `R/movies_ui.R`, we’ll include the `addResourcePath()` at the top of the `tagList()` and reference the image in `img()` using only the subfolder in the path:

```{r}
#| eval: false 
#| code-fold: show 
#| code-summary: 'show/hide movies_ui()'
movies_ui <- function() {
  addResourcePath(
    prefix = "www", # <1>
    directoryPath = system.file("www", package = "sap") # <2>
  )
  tagList(
    bslib::page_fillable(
      h1("Movie Reviews"),
      bslib::layout_sidebar(
        sidebar =
          bslib::sidebar(
            title = tags$h4("Sidebar inputs"),
            img(
              src = "www/shiny.png", # <3>
              height = 60,
              width = 55,
              style = "margin:10px 10px"
            ),
            mod_var_input_ui("vars")
          ),
        bslib::card(
          full_screen = TRUE,
          bslib::card_header(
            tags$h4("Scatter Plot")
          ),
          mod_scatter_display_ui("plot"),
          bslib::card_footer(
            tags$blockquote(
              tags$em(
                tags$p(
                  "The data for this application comes from the ",
                  tags$a("Building web applications with Shiny",
                    href = "https://rstudio-education.github.io/shiny-course/"
                  ),
                  "tutorial"
                )
              )
            )
          )
        )
      )
    )
  )
}
```
1. Prefix (or folder name) of installed location  
2. Path to installed package files  
3. Reference to installed package image file   

The application includes the image file after loading, documenting, and installing our package:

```{r}
#| label: hot_key_load_all_00
#| echo: false
#| results: asis
#| eval: true
hot_key("all")
```

```{r}
#| eval: false 
#| code-fold: false
library(sap)
launch_app(run = 'p')
```


![`inst/www` accessible with `addResourcePath()`](images/external_www_launch_app.png){width='100%' fig-align='center'}


We can also use `inst/` to store alternate image files and configure the UI to display a different layout. This method ensures our app has the exact same functionality, but a different UI layout.[^layouts-git] 

[^layouts-git]: As the development of your application progresses, you can (and should) keep different versions of your application in separate Git branches. But I've also found using the `inst/` folder for those early stages of developing is helpful. 

```{r}
#| label: co_box_bslib
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "o", 
  look = "default", hsize = "1.10", size = "1.05",
  header = "Dependency watch!",
  contents = "
`bslib` is a dependency of `shiny`, so we don't need to import this with `usethis::use_package()` (see output from `pak::pkg_deps_tree('shiny')` below)

\`\`\`sh
shiny 1.9.1 ✨                                                             
├─httpuv 1.6.15 ✨🔧
│ ├─later 1.3.2 ✨🔧
│ │ ├─Rcpp 1.0.13 ✨🔧
│ │ └─rlang 1.1.4 ✨🔧
│ ├─promises 1.3.0 ✨🔧
│ │ ├─fastmap 1.2.0 ✨🔧
│ │ ├─later
│ │ ├─magrittr 2.0.3 ✨🔧
│ │ ├─R6 2.5.1 ✨
│ │ ├─Rcpp
│ │ └─rlang
│ ├─R6
│ └─Rcpp
├─mime 0.12 ✨🔧
├─jsonlite 1.8.8 ✨🔧
├─xtable 1.8-4 ✨
├─fontawesome 0.5.2 ✨
│ ├─rlang
│ └─htmltools 0.5.8.1 ✨🔧
│   ├─base64enc 0.1-3 ✨🔧
│   ├─digest 0.6.36 ✨🔧
│   ├─fastmap
│   └─rlang
├─htmltools
├─R6
├─sourcetools 0.1.7-1 ✨🔧
├─later
├─promises
├─crayon 1.5.3 ✨
├─rlang
├─fastmap
├─withr 3.0.1 ✨
├─commonmark 1.9.1 ✨🔧
├─glue 1.7.0 ✨🔧
├─bslib 0.8.0 ✨
│ ├─base64enc
│ ├─cachem 1.1.0 ✨🔧
│ │ ├─rlang
│ │ └─fastmap
│ ├─fastmap
│ ├─htmltools
│ ├─jquerylib 0.1.4 ✨
│ │ └─htmltools
│ ├─jsonlite
│ ├─lifecycle 1.0.4 ✨
│ │ ├─cli 3.6.3 ✨🔧
│ │ ├─glue
│ │ └─rlang
│ ├─memoise 2.0.1 ✨
│ │ ├─rlang
│ │ └─cachem
│ ├─mime
│ ├─rlang
│ └─sass 0.4.9 ✨🔧
│   ├─fs 1.6.4 ✨🔧
│   ├─rlang
│   ├─htmltools
│   ├─R6
│   └─rappdirs 0.3.3 ✨🔧
├─cachem
└─lifecycle

Key:  ✨ new | 🔧 compile

\`\`\`

",
  fold = TRUE
)
```

The updated `movies_ui()` function below has an optional [`bslib`](https://rstudio.github.io/bslib/index.html) argument that will change the layout an display an alternate image (stored in `inst/www/bootstrap.png`).

```{r}
#| eval: false 
#| code-fold: show 
#| code-summary: 'show/hide updated movies_ui()'
#' User Interface for the Movies Review Application
#'
#' Creates the user interface (UI) for the Movies Review application, which
#' allows users to create customizable scatter plots based on movie data.
#' 
#' @param bslib View bslib logo?
#'
#' @return A Shiny `tagList` object containing the UI elements.
#'
#' @section Details:
#' The interface is built using [`bslib`](https://rstudio.github.io/bslib/)
#' - **Page (fillable)**: [`bslib::page_fillable()`](https://rstudio.github.io/bslib/reference/page_fillable.html)
#'   displays the app title.
#' - **Sidebar**: [`bslib::layout_sidebar()`](https://rstudio.github.io/bslib/reference/sidebar.html)
#'   includes a logo and the variable
#'   selection module.
#'   ([`mod_var_input_ui`]).
#' - **Card**: [`bslib::card()`](https://rstudio.github.io/bslib/reference/card.html)
#'   displays the scatter plot module
#'   ([`mod_scatter_display_ui`]).
#'
#' @seealso
#' - [`movies_server()`] for the server logic of the app.
#' - [`mod_var_input_ui()`] and [`mod_scatter_display_ui()`] for the modules
#'   included in the UI.
#'
#' @family **Application Components**
#'
#' @examples
#' if (interactive()) {
#'   shiny::shinyApp(ui = movies_ui(), server = movies_server)
#' }
#'
#' @export
movies_ui <- function(bslib = FALSE) {
  addResourcePath( # <1>
    prefix = 'www', 
    directoryPath = system.file('www', package = 'sap')) # <1>
  if (isFALSE(bslib)) {
  tagList( # <2>
    bslib::page_fillable(
      h1("Movie Reviews"),
      bslib::layout_sidebar(
        sidebar =
          bslib::sidebar(
            title = tags$h4("Sidebar inputs"),
            img(
              src = "www/shiny.png",
              height = 60,
              width = 55,
              style = "margin:10px 10px"
            ),
            mod_var_input_ui("vars")
          ),
        bslib::card(
          full_screen = TRUE,
          bslib::card_header(
            tags$h4("Scatter Plot")
          ),
          bslib::card_body(fillable = TRUE,
            mod_scatter_display_ui("plot")
          ),
          bslib::card_footer(
            tags$blockquote(
              tags$em(
                tags$p(
                  "The data for this application comes from the ",
                  tags$a("Building web applications with Shiny",
                    href = "https://rstudio-education.github.io/shiny-course/"
                  ),
                  "tutorial"
                )
              )
            )
          )
        )
      )
    )
  ) # <2>
  } else {
    tagList( # <3>
      bslib::page_fillable(
        title = "Movie Reviews (bslib)",
        theme = bslib::bs_theme(
          bg = "#101010",
          fg = "#F6F5F5",
          primary = "#EE6F57",
          secondary = "#32E0C4",
          success = "#FF4B5C",
          base_font = sass::font_google("Ubuntu"),
          heading_font = sass::font_google("Ubuntu")
        ),
        bslib::layout_sidebar(
          sidebar = bslib::sidebar(
            open = TRUE,
            mod_var_input_ui("vars")
          ),
          bslib::card(
            full_screen = TRUE,
                bslib::card_header(
                  img(src = "www/bootstrap.png", # <4>
                  height = 80,
                  width = 100,
                  style = "margin:10px 10px")
              ),
             bslib::card_body(fillable = TRUE,
                 mod_scatter_display_ui("plot")
            )
          )
        )
      )
    ) # <3>
  }
} 
```
1. Include `inst/www` resources  
2. Original `bslib` layout  
3. New `bslib` layout   
4. Reference to alternate image (in `inst/www/bootstrap.png`)   

The new `bslib` argument in our updated `moves_ui()` function toggles between the two UI options. We should also add an `app` argument to `launch_app()` to handle the two UI options: 

```{r}
#| label: rd-launch-app-bslib
#| eval: false 
#| code-fold: show 
#| code-summary: 'show/hide updated launch_app()'
#' Movies app standalone function
#'
#' Wrapper function for `shinyApp()`
#'
#' @param app which app to run. Options are: 
#'  * `"movies"` = Default app  
#'  * `"bslib"` = Alternative `bslib` layout 
#' @param options arguments to pass to `options()`
#' @param run where to launch app:
#'  * `p` = launch in viewer pane
#'  * `b` = launch in external browser
#'  * `w` = launch in window
#' @param ... arguments passed to UI
#'
#' @return shiny app
#'
#' @seealso [mod_var_input_ui()], [mod_var_input_server()], [mod_scatter_display_ui()], [mod_scatter_display_server()]
#'
#'
#' @export
#' 
#' @import shiny
#' 
launch_app <- function(app = "movies", options = list(), run = "p", ...) {
  if (interactive()) {
    display_type(run = run)
  }
  if (app == "bslib") {
    shinyApp(
      ui = movies_ui(bslib = TRUE),
      server = movies_server,
      options = options
    )
  } else {
    shinyApp(
      ui = movies_ui(...),
      server = movies_server,
      options = options
    )
  }
}
```

Now we can load, document, and build the package and confirm `app = "bslib"` works:

```{r}
#| label: dev_key_load_all_01
#| echo: false
#| results: asis
#| eval: true
hot_key("all")
```

```{r}
#| eval: false 
#| code-fold: false
launch_app(app = 'bslib')
```

This alternate version of `launch_app()` uses the same modules and utility functions as the previous versions but when `app = "bslib"`, the app displays the alternate UI layout:

![`inst/www/bootstrap.png` image from `movies_ui()`](images/external_bslib_launch_app.png){width='100%' fig-align='center'}


The `inst/` folder is a versatile tool for storing various files needed in our application (logos or images, CSS styling, JavaScript functions, HTML, etc.). The example above was simple, but using `inst/` to hold resources for alternate UIs that can be displayed with a single argument is handy for demoing versions for stakeholders.

## Data files {#sec-resources-inst-dev}

It is not uncommon to develop an application that can handle data from multiple sources. In these situations, we can sometimes store the alternative data files in the `inst/` folder.[^external-data]

[^external-data]: We covered external data in @sec-data-inst-extdata. 

### A [`tidy-movies`]{style="font-size: 0.95em;"} app

We'll create an alternative application in `sap` that uses a tidy version of the [`ggplot2movies` data](https://cran.r-project.org/web/packages/ggplot2movies/index.html), which we create using a function stored in the [`data-raw/tidy_movies.R`](https://github.com/mjfrigaard/sap/blob/09.2_inst-tidy-movies/data-raw/tidy_movies.R) file.[^raw-data]

```{r}
#| include: false
#| eval: false 
#| code-fold: true 
#| code-summary: 'show/hide data-raw/tidy_movies.R'
## code to prepare the `tidy_movies` dataset goes here
# load packages --------------------
library(fst)
make_tidy_ggp2_movies <- function(movies_data_url) {
  movies_data <- read.csv(file = movies_data_url)
  # specify genre columns
  genre_cols <- c(
    "Action", "Animation",
    "Comedy", "Drama",
    "Documentary", "Romance",
    "Short"
  )
  # calculate row sum for genres
  movies_data$genre_count <- rowSums(movies_data[, genre_cols])
  # create aggregate 'genres' for multiple categories
  movies_data$genres <- apply(
    X = movies_data[, genre_cols],
    MARGIN = 1,
    FUN = function(row) {
      genres <- names(row[row == 1])
      if (length(genres) > 0) {
        return(paste(genres, collapse = ", "))
      } else {
        return(NA)
      }
    }
  )
  # format variables
  movies_data$genre_count <- as.integer(movies_data$genre_count)
  movies_data$genre <- ifelse(test = movies_data$genre_count > 1,
    yes = "Multiple genres",
    no = movies_data$genres
  )
  movies_data$genre <- as.factor(movies_data$genre)
  movies_data$mpaa <- factor(movies_data$mpaa,
    levels = c("G", "PG", "PG-13", "R", "NC-17"),
    labels = c("G", "PG", "PG-13", "R", "NC-17")
  )

  # reduce columns to only those in graph
  movies_data[, c(
    "title", "year", "length", "budget",
    "rating", "votes", "mpaa", "genre_count",
    "genres", "genre"
  )]
}

tidy_movies <- make_tidy_ggp2_movies("https://raw.githubusercontent.com/hadley/ggplot2movies/master/data-raw/movies.csv")

# save to inst/tidy-data/
fst::write_fst(x = tidy_movies, path = "inst/tidy-data/tidy_movies.fst")
```

[^raw-data]: We covered the `data-raw/` folder in the [Data chapter](data.qmd), and you can read more about it [here in R packages, 2ed](https://r-pkgs.org/data.html#sec-data-data-raw.)

We can place the application modules, UI, and server functions in [`inst/tidy-movies/R`](https://github.com/mjfrigaard/sap/tree/09.3_inst-dev/inst/tidy-movies/R):

```{bash}
#| eval: false
#| code-fold: false
inst
├── extdata
│   └── movies.fst
├── tidy-movies # <1>
│   ├── R # <2>
│   │   ├── devServer.R
│   │   ├── devUI.R
│   │   ├── dev_mod_scatter.R
│   │   └── dev_mod_vars.R # <2>
│   ├── app.R # <3>
│   ├── imdb.png # <4>
│   └── tidy_movies.fst # <5>
└── www
    ├── bootstrap.png
    └── shiny.png

5 directories, 10 files
```
1. Tidy movies app folder  
2. App ui, server, and modules   
3. Launch `tidy-movies` app
4. Alternate image/logo  
5. Alternate data  

All of the functions from `sap` are available in the `tidy-movies/` app with explicit namespacing (i.e., `sap::fun()`):

1. `dev_mod_vars_ui()` contains choices for the columns in the `tidy_movies` data, but there's no need to rewrite the `mod_var_input_server()` function.[^export-modules]

2. The `dev_mode_scatter` module functions have been rewritten to add functionality for importing the `tidy_movies.fst` data file and an option to removing missing values from the graph.  

3. [`inst/tidy-data/app.R`](https://github.com/mjfrigaard/sap/blob/09.3_inst-dev/inst/tidy-data/app.R) contains a call to `shinyApp()` and any other packages we'll need to launch the application. The data and alternative image file can be placed in the root folder (with the `app.R` file):

[^export-modules]: This requires exporting `mod_var_input_server()` with `@export` in the `R/` folder.

### Launching [`tidy-movies`]{style="font-size: 0.95em;"} {#sec-resources-tidy-movies-launch}

Finally, we'll launch the `tidy_movies` data app with the `app` argument in our standalone function. This conditional argument is similar to the `app = "bslib"` option, but we use  `shinyAppDir()` to launch the app stored in `inst/tidy-movies` (which we locate with `system.file()`).

```{r}
#| eval: false 
#| code-fold: show
#| code-summary: 'show/hide R/launch_app.R'
#' Launch the Movies Review Application
#'
#' Starts the Movies Review Shiny application, which provides a customizable
#' scatter plot interface for analyzing movie data.
#' 
#' @param app which app to run. Options are:
#'  * `"movies"` = Default app  
#'  * `"bslib"` = Alternative `bslib` layout 
#'  * `"ggp2"` = `ggplot2movies` (tidy) data app.
#' @param options arguments to pass to `options()`
#' @param run where to launch app:
#'  * `p` = launch in viewer pane
#'  * `b` = launch in external browser
#'  * `w` = launch in window
#' @param ... arguments passed to UI 
#'
#' @return A **Shiny application** object.
#'
#' @section Details:
#' The application uses:
#' - **UI**: Defined in [`movies_ui()`].
#' - **Server Logic**: Defined in [`movies_server()`].
#'
#' @seealso
#' - [`movies_ui()`] for the user interface.
#' - [`movies_server()`] for the server logic.
#'
#' @family **Standalone Application**
#' 
#' @details
#' See the [ggplot2movies](https://github.com/hadley/ggplot2movies) package.
#' 
#'
#' @examples
#' if (interactive()) {
#'   launch_app()
#' }
#'
#' @export
#' 
#' @import shiny
#' 
launch_app <- function(app = "movies", options = list(), run = "p", ...) {
  if (interactive()) {
    display_type(run = run)
  }
  if (app == "bslib") {
    shinyApp(
      ui = movies_ui(bslib = TRUE),
      server = movies_server,
      options = options
    )
  } else if (app == "ggp2") {
      shinyAppDir(
        appDir = system.file("tidy-movies",
          package = "sap"
      ),
      options = options
      )
  } else {
    shinyApp(
      ui = movies_ui(...),
      server = movies_server,
      options = options
    )
  }
}
```

<br>

After loading, documenting, and installing, we’ll run the tidy `ggplot2movies::movies` data app:

```{r}
#| label: dev_key_load_all_02
#| echo: false
#| results: asis
#| eval: true
hot_key("all")
```


```{r}
#| code-fold: false
#| eval: false
launch_app(app = 'ggp2')
```

![`inst/tidy-movies/` app with `dev_movies_ui()`](images/external_ggp2_launch_app.png){width='100%' fig-align='center'}

```{r}
#| label: co_box_themes_colors
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g", 
  look = "default", hsize = "1.10", size = "1.05",
  header = "Using colors and themes",
  contents = "Using different colors and themes for alternative applications can be a quick and easy way to differentiate the versions of your application.")
```


## Quarto apps {#sec-resources-inst-quarto}

Shiny apps can also be built inside [Quarto documents](https://quarto.org/docs/interactive/shiny/), in which case we could also use the `inst/` folder to store and load resources (images, CSS, etc.).

The `inst/quarto/` folder contains a Quarto version of our movies app:

```{bash}
#| eval: false 
#| code-fold: false
inst/quarto
├── _quarto.yml
├── index.qmd
└── www
    ├── quarto.png
    └── styles.scss

1 directory, 4 files
```

The `_quarto.yml` file contains project metadata for the app[^proj-yaml], and the `www/` folder contains an image file and a CSS file.

```yml
title: "Quarto Movies App"

format:
  html:
    embed-resources: true
```

[^proj-yaml]: Read more about the `_quarto.yml` configuration file in the [Quarto documentation.](https://quarto.org/docs/projects/quarto-projects.html#project-metadata)

### Shiny documents 

In `index.qmd`, we can specify `server: shiny` in the YAML header to let Quarto know we want the document to be interactive:

:::{style='font-size: 0.90em;'}

```yml
---
title: Quarto Movies App
format:
  html:
    page-layout: full
    embed-resources: true
    theme:
      - united
      - www/styles.scss
    
server: shiny
---
```

:::

The other options we've included in our YAML header are [`page-layout`](https://quarto.org/docs/output-formats/page-layout.html#page-layout) (for customizing the layout of each element), [`embed-resources`](https://quarto.org/docs/output-formats/html-publishing.html#standalone-html) (to create a standalone HTML document), and [`theme`](https://quarto.org/docs/output-formats/html-themes.html) (we're using a Bootstrap 5 theme with custom CSS).

To set up our Quarto/Shiny app, we should include a code chunk with `context: setup` near the top of the document. We can use the image files in `inst/quarto/www` by adding a call to `addResourcePath()` in the `setup` chunk: 

{{< include _quarto_setup.qmd >}}

Note the `context: setup` chunk includes options and themes (I'm using the [`thematic` package](https://rstudio.github.io/thematic/) to set a theme for the `ggplot2` graph in our app).

Using `page-layout: full` in the YAML header lets us use a variety of `panel` options for each code chunk. For example, we'll place the variable input module in a code chunk with the `input` option,[^export-mod-var-input-ui] the display module with the `center` option,[^export-mod-scatter-display-ui] and the data/Quarto attribution in the `fill` option.[^page-layout]

[^export-mod-var-input-ui]: This requires exporting `mod_var_input_ui()` with `@export` in the `R/` folder.

[^export-mod-scatter-display-ui]: This requires exporting `mod_scatter_display_ui()` with `@export` in the `R/` folder.

[^page-layout]: Read more about `page-layout` in the [Quarto documentation](https://quarto.org/docs/output-formats/page-layout.html#page-layout)  

{{< include _quarto_panel.qmd >}}

The `context: setup` and `panel` option code chunks will execute when the document is rendered. However, any code chunk with  `context: server` will execute when the document is _served_ (not when it is rendered).[^export-server-module-funs]

[^export-server-module-funs]: This requires exporting `mod_var_input_server()` and `mod_scatter_display_server()` with `@export` in the `R/` folder.

{{< include _quarto_server.qmd >}}

These chunks are run in separate R sessions, meaning we cannot access variables created in the first chunk within the second and vice versa (similar to to the `movies_ui()`, and `movies_server.R()`).

To render our Quarto Shiny app, we can use the **Run Document**/**Preview** button or running the following commands in the **Terminal**: 

```sh
quarto serve /<path>/<to>/sap/inst/quarto/index.qmd
```

![Movies Quarto Shiny App](images/external_quarto_app.png){width='100%' fig-align='center'}

We can also launch the quarto app using the following R commands:

```{r}
#| eval: false 
#| code-fold: false
quarto::quarto_preview(
  file = system.file("quarto", "index.qmd", 
                     package = "sap"),
  render = "all",
  browse = utils::browseURL,
  watch = TRUE
)
```

### Launching [`inst/quarto`]{style="font-size: 0.95em;"}

To launch our Quarto application from `inst/quarto`, we'll change the `app` argument again in `launch_app()`:

```{r}
#| eval: false 
#| code-fold: show 
#| code-summary: 'show/hide launch_app()'
#' Launch the Movies Review Application
#'
#' Starts the Movies Review Shiny application, which provides a customizable
#' scatter plot interface for analyzing movie data.
#' 
#' @param app which app to run. Options are:
#'  * `"movies"` = Default app  
#'  * `"bslib"` = Alternative `bslib` layout 
#'  * `"ggp2"` = `ggplot2movies` (tidy) data app.
#'  * `"quarto"` = Quarto movies app.
#' @param options arguments to pass to `options()`
#' @param run where to launch app:
#'  * `p` = launch in viewer pane
#'  * `b` = launch in external browser
#'  * `w` = launch in window
#' @param ... arguments passed to UI 
#'
#' @return A **Shiny application** object.
#'
#' @section Details:
#' The application uses:
#' - **UI**: Defined in [`movies_ui()`].
#' - **Server Logic**: Defined in [`movies_server()`].
#'
#' @seealso
#' - [`movies_ui()`] for the user interface.
#' - [`movies_server()`] for the server logic.
#'
#' @family **Standalone Application**
#' 
#' @details
#' See the [ggplot2movies](https://github.com/hadley/ggplot2movies) package.
#' 
#'
#' @examples
#' if (interactive()) {
#'   launch_app()
#' }
#' 
#' @export
#' 
#' @import shiny
#' 
launch_app <- function(app = "movies", options = list(), run = "p", ...) {
  if (interactive()) {
    display_type(run = run)
  }
  if (app == "bslib") {
    shinyApp(
      ui = movies_ui(bslib = TRUE),
      server = movies_server,
      options = options
    )
  } else if (app == "ggp2") {
      shinyAppDir(
        appDir = system.file("tidy-movies",
          package = "sap"
      ),
      options = options
      )
  } else if (app == "quarto") {
      quarto::quarto_preview(
        system.file("quarto", "index.qmd",
            package = "sap" ), 
        render = "all")
  } else {
    shinyApp(
      ui = movies_ui(...),
      server = movies_server,
      options = options
    )
  }
}
```

Now we can load, document, and build the package:

```{r}
#| label: quarto_key_load_all
#| echo: false
#| results: asis
#| eval: true
hot_key("all")
```

Launching the application now just requires a single argument: 

```{r}
#| eval: false 
#| code-fold: false
launch_app(app = "quarto")
```


## Production {#sec-resources-inst-prod}

Finally, it's also possible to have a folder dedicated for deploying a production version of our application from our app-package. I recommend naming this folder something like `inst/prod/` or `inst/deploy`, and it can contain a version of your application that's 'fit for public consumption.' In `inst/prod/app` I've created an `app.R` file:

```{bash}
#| eval: false
#| code-fold: false
inst/
  └── prod/
      └── app
          └── app.R
          
2 directories, 1 file
```

### [`prod/app/app.R`]{style="font-size: 0.95em;"} 

`app.R` includes a call to `launch_app()` with the `app` and `options` arguments:

```{r}
#| eval: false
#| code-fold: show 
#| code-summary: 'show/hide prod/app/app.R'
library(sap)
launch_app(app = "bslib", options = list(test.mode = FALSE))
```

I'll use the `"bslib"` version from above to differentiate it from the other applications in `sap`. 

### [Deploying `inst/prod/`]{style="font-size: 0.95em;"} {#sec-resources-prod-deploy}

Back in the our `app.R` file, we'll use `shinyAppDir()` and `system.file()` to return the app object from `prod/app/app.R`:

```{r}
#| eval: false
#| code-fold: show 
#| code-summary: 'show/hide app.R'
withr::with_options(new = list(shiny.autoload.r = FALSE), code = { # <1>
  if (!interactive()) {
    sink(stderr(), type = "output")
    tryCatch(
      expr = {
        library(sap)
      },
      error = function(e) {
        pkgload::load_all()
      }
    )
    shinyAppDir(appDir = system.file("prod/app", package = "sap")) # <2>
  } else {
    pkgload::load_all()
  }
  launch_app(options = list(test.mode = FALSE), run = 'p')
})
```
1. Set option to turn off `loadSupport()`
2. Create shiny object from `prod/app`   

```{r}
#| label: dev_key_load_all_03
#| echo: false
#| results: asis
#| eval: true
hot_key("all")
```

To deploy the app, call `rsconnect::deployApp()` in the console and supply an `appName`:

```{r}
#| eval: false
#| code-fold: false 
rsconnect::deployApp(appName = 'movie-reviews-prod')
```

The deployment log will look something like this: 

```{verbatim}
── Preparing for deployment ─────────────────────────────────────────────────
✔ Deploying "movie-reviews-prod" using "server: shinyapps.io / username: <username>"
ℹ Creating application on server...
✔ Created application with id 12711883
ℹ Bundling 39 files: .Rbuildignore, app.R, data/movies.rda, data/movies.RData,
data-raw/tidy_movies.R, DESCRIPTION, inst/tidy-data/app.R, inst/tidy-data/imdb.png,
inst/tidy-data/R/dev_mod_scatter.R, inst/tidy-data/R/dev_mod_vars.R, 
inst/tidy-data/R/devServer.R, inst/tidy-data/R/devUI.R, 
inst/tidy-data/tidy_movies.fst, inst/extdata/movies.fst, inst/prod/app/app.R, 
inst/www/bootstrap.png, inst/www/shiny.png, man/display_type.Rd, …, 
R/scatter_plot.R, and README.md
ℹ Capturing R dependencies with renv
✔ Found 69 dependencies
✔ Created 1,568,327b bundle
ℹ Uploading bundle...
✔ Uploaded bundle with id 9101312
── Deploying to server ────────────────────────────────────────────────────────
Waiting for task: 1457289827
  building: Processing bundle: 9101312
  building: Building image: 11074678
  building: Fetching packages
  building: Installing packages
  building: Installing files
  building: Pushing image: 11074678
  deploying: Starting instances
  success: Stopping old instances
── Deployment complete ───────────────────────────────────────────────────────
✔ Successfully deployed to <https://<username>.shinyapps.io/movie-reviews-prod/>
```

You can see a deployed version of this application [here](https://paradigmdata.shinyapps.io/movie-reviews-prod/)

## Recap {.unnumbered}

```{r}
#| label: git_launch_09.1_inst-www
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  branch = "09_inst")
```

This chapter had covered how to include external files and resources (i.e., what was previously stored in the `www/` folder of a regular Shiny app project) in your app-package with `addResourcePath()` and `system.file()`.

We've also covered how to use the `inst/` folder to include alternative files, development and production/deployment versions of your app. You can now launch the following applications from `sap`: 

**Standard application with/without test mode**

```{r}
#| eval: false
#| code-fold: false
library(sap)
launch_app(options = list(test.mode = TRUE))
# or 
launch_app(options = list(test.mode = FALSE))
```

**[`inst/bslib`]{style="font-size: 1.05em;"}: an application with an alternative layout (with/without test mode)**

```{r}
#| eval: false
#| code-fold: false
library(sap)
launch_app(app = "bslib", options = list(test.mode = TRUE))
# or 
launch_app(app = "bslib", options = list(test.mode = FALSE)) 
```

**[`inst/tidy-data`]{style="font-size: 1.05em;"}: an application using a 'development' dataset (with/without test mode)**

```{r}
#| eval: false
#| code-fold: false
library(sap)
launch_app(app = "ggp2", options = list(test.mode = TRUE))
# or 
launch_app(app = "ggp2", options = list(test.mode = FALSE))
```

**[`inst/prod`]{style="font-size: 1.05em;"}: An `app.R` file for launching a 'production' version of our app.**

```{r}
#| eval: false
#| code-fold: false
library(sap)
rsconnect::deployApp(appName = 'movie-reviews-prod')
```

In the next section, we're going to cover testing the code in a shiny app-package.  

```{r}
#| label: co_box_isnt_recap
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g", fold = FALSE,
  look = "default", hsize = "1.10", size = "1.05",
  header = "Recap: `inst` & `www` folders",
  contents = "
- **`inst/`**: the `inst/` folder is installed with your app-package and will be accessible to users, so it's a great location for files you want contained in your app, but don't fit into the standard R package structure.\n
  - `inst/` is also a great location for alternative versions of applications (i.e., `inst/app/dev` or `inst/app/prod/`).\n
  
- **`system.file()`**: constructs a path to files or folders within **installed packages** and is especially useful when working with external datasets (i.e., `inst/extdata/`) or other external resources included with your app-package (i.e., `inst/www/`).
  
- **`www`**: used for external static resources in shiny apps. shiny will automatically serve files under the `www/` directory, but in app-packages we need to explicitly set this location with `shiny::addResourcePath()`
  
- **`addResourcePath()`**: create a `prefix` (i.e., path) for a `directoryPath` of static files to accessible in shiny's web server:

    \`\`\`sh
    # file location
    inst/
      └── www/
            └── shiny.png
    \`\`\`
  
    \`\`\`r
    # add path to app 
    addResourcePath(prefix = 'www', 
                    directoryPath = system.file('www', 
                                    package = 'sap'))
    # use path without 'inst/' prefix
    shiny::img(src = 'www/shiny.png')
    \`\`\`
  "
)
```


```{r}
#| label: git_contrib_box
#| echo: false
#| results: asis
#| eval: true
git_contrib_box()
```