shiny.qmd

# Shiny {#sec-shiny}

```{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.10", size = "1.05", 
  header = "![](images/00_index_shiny.png){height=40} TLDR", 
  fold = TRUE,
  contents = "
  
<br>
  
A basic **Shiny project** has two files:
  
  An `app.R` and `.Rproj` file:\n
  \`\`\`bash
  shiny-app/
    ├── app.R
    └── shiny-app.Rproj
  \`\`\`
  
A fully developed **Shiny project** can have the following:
  
  1. An `R/` folder for additional scripts (i.e., modules, helper & utility functions) that is automatically sourced when the application runs\n
&emsp; &emsp; - The only exception to this is a `global.R` file, which is run first\n
  2. A `www/` folder for external resources (images, styling, etc.) that is automatically served when the application runs\n
  3. An optional `DESCRIPTION` file that controls deployment behaviors (i.e., `DisplayMode`)\n
  4. Data files\n
  5. An optional `README.md` file for documentation\n
  
  \`\`\`bash
  shiny-app/
    ├── DESCRIPTION
    ├── R/
    │   ├── module.R
    │   ├── helper.R
    │   └── utils.R
    ├── README.md
    ├── app.R
    ├── data.RData
    ├── shiny-app.Rproj
    └── www/
        └── shiny.png
  \`\`\`
  
\\*[Both `R/` and `www/` are automatically loaded when the app launches.]{style='font-style: italic;'}
  
  "
)
```

---

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

This chapter briefly reviews programming with Shiny's reactive model and how it differs from regular R programming. Then, I'll cover some of the unique behaviors of Shiny app projects (and why you might consider adopting them if you haven't already).

![](images/00_index_shiny.png){fig-align="right"}

:::

```{r}
#| label: shinypak_apps
#| echo: false
#| results: asis
#| eval: true
shinypak_apps(regex = "^02", branch = "02.1_shiny-app")
```

## Shiny basics {.unnumbered}

Reactivity is the process that lets Shiny apps respond to user actions automatically. When developing Shiny apps, we need to connect inputs, reactivity, and outputs to manage how the app behaves and predict its actions. 

Shiny programming is different from regular R programming in a few important ways:

-   **An Event-driven UI**: Shiny apps require developers to create a user interface (UI) that helps users navigate the app. The UI registers user actions, such as button clicks or input changes, which trigger updates in the application.[^shiny-event-ui]

    -   Regular R programming often involves executing predefined steps or functions without direct interaction or responses to user events.

-   **A Reactive Server**: In Shiny, the app reacts based on how inputs, values, and outputs are connected, which means that when a user makes a change, those changes are automatically shared throughout the app.

    -   In standard R programming, we write functions to process data and generate outputs like graphs, tables, and model results. This method does not account for reactivity or downstream changes.
    
Learning reactivity can be challenging when you start, but fortunately, there are [excellent tutorials](https://shiny.posit.co/r/getstarted/shiny-basics/lesson1/index.html) and [articles](https://shiny.posit.co/r/articles/build/understanding-reactivity/) to help you along the way!

[^shiny-event-ui]: Shiny apps require developers to design and develop a user interface (UI). [User experience (UX) design](https://bootcamp.cvn.columbia.edu/blog/what-is-ux-design/#:~:text) is an entirely separate field, but as Shiny developers, we need to know enough to allow users to interact with and navigate our apps. 

## Shiny projects ![](images/rproj_icon.png){height=30} {#sec-shiny-projects}

```{r}
#| label: git_box_moviesApp_main
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = 'launch',
  fig_pw = '75%', 
  branch = "02.1_shiny-app", 
  repo = 'sap')
```


RStudio's **New Project Wizard**  ![](images/rstudio-icon.png){height=20} can be used to create a new Shiny application project: 


![New Shiny app project](images/shiny_new_project_wizard.png){width="75%" fig-align="center"}


New app projects need a name and location: 


![We can also decide whether we want to use Git or `renv`](images/shiny_new_shiny_proj.png){width="75%" fig-align="center"}

### Boilerplate [`app.R`]{style='font-size: 1.05em;'} {#sec-boilerplate-app-dot-r}

Note that the only items in the new Shiny app project are `app.R` and the `sap.Rproj` file.

```{bash}
#| eval: false 
#| code-fold: false
sap/
    ├── app.R
    └── sap.Rproj

1 directory, 2 files
```

If you've created a new app project in RStudio ![](images/rstudio-icon.png){height=20}, the `app.R` initially contains a boilerplate application, which we can launch by clicking on the **Run App** button:

::: {.column-margin}

![Click on **Run App**](images/shiny_run_app.png){width="75%" fig-align="center"}

:::

::: {#fig-shiny_old_faithful}

![Old Faithful geyser app](images/shiny_old_faithful.png){#fig-shiny_old_faithful width="100%" fig-align="center"}

Boilerplate Old Faithful geyser app in new Shiny projects
:::

The boilerplate 'Old Faith Geyser Data' app is a perfect example of what Shiny can do with a single `app.R` file, but we'll want to exchange this code for a more realistic application.

## Movies app {#sec-introduce-movie-review-app}

```{r}
#| label: git_launch_02.2_movies-app
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  branch = "02.2_movies-app")
```

The next few sections will cover some intermediate/advanced Shiny app features using the Shiny app from the '[Building Web Applications with Shiny](https://rstudio-education.github.io/shiny-course/)' course. This app is a great example for the following reasons:

1.  It has **multiple input types** that are collected in the UI 

2. The graph output can be converted to a **utility function** 

3. The app loads an **external data** file when it's launched

4. The code is accessible (and comes from a trusted source) 

As Shiny applications become more complex, they often grow beyond just one `app.R` file. Knowing how to store utility functions, data, documentation, and metadata is important to manage this complexity. This preparation helps us successfully organize our Shiny apps into R packages.

### app.R {#sec-initial-movie-review-app-dot-r}

The code below replaces our boilerplate 'Old Faith Geyser Data' app in `app.R`:

```{r}
#| code-fold: true
#| eval: false 
#| code-summary: 'show/hide movie review Shiny app'
ui <- shiny::fluidPage(
  theme = shinythemes::shinytheme("spacelab"),
  shiny::sidebarLayout(
    shiny::sidebarPanel(
      shiny::selectInput(
        inputId = "y",
        label = "Y-axis:",
        choices = c(
          "IMDB rating" = "imdb_rating",
          "IMDB number of votes" = "imdb_num_votes",
          "Critics Score" = "critics_score",
          "Audience Score" = "audience_score",
          "Runtime" = "runtime"
        ),
        selected = "audience_score"
      ),
      shiny::selectInput(
        inputId = "x",
        label = "X-axis:",
        choices = c(
          "IMDB rating" = "imdb_rating",
          "IMDB number of votes" = "imdb_num_votes",
          "Critics Score" = "critics_score",
          "Audience Score" = "audience_score",
          "Runtime" = "runtime"
        ),
        selected = "critics_score"
      ),
      shiny::selectInput(
        inputId = "z",
        label = "Color by:",
        choices = c(
          "Title Type" = "title_type",
          "Genre" = "genre",
          "MPAA Rating" = "mpaa_rating",
          "Critics Rating" = "critics_rating",
          "Audience Rating" = "audience_rating"
        ),
        selected = "mpaa_rating"
      ),
      shiny::sliderInput(
        inputId = "alpha",
        label = "Alpha:",
        min = 0, max = 1,
        value = 0.4
      ),
      shiny::sliderInput(
        inputId = "size",
        label = "Size:",
        min = 0, max = 5,
        value = 3
      ),
      shiny::textInput(
        inputId = "plot_title",
        label = "Plot title",
        placeholder = "Enter text to be used as plot title"
      ),
      shiny::actionButton(
        inputId = "update_plot_title",
        label = "Update plot title"
      )
    ),
    shiny::mainPanel(
      shiny::br(),
      shiny::p(
        "These data were obtained from",
        shiny::a("IMBD", href = "http://www.imbd.com/"), "and",
        shiny::a("Rotten Tomatoes", href = "https://www.rottentomatoes.com/"), "."
      ),
      shiny::p(
        "The data represent",
        nrow(movies),
        "randomly sampled movies released between 1972 to 2014 in the United States."
      ),
      shiny::plotOutput(outputId = "scatterplot"),
      shiny::hr(),
      shiny::p(shiny::em(
        "The code for this Shiny application comes from",
        shiny::a("Building Web Applications with shiny",
          href = "https://rstudio-education.github.io/shiny-course/"
        )
      ))
    )
  )
)

server <- function(input, output, session) {
  new_plot_title <- shiny::reactive({
    tools::toTitleCase(input$plot_title)
  }) |>
    shiny::bindEvent(input$update_plot_title,
      ignoreNULL = FALSE,
      ignoreInit = FALSE
    )


  output$scatterplot <- shiny::renderPlot({
    scatter_plot(
      df = movies,
      x_var = input$x,
      y_var = input$y,
      col_var = input$z,
      alpha_var = input$alpha,
      size_var = input$size
    ) +
      ggplot2::labs(title = new_plot_title()) +
      ggplot2::theme_minimal() +
      ggplot2::theme(legend.position = "bottom")
  })
}

shiny::shinyApp(ui = ui, server = server)
```

### Utility functions {#sec-initial-movie-review-utils}

I've converted `ggplot2` server code into a `scatter_plot()` utility function: 

```{r}
#| code-fold: true
#| eval: false 
#| code-summary: 'show/hide scatter_plot()'
scatter_plot <- function(df, x_var, y_var, col_var, alpha_var, size_var) {
    ggplot2::ggplot(data = df,
      ggplot2::aes(x = .data[[x_var]],
          y = .data[[y_var]],
          color = .data[[col_var]])) +
      ggplot2::geom_point(alpha = alpha_var, size = size_var)

}
```

This function is stored in a new `utils.R` file:

### Data {#sec-initial-movie-review-data}

The `movies.RData` dataset contains reviews from [IMDB](https://www.imdb.com/) and [Rotten Tomatoes](https://www.rottentomatoes.com/). You can download these data [here](https://github.com/mjfrigaard/bbsa/raw/main/movies.RData). The `sap` project now contains the following files:

```{bash}
#| eval: false 
#| code-fold: false 
sap/
  ├── app.R
  ├── movies.RData
  ├── sap.Rproj
  └── utils.R

2 directories, 4 files
```

To run the `movies` app, we need to load the data and source the `utils.R` file by adding the code below to the top of the `app.R` file:

```{r}
#| eval: false 
#| code-fold: false
# install ------------------------------------
# install pkgs, then comment or remove below
pkgs <- c("shiny", "shinythemes", "stringr", "ggplot2", "rlang") # <1>
install.packages(pkgs, verbose = FALSE)                          # <1>
                                                                 # <1>
# packages ------------------------------------
library(shiny)
library(shinythemes)
library(stringr)
library(ggplot2)
library(rlang)

# data -----------------------------------------
load("movies.RData")

# utils ----------------------------------------
source("utils.R")

```

1. Install `pkgs`, then comment or remove below

Clicking on **Run App** displays the movie review app:

![Movie review app](images/shiny_movies_app.png){width="100%" fig-align="center"}


## Folders {#sec-shiny-folders}

Now that we have a *slightly* more complex application in `app.R`, I’ll add a few project folders we can include in our project that have unique built-in behaviors. These folders will help organize your files and make additional resources available to your app.

```{r}
#| label: git_launch_03_proj-app
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  branch = "02.3_proj-app")
```

### R/

If your Shiny app relies on utility or helper functions outside the `app.R` file, place this code in an `R/` folder. Any `.R` files in the `R/` folder will be automatically sourced when the application is run.

::: {.callout-note title="Place `utils.R` in `R/` folder" collapse='false' appearance='simple'}

I've moved the `utils.R` file into the `R/` folder in `sap`:

```{bash}
#| eval: false 
#| code-fold: false
sap/
     └── R/
         └── utils.R

1 directory, 1 file
```

:::

Shiny's [`loadSupport()`](https://shiny.posit.co/r/reference/shiny/1.5.0/loadsupport) function makes this process possible. We'll return to this function in a later chapter, because the `R/` folder has a similar behavior in R packages.[^load-support-1]

[^load-support-1]: Shiny introduced these features in version 1.3.2.9001, and you can read more about them in the section titled, '*The `R/` directory*' in [App formats and launching apps](https://shiny.posit.co/r/articles/build/app-formats/)

### www/

When you run a Shiny application, any static files (i.e., resources) under a `www/` directory will automatically be made available within the application. This folder stores images, CSS or JavaScript files, and other static resources.

::: {.callout-note title="Create `www/` folder and download image" collapse='false' appearance='simple'}

I've downloaded the Shiny logo ([`shiny.png`](https://raw.githubusercontent.com/rstudio/hex-stickers/main/PNG/shiny.png)) and stored it in the `www/` folder. 

```{bash}
#| eval: false 
#| code-fold: false
sap/
     └── www/
           └── shiny.png

1 directory, 1 file
```

In the section below, we'll reference `shiny.png` directly in the UI.

:::

Following the conventional folder structure will also help set you up for success when/if you decide to convert it into an app-package.

## Files {#sec-shiny-files}

The sections below cover additional files to include in your Shiny app. None of these files are required, but including them will make the transition to package development smoother. 

### README

Including a `README.md` file in your root folder is a good practice for any project. Using the standard markdown format (`.md`) guarantees it can be read from GitHub, too. `README.md` files should contain relevant documentation for running the application.


::: {.callout-note title="Create `README.md`" collapse='false' appearance='simple'}

I've included the content below in the `README.md` file

```Markdown
# movies app

The original code and data for this Shiny app comes from the [Building Web Applications with Shiny](https://rstudio-education.github.io/shiny-course/) course. It's been converted to use [shiny modules](https://shiny.posit.co/r/articles/improve/modules/). 

View the code for this application in the [`sap` branches](https://github.com/mjfrigaard/sap/branches/all).
```

:::

### DESCRIPTION

`DESCRIPTION` files play an essential role in R packages, but they are also helpful in Shiny projects if I want to deploy the app in [showcase mode](https://shiny.posit.co/r/articles/build/display-modes/).

::: {.callout-note title="Create `DESCRIPTION`" collapse='false' appearance='simple'}

I've included the content below in `DESCRIPTION`:

```{bash}
#| eval: false
#| code-fold: false
Type: shiny
Title: movies app
Author: John Smith
DisplayMode: Showcase                                                 
                                                                      
```

:::

::::{.column-margin}

:::{style="font-weight: bold; font-size: 1.10em"}
*It's always a good idea to leave at least one `<empty final line>` in your `DESCRIPTION` file.*
:::

::::

After adding `README.md` and a `DESCRIPTION` file (listing `DisplayMode: Showcase`), the movies app will display the code and documentation when the app launches.[^showcase-mode]

[^showcase-mode]: Read more about `showcase` mode [here](https://shiny.posit.co/r/articles/build/display-modes/)


## Code {#sec-app-code}

The following two items are considered best practices because they make your app more scalable by converting `app.R` into functions.

### Modules  {#sec-shiny-modules}

Shiny modules are a '[pair of UI and server functions](https://mastering-shiny.org/scaling-modules.html)' designed to compartmentalize input and output IDs into distinct namespaces,

> *'...a namespace is to an ID as a directory is to a file...'* - [`shiny::NS()` help file](https://shiny.posit.co/r/reference/shiny/latest/ns)

Module UI functions usually combine the layout, input, and output functions using `tagList()`. Module server functions handle the 'backend' logic within a Shiny server function. UI and server module functions are connected through an `id` argument. The UI function creates this `id` with `NS()` (namespace), and the server function uses `moduleServer()` to call it.

#### Inputs

The `mod_var_input_ui()` function creates a list of inputs (column names and graph aesthetics) in the UI: 

```{r}
#| eval: false
#| code-fold: show 
#| code-summary: 'show/hide mod_var_input_ui()'
mod_var_input_ui <- function(id) {
  ns <- shiny::NS(id)
  shiny::tagList(
    shiny::selectInput(
      inputId = ns("y"), # <1>
      label = "Y-axis:",
      choices = c(
        "IMDB rating" = "imdb_rating",
        "IMDB number of votes" = "imdb_num_votes",
        "Critics Score" = "critics_score",
        "Audience Score" = "audience_score",
        "Runtime" = "runtime"
      ),
      selected = "audience_score"
    ),
    shiny::selectInput(
      inputId = ns("x"), # <2>
      label = "X-axis:",
      choices = c(
        "IMDB rating" = "imdb_rating",
        "IMDB number of votes" = "imdb_num_votes",
        "Critics Score" = "critics_score",
        "Audience Score" = "audience_score",
        "Runtime" = "runtime"
      ),
      selected = "imdb_rating"
    ),
    shiny::selectInput(
      inputId = ns("z"), # <3>
      label = "Color by:",
      choices = c(
        "Title Type" = "title_type",
        "Genre" = "genre",
        "MPAA Rating" = "mpaa_rating",
        "Critics Rating" = "critics_rating",
        "Audience Rating" = "audience_rating"
      ),
      selected = "mpaa_rating"
    ),
    shiny::sliderInput(
      inputId = ns("alpha"),  # <4>
      label = "Alpha:",
      min = 0, max = 1, step = 0.1,
      value = 0.5
    ),
    shiny::sliderInput(
      inputId = ns("size"),  # <5>
      label = "Size:",
      min = 0, max = 5,
      value = 2
    ),
    shiny::textInput(
      inputId = ns("plot_title"),  # <6>
      label = "Plot title",
      placeholder = "Enter plot title"
    )
  )
}
```
1. `y` axis numeric variable 
2. `x` axis numeric variable 
3. `z` axis categorical variable  
4. `alpha` numeric value for points  
5. `size` numeric value for size  
6. `plot_title` text 

```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-align: center
%%| fig-cap: 'Variable input module'
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace',"fontSize":"16px"}}}%%
flowchart TD
    User(["User"])
    subgraph mod_var_input_server["<strong>mod_var_input_server()</strong>"]
        XServer[\"input$x"\]
        YServer[\"input$y"\]
        ZServer[\"input$z"\]
        AlphaServer[\"input$alpha"\]
        SizeServer[\"input$size"\]
        TitleServer[\"input$plot_title"\]
    end
    subgraph mod_var_input_ui["<strong>mod_var_input_ui()</strong>"]
        XUI[/"X-axis"/]
        YUI[/"Y-axis"/]
        ZUI[/"Color by"/]
        AlphaUI[/"Alpha"/]
        SizeUI[/"Size"/]
        TitleUI[/"Plot title"/]
    end
    User --> |"<em>Selects...</em>"|mod_var_input_ui
    mod_var_input_ui -->|"<em>Collects...</em>"| mod_var_input_server
    mod_var_input_server --> |"<em>Returns...</em>"|Return(["Reactive<br>list"])
    
```

`mod_var_input_server()` returns these values in a reactive list:

```{r}
#| eval: false
#| code-fold: show 
#| code-summary: 'show/hide mod_var_input_server()'
mod_var_input_server <- function(id) {

  shiny::moduleServer(id, function(input, output, session) {
    return(
        reactive({
          list(
            "y" = input$y, # <1>
            "x" = input$x, # <2>
            "z" = input$z, # <3>
            "alpha" = input$alpha, # <4>
            "size" = input$size, # <5>
            "plot_title" = input$plot_title # <6>
          )
        })
    )
  })
}
```

1. `y` axis numeric variable 
2. `x` axis numeric variable 
3. `z` axis categorical variable  
4. `alpha` numeric value for points  
5. `size` numeric value for size  
6. `plot_title` text 



#### Display

`mod_scatter_display_ui()` creates a dedicated namespace for the plot output (along with some help text):

```{r}
#| eval: false
#| code-fold: show 
#| code-summary: 'show/hide mod_scatter_display_ui()'
mod_scatter_display_ui <- function(id) {
  ns <- shiny::NS(id)
  shiny::tagList(
    shiny::tags$br(),
    shiny::tags$blockquote(
      shiny::tags$em(
        shiny::tags$h6("The data for this application comes from the ",
        shiny::tags$a("Building web applications with Shiny",
          href = "https://rstudio-education.github.io/shiny-course/"),
                      "tutorial"))
      ),
    shiny::plotOutput(outputId = ns("scatterplot")) # <1> 
  )
}
```
1. Namespaced module `id` for plot in UI

`mod_scatter_display_server()` loads the `movies` data and collects the returned reactive list from variable input module as `var_inputs`. 

```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-align: center
%%| fig-cap: 'Display module'
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"16px"}}}%%
flowchart TD
    User(["User"])
    mod_var_input_ui["<strong>mod_var_input_ui()</strong>"]
    mod_scatter_display_ui["<strong>mod_scatter_display_ui</strong>"] 
    
    subgraph mod_scatter_display_server["<strong>mod_scatter_display_server()</strong>"]
        var_inputs[\"var_inputs()"\]
        inputs[\"inputs()"\]
        scatter_plot("scatter_plot()")
    end
    
    subgraph mod_var_input_server["<strong>mod_var_input_server()</strong>"]
        Reactives[/"input$x<br>input$y<br>input$z<br>input$alpha<br>input$size"/]
        Title[/"input$plot_title"\]
    end
    
    User --> |"<em>Selects inputs...</em>"|mod_var_input_ui
    mod_var_input_ui --> |"<em>Collects inputs..</em>"|mod_var_input_server
    Reactives -->|"<em>Returns inputs...</em>"|selected_vars
    Title -.-> |"<em>Optional input...</em>"|selected_vars
    selected_vars[/"selected inputs"/] -->|"<em>Input argument for...</em>"|mod_scatter_display_server
    var_inputs --> inputs --> scatter_plot
    scatter_plot -->|"<em>Renders plot...</em>"|mod_scatter_display_ui
    mod_scatter_display_ui -->|"<em>Displays output...</em>"|Display(["Graph"])
    
    style mod_scatter_display_ui stroke-width:2px,rx:3,ry:3
    style mod_scatter_display_server stroke-width:2px,rx:3,ry:3
    style mod_var_input_ui stroke-width:2px,rx:3,ry:3
    style mod_var_input_server stroke-width:2px,rx:3,ry:3
    style scatter_plot stroke-width:2px,rx:10,ry:10
    style Reactives font-size:15px,stroke-width:1px,rx:5,ry:5
    style Title font-size:15px,stroke-width:1px,rx:5,ry:5
```

`var_inputs()` is used to build the `inputs()` reactive, which is passed to the `scatter_plot()` utility function. `scatter_plot()` creates the graph, adds the `plot_title()` (if necessary) and theme:

```{r}
#| eval: false 
#| code-fold: show
#| code-summary: 'show/hide mod_scatter_display_server()'
mod_scatter_display_server <- function(id, var_inputs) {
  shiny::moduleServer(id, function(input, output, session) {
    
    load("movies.RData") # <1>


    inputs <- shiny::reactive({ # <2>
      plot_title <- tools::toTitleCase(var_inputs()$plot_title) # <2>
      list( # <2>
        x = var_inputs()$x, # <2>
        y = var_inputs()$y, # <2>
        z = var_inputs()$z, # <2>
        alpha = var_inputs()$alpha, # <2>
        size = var_inputs()$size, # <2>
        plot_title = plot_title # <2>
      )  # <2>
    }) # <2>
    output$scatterplot <- shiny::renderPlot({ # <3>
      plot <- scatter_plot( # <3>
        df = movies, # <3>
        x_var = inputs()$x, # <3>
        y_var = inputs()$y, # <3>
        col_var = inputs()$z, # <3>
        alpha_var = inputs()$alpha, # <3>
        size_var = inputs()$size # <3>
      ) # <3>
      plot + # <4>
        ggplot2::labs( # <4>
          title = inputs()$plot_title, # <4>
          x = stringr::str_replace_all( # <4>
                  tools::toTitleCase( # <4>
                      inputs()$x), # <4>
                  "_", " "), # <4>
          y = stringr::str_replace_all( # <4>
                  tools::toTitleCase( # <4>
                    inputs()$y), # <4>
                "_", " ") # <4>
        ) + 
        ggplot2::theme_minimal() + # <5>
        ggplot2::theme(legend.position = "bottom") # <5>
    })
  })
}
```
1. loading the `movies` data
2. assembling the returned values from  `mod_var_input_server()`, and creating the `input()` reactive
3. `scatter_plot()` utility function creates the `plot` object 
4. adds the `plot_title()`
5. add `theme` to layers 


Both UI and server module functions are combined into a single `.R` file, and all modules are placed in the `R/` folder so they are sourced when the application is run. 

```{bash}
#| eval: false 
#| code-fold: false 
R/
 ├── mod_scatter_display.R
 ├── mod_var_input.R
 └── utils.R
```

### Standalone app function {#sec-shiny-standalone-app-fun}

Instead of using `shiny::shinyApp()` (or the **Run App** icon), we'll want a custom standalone app function to launch our application. This give us more flexibility and control with our modules (and makes debugging easier).

```{r}
#| eval: false
#| code-fold: true 
#| code-summary: 'show/hide launch_app()'
launch_app <- function() { 
  shiny::shinyApp(
    ui = shiny::fluidPage(
      shiny::titlePanel(
        shiny::div(
          shiny::img(
            src = "shiny.png",
            height = 60,
            width = 55,
            style = "margin:10px 10px"
            ), 
         "Movies Reviews"
        )
      ),
      shiny::sidebarLayout(
        shiny::sidebarPanel(
          mod_var_input_ui("vars") # <1>
        ),
        shiny::mainPanel(
          mod_scatter_display_ui("plot") # <2>
        )
      )
    ),
    server = function(input, output, session) {
      
      selected_vars <- mod_var_input_server("vars") # <3>

      mod_scatter_display_server("plot", var_inputs = selected_vars) # <4>
    }
  )
}
```
1. Variable input UI module 
2. Graph display UI module 
3. Variable input server module 
4. Graph display server module 

The `id` arguments (`"vars"` and `"plot"`) connect the UI functions to their server counterparts, and the output from `mod_var_input_server()` is the `var_inputs` argument in `mod_scatter_display_server()`.

```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-align: center
%%| fig-cap: 'Standalone app function'
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"13px"}}}%%
flowchart LR
    subgraph Launch["<code>launch_app()</code>"]
        subgraph VarNS["Variable (<code>vars</code>) Namespace"]
            VarInpuUI["UI Module:<br><code>mod_var_input_ui()</code>"]
            VarInpuServer["Server Module:<br><code>mod_var_input_server()</code>"]
            VarInpuUI <--> VarInpuServer
        end
        subgraph GraphNS["Graph (<code>plot</code>) Namespace"]
        DisplayUI["UI Module:<br><code>mod_scatter_display_ui()</code>"]
        DisplayServer["Server Module:<br><code>mod_scatter_display_server()</code>"]
        PlotUtil["Utility Function:<br><code>scatter_plot()</code>"]
        VarInpuServer <-->|"selected_vars"|DisplayServer
        DisplayServer <-.-> PlotUtil <--> DisplayUI
        end
    end

    VarNS <==>|"Communicates<br>across namespaces"| GraphNS

```

To launch our app, we place the call to `shinyApp()` in a `launch_app()` function in `app.R`. Both module functions are combined in the `ui` and `server` arguments of `shinyApp()`. 

```{r}
#| eval: false
#| code-fold: true 
#| code-summary: 'show/hide launch_app() in app.R'
# install ------------------------------------
# after installing, comment this out
pkgs <- c("shiny", "shinythemes", "stringr", "ggplot2", "rlang") # <1>
install.packages(pkgs, verbose = FALSE) # <1>

# packages ------------------------------------
library(shiny) # <2>
library(shinythemes) # <2>
library(stringr) # <2>
library(ggplot2) # <2>
library(rlang) # <2>

launch_app <- function() { 
  shiny::shinyApp(
    ui = shiny::fluidPage(
      shiny::titlePanel(
        shiny::div(
          shiny::img(
            src = "shiny.png",
            height = 60,
            width = 55,
            style = "margin:10px 10px"
            ), 
         "Movies Reviews"
        )
      ),
      shiny::sidebarLayout(
        shiny::sidebarPanel(
          mod_var_input_ui("vars") # <3>
        ),
        shiny::mainPanel(
          mod_scatter_display_ui("plot") # <4>
        )
      )
    ),
    server = function(input, output, session) {
      
      selected_vars <- mod_var_input_server("vars") # <5>

      mod_scatter_display_server("plot", var_inputs = selected_vars) # <6>
    }
  )
}
launch_app()
```

1. Header (comment this out after the packages are installed)
2. Load packages  
3. Variable input UI module 
4. Graph display UI module 
5. Variable input server module 
6. Graph display server module 

Now, I can run the app with `launch_app()`. 

![View a deployed version [here](https://mjfrigaard.shinyapps.io/moviesApp/)](images/shiny_proj_movies_app.png){width="100%" fig-align="center"}

The deployed files of `sap` are below: 

```{bash}
#| eval: false 
#| code-fold: false
sap/ # 02.3_proj-app branch
├── DESCRIPTION
├── R/
│   ├── mod_scatter_display.R
│   ├── mod_var_input.R
│   └── utils.R
├── README.md
├── app.R
├── movies.RData
├── sap.Rproj
├── rsconnect/
│   └── shinyapps.io/
│       └── user/
│           └── sap.dcf
└── www/
    └── shiny.png

6 directories, 10 files
```

:::{.column-margin}

The `rsconnect/` folder has been removed from the [`02.3_proj-app`](https://github.com/mjfrigaard/sap/tree/02.3_proj-app) branch.

:::


## Additional features {#sec-adv-shiny-projects}

Below are two additional 'optional' features that *can* be included with your Shiny application. I consider these 'optional' because they're use depends on the specific needs and environment for each application.

### Globals

Placing a `global.R` file in your root folder (or in the `R/` directory) causes this file to be sourced only once when the Shiny app launches, rather than each time a new user connects to the app. `global.R` is commonly used for initializing variables, loading libraries, loading large data sets and/or performing initial calculations.

::: {.callout-note title="Using `global.R`" collapse='true' appearance='simple'}

I *could* place the header from `app.R` in `global.R` to ensure these packages are loaded before the application launches:

```{r}
#| eval: false 
#| code-fold: show
#| code-summary: 'show/hide contents of R/global.R'
# packages ------------------------------------
library(shiny)
library(shinythemes)
library(stringr)
library(ggplot2)
library(rlang)
```

`global.R` can be placed in the `R/` folder 

```{bash}
#| eval: false 
#| code-fold: false
R/
├── global.R
├── mod_scatter_display.R
├── mod_var_input.R
└── utils.R

1 directory, 4 files
```

Or in the project root folder

```{bash}
#| eval: false 
#| code-fold: false
├── DESCRIPTION
├── R
│   ├── mod_scatter_display.R
│   ├── mod_var_input.R
│   └── utils.R
├── README.md
├── app.R
├── global.R
├── man
├── movies.RData
├── sap.Rproj
└── www
    └── shiny.png

4 directories, 10 files
```

In both locations, it will be sourced before launching the application.

:::

`global.R` can be used to maintain efficiency and consistency across application sessions.

### Project dependencies ([`renv`]{style='font-size: 1.05em;'})

If you use [`renv`](https://rstudio.github.io/renv/articles/renv.html), keep track of your dependencies by regularly running `renv::status()` and `renv::snapshot()`.

::: {.callout-note title="Using `renv`" collapse='true' appearance='simple'}

Start by initiating `renv` with `renv::init()`, then run `renv::status()` to check which packages have been added to the lockfile:

```{r}
#| eval: false
#| code-fold: false
renv::status()
```

``` sh
The following package(s) are in an inconsistent state:

 package      installed recorded used
 colorspace   y         n        y   
 fansi        y         n        y   
 farver       y         n        y   
 ggplot2      y         n        y   
 gtable       y         n        y   
 isoband      y         n        y   
 labeling     y         n        y   
 lattice      y         n        y   
 MASS         y         n        y   
 Matrix       y         n        y   
 mgcv         y         n        y   
 munsell      y         n        y   
 nlme         y         n        y   
 pillar       y         n        y   
 pkgconfig    y         n        y   
 RColorBrewer y         n        y   
 scales       y         n        y   
 shinythemes  y         n        y   
 tibble       y         n        y   
 utf8         y         n        y   
 vctrs        y         n        y   
 viridisLite  y         n        y   
```

Take a 'snapshot' to capture the current package dependencies:

```{r}
#| eval: false
#| code-fold: false
renv::snapshot()
```


``` sh
The following package(s) will be updated in the lockfile:

# CRAN --------------------------------------------------
- lattice        [* -> 0.21-8]
- MASS           [* -> 7.3-60]
- Matrix         [* -> 1.5-3]
- mgcv           [* -> 1.8-42]
- nlme           [* -> 3.1-162]
- vctrs          [* -> 0.6.3]

# RSPM --------------------------------------------------
- colorspace     [* -> 2.1-0]
- fansi          [* -> 1.0.4]
- farver         [* -> 2.1.1]
- ggplot2        [* -> 3.4.2]
- gtable         [* -> 0.3.3]
- isoband        [* -> 0.2.7]
- labeling       [* -> 0.4.2]
- munsell        [* -> 0.5.0]
- pillar         [* -> 1.9.0]
- pkgconfig      [* -> 2.0.3]
- RColorBrewer   [* -> 1.1-3]
- scales         [* -> 1.2.1]
- shinythemes    [* -> 1.2.0]
- tibble         [* -> 3.2.1]
- utf8           [* -> 1.2.3]
- viridisLite    [* -> 0.4.2]

Do you want to proceed? [Y/n]: y

- Lockfile written to '~/path/to/sap/renv.lock'.
```

:::

## Recap

This chapter has covered some differences between developing Shiny apps and regular R programming, creating new Shiny projects in Posit Workbench, and some practices to adopt that can make the transition to app-packages a little easier. The code used in this chapter is stored in the [`sap` repository](https://github.com/mjfrigaard/sap/branches/all). 

```{r}
#| label: co_box_recap
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "g", 
  look = "default", hsize = "1.10", size = "1.05", 
  header = "Recap",
  contents = "
  
  - Placing utility or helper files in an `R/` folder removes the need to call `source()` in `app.R`.
  
  - Images, CSS, JavaScript, and other static resources can be stored in `www/` and Shiny will serve these files when the application is run.
  
  - `README.md` files can document the application's description, purpose, requirements, etc.
  
  - `DESCRIPTION` files provide metadata and include fields that affect application deployment (i.e., `DisplayMode: Showcase`)
  
  - Converting the application code into functions (modules and standalone app functions) creates a 'division of labor' for each component, which makes it easier to think about and work on them independently.
  
  - Finally, if you're using `renv`, run `renv::status()` and `renv::snapshot()` to manage dependencies 

  ", fold = FALSE
)
```

In the next chapter, I'll cover what makes a package a package, and some do's and don'ts when converting a developed Shiny application into an R package. 

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