my-rhino-app.qmd

---
title: "Shiny frameworks (part 5, `rhino`)"
author: "Martin Frigaard"
date: "2023-03-03"
categories: [shiny, code, packages]
image: "image.png"
toc: true
toc-depth: 5
toc-title: 'Contents'
toc-location: "left"

fig-align: center
code-link: true
fontsize: '10'

callout-icon: false

freeze: true

execute:
  echo: true
  warning: false
  eval: false
---

```{r}
#| label: utils
#| eval: true
#| echo: false
#| include: false
library(kableExtra)
co_box <- function(color, header, contents = "Your text") {
  class <- switch(color,
    b = "note",
    g = "tip",
    r = "important",
    o = "caution",
    stop("Invalid `type`", call. = FALSE)
  )
  switch(color,
    b = cat(paste0(
      "\n",
      ":::: {.callout-", class, " collapse='false'}", "\n\n",
      "## ", header, "\n\n",
      "::: {style='font-size: 0.90em; color: #696969;'}\n\n",
      contents, "\n\n",
      "::: \n\n",
      "::::", "\n"
    )),
    g = cat(paste0(
      "\n",
      ":::: {.callout-", class, " collapse='true'}", "\n\n",
      "## ", header, "\n\n",
      "::: {style='font-size: 0.90em; color: #696969;'}\n\n",
      contents, "\n\n",
      "::: \n\n",
      "::::", "\n"
    )),
    o = cat(paste0(
      "\n",
      ":::: {.callout-", class, " collapse='false'}", "\n\n",
      "## ", header, "\n\n",
      "::: {style='font-size: 0.90em; color: #696969;'}\n\n",
      contents, "\n\n",
      "::: \n\n",
      "::::", "\n"
    )),
    r = cat(paste0(
      "\n",
      ":::: {.callout-", class, " collapse='false'}", "\n\n",
      "## ", header, "\n\n",
      "::: {style='font-size: 0.90em; color: #696969;'}\n\n",
      contents, "\n\n",
      "::: \n\n",
      "::::", "\n"
    )),
    stop("Invalid `type`", call. = FALSE)
  )
}
# roxy_ns_df -----
roxy_ns_df <- data.frame(
  check.names = FALSE,
  `roxygen2 tag` = c("@importFrom", "@import", "@export"),
  `NAMESPACE directive` = c(
    "importFrom() : import selected object from another NAMESPACE",
    "import(): import all objects from another package’s NAMESPACE.",
    "export() : export the function, method, generic, or class so it’s available outside of the package (in the NAMESPACE)"
  ),
  DESCRIPTION = c("Imports:", "Imports:", "Nothing")
)
# box_use_df -----
box_use_df <- data.frame(
  check.names = FALSE,
  `Inside box::use()` = c(
    "box::use(
      pkg
    )",
    "box::use(
      p = pkg
      )",
    "box::use(
      pkg = pkg[foo, bar]
      )",
    "box::use(
      pkg[my_foo = foo, ...]
      )"
  ),
  Action = c(
    "imports 'pkg', does not attach any function names",
    "imports 'pkg' with alias ('p'), does not attach any function names",
    "imports 'pkg' and attaches the function names 'pkg::foo()' and 'pkg::bar()'",
    "imports 'pkg' with alias for 'foo' ('my_foo') and attaches all exported function names"
  )
)
```

<!--
https://mjfrigaard.github.io/posts/vanilla-shiny/

https://mjfrigaard.github.io/posts/my-pkg-app/

https://mjfrigaard.github.io/posts/my-golem-app/

https://mjfrigaard.github.io/posts/my-leprechaun-app/

https://mjfrigaard.github.io/posts/my-rhino-app/
-->


This is the fifth and final post on creating shiny apps with various frameworks. In this post, I'll build a *'high quality, enterprise-grade'* shiny app using the [`rhino`](https://appsilon.github.io/rhino/index.html) package and framework.

```{r}
#| label: co_box_dev
#| echo: false
#| results: asis
#| eval: true
co_box(color = "r", header = "ALERT!", "**This post is currently under development. Thank you for your patience.**")
```


## Framework comparisons 

This series has focused on the following technical areas: **Start**, **Build**, and **Use**. 

  -   **Start** covers the steps required to begin building a shiny app with the framework (from the console and IDE), and any additional packages or dependencies.

  -   **Build** covers the development process, which includes writing and storing code, data, external resources (like CSS or JavaScript), testing, etc. 

  -   **Use** shows how developers can launch their application using the given framework/package locally (i.e., within the RStudio (Posit) IDE), common workflow tips, and any points I found confusing.   

+ In part one, I built a 'minimal' shiny app ([`VanillaApp`](https://mjfrigaard.github.io/posts/vanilla-shiny/))  

+ In part two, I structured the shiny application as an R package using [`usethis`](https://usethis.r-lib.org/) and [`devtools`](https://devtools.r-lib.org/), [`myPkgApp`](https://mjfrigaard.github.io/posts/my-pkg-app/).

+ In part three, I used the popular [`golem` framework](https://thinkr-open.github.io/golem/), [`myGolemApp`](https://mjfrigaard.github.io/posts/my-golem-app/).

+ In part four, I created a shiny app using the [`leprechaun` package](https://leprechaun.opifex.org/#/) and framework, [`myLeprechaunApp`](https://mjfrigaard.github.io/posts/my-leprechaun-app/) 

The GitHub repo with all shiny app setups is [here](https://github.com/mjfrigaard/shiny-app-setups).

<br>

# `myRhinoApp`


`rhino` is a package developed by [Appsilon](https://appsilon.com/) (yes, [`shinyconf` Appsilon](https://shinyconf.appsilon.com/)) for "*Build[ing] high quality, enterprise-grade Shiny apps at speed.*" 

`rhino` differs from the previous frameworks and methods in a couple important ways. First, a `rhino` application **is not an R package**. Instead, `rhino` shiny apps rely on [`box`](https://klmr.me/box/) for managing importing dependencies  (instead of the `DESCRIPTION` and `NAMESPACE`). Second, `rhino` requires [node.js](https://www.wikiwand.com/en/Node.js), open-source JavaScript runtime environment.


## Start

To create a new rhino application, select **Project** > **New Project** > **New Directory**, and **Shiny Application using rhino**

The **New Project Wizard** will require a *Directory name* and *subdirectory*. I've also left *Github Actions CI* selected (the default)

::: {#fig-rhino-setup .column}
![](rhino-setup.png){height="100%" width="100%" fig-align="center"}

`myRhinoApp`
:::

::: {style="font-size: 0.80em;"}
*Click __Code__ to see output*
:::

::: {style="font-size: 0.80em;"}
```{bash}
#| label: startup-rhino
#| code-fold: true
* Initializing project ...
* Discovering package dependencies ... Done!
* Copying packages into the cache ... Done!
The following package(s) will be updated in the lockfile:

# CRAN ===============================
- R.cache        [* -> 0.16.0]
- R.methodsS3    [* -> 1.8.2]

  < < < < < < < OMITTED > > > > > > > >

- xtable         [* -> 1.8-4]
- yaml           [* -> 2.3.7]

# GitHub =============================
- box            [* -> klmr/box@dev]

The version of R recorded in the lockfile will be updated:
- R              [*] -> [4.2.2]

* Lockfile written to '~/projects/myRhinoApp/renv.lock'.
✔ Initialized renv.
✔ Application structure created.
✔ Unit tests structure created.
✔ E2E tests structure created.
✔ Github Actions CI added.
```
:::

This initializes the new `rhino` app by opening the `.Rproj` file in RStudio.

If I wanted to create the `myRhinoApp` application from the console, I would use the following: 

::: {style="font-size: 0.80em;"}
```{r}
#| label: init-rhino
#| code-fold: false
install.packages("rhino")
rhino::init("/Users/mjfrigaard/projects/myRhinoApp")
```
:::

::: {style="font-size: 0.80em;"}
*Click __Code__ to see output*
:::

::: {style="font-size: 0.80em;"}
```{bash}
#| label: rhino-init-output
#| code-fold: true
✔ Rproj file created.
* Initializing project ...
* Discovering package dependencies ... Done!
* Copying packages into the cache ... Done!
The following package(s) will be updated in the lockfile:

# CRAN ===============================
- R.cache        [* -> 0.16.0]
- R.methodsS3    [* -> 1.8.2]

  < < < < < < < OMITTED > > > > > > > >

- xtable         [* -> 1.8-4]
- yaml           [* -> 2.3.7]

# GitHub =============================
- box            [* -> klmr/box@dev]

The version of R recorded in the lockfile will be updated:
- R              [*] -> [4.2.2]

* Lockfile written to '~/projects/myRhinoApp/renv.lock'.
✔ Initialized renv.
✔ Application structure created.
✔ Unit tests structure created.
✔ E2E tests structure created.
✔ Github Actions CI added.
```
:::

```{r}
#| label: co_box_output
#| echo: false
#| results: asis
#| eval: true
co_box(color = "b", header = "What's the difference?", contents = "Both methods create the same structure, using `rhino::init()` will not automatically open the new rhino application project file (`~/projects/myRhinoApp/myRhinoApp.Rproj`), so I have to navigate to this file and open it.")
```

The initial folder structure for a new rhino app is below: 

::: {style="font-size: 0.80em;"}
```{bash}
#| label: rhino-initial-tree
#| code-fold: false
myRhinoApp/
      ├── app/
      │   ├── js
      │   │   └── index.js
      │   ├── logic
      │   │   └── __init__.R
      │   ├── main.R
      │   ├── static
      │   │   └── favicon.ico
      │   ├── styles
      │   │   └── main.scss
      │   └── view
      │       └── __init__.R
      ├── app.R
      ├── config.yml
      ├── dependencies.R
      ├── myRhinoApp.Rproj
      ├── renv/
      │   ├── activate.R
      │   ├── library
      │   │   └── R-4.2
      │   ├── sandbox
      │   │   └── R-4.2
      │   └── settings.dcf
      ├── renv.lock
      ├── rhino.yml
      └── tests/
          ├── cypress
          │   └── integration
          ├── cypress.json
          └── testthat
              └── test-main.R

16 directories, 16 files
```
:::

The `rhino` package website has [excellent documentation on their app structure philosophy](https://appsilon.github.io/rhino/articles/explanation/application-structure.html), and it's worth reading through this before getting started. I'll do my best to summarize the application's files below:

### `app/`

The `app/` folder contains the primary folder and files for my application. 

-   `app/` includes the following files and sub-folders: 

    ::: {style="font-size: 0.80em;"}
    ```{bash}
    #| label: rhino-initial-app
    #| code-fold: false
    app/
      ├── js/
      │   └── index.js
      ├── logic/
      │   └── __init__.R
      ├── main.R
      ├── static/
      │   └── favicon.ico
      ├── styles/
      │   └── main.scss
      └── view/
          └── __init__.R
    
    6 directories, 6 files
    ```
    :::


-   `js/`: the `js` folder initially contains a blank `index.js` script  
  
-   `logic/`: the `logic` folder contains [*code independent from Shiny*](https://appsilon.github.io/rhino/articles/explanation/application-structure.html#logic)
      
    -   `logic/__init__.R` is originally blank, but provides a link to the website section on project structure  
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino-initial-logic-init
    #| code-fold: false
    # Logic: application code independent from Shiny.
    # https://go.appsilon.com/rhino-project-structure
    ```
    :::
  
-   `static/`: the `static/` folder will contain external resources (like JavaScript files) and is similar to the sub-folders in `inst/` from `golem` and `leprechaun`. 

    -   Use these file in the UI with: 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino-statis-ui-call
    #| code-fold: false
    tags$script(src = "static/js/app.min.js")
    ```
    :::
  
-   `styles/`: the `styles/` folder will hold custom styles (CSS and HTML) in the `styles/main.css` file (which is initially blank)
  
-   `view/`: the `view/` folder holds the [*code which describes the user interface of your application and relies upon the reactive capabilities of Shiny.*](https://appsilon.github.io/rhino/articles/explanation/application-structure.html#view)

    -   `view/__init__.R` is also intially blank, but provides a link to the website section on project structure  
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino-initial-view-init
    #| code-fold: false
    # View: Shiny modules and related code.
    # https://go.appsilon.com/rhino-project-structure
    ```
    :::
    
-   `main.R`: the `main.R` file contains the *actual* application code (this is where I'll make edits).

    -   `app/main.R` contains the code for the application I see when I run `rhino::app()`
    
    ::: {style="font-size: 0.80em;"}
    *Click __Code__ to see `app/main.R`*
    :::
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino-initial-main
    #| code-fold: show
    box::use(
      shiny[bootstrapPage, moduleServer, NS, renderText, tags, textOutput],
    )
    
    #' @export
    ui <- function(id) {
      ns <- NS(id)
      bootstrapPage(
        tags$h3(
          textOutput(ns("message"))
        )
      )
    }
    
    #' @export
    server <- function(id) {
      moduleServer(id, function(input, output, session) {
        output$message <- renderText("Hello!")
      })
    }
    ```
    :::
    
<br>

```{r}
#| label: box_co_box
#| echo: false
#| eval: true
#| results: asis
co_box(color = "r", header = "`box::use()`?", contents = "If `box`'s syntax looks strange--don't worry! It looked strange to me too at first. But it's actually something special with those `roxygen2` tags. I'll cover it more in the **Build** section below.")
```


### `app.R`

-   `app.R` is the file that will run my application and contains the `rhino::app()` function. 

    ::: {style="font-size: 0.95em; color: #E74A2F;"}
    **Do not edit this file!**
    :::

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino-app-initial
    #| code-fold: false
    # Rhino / shinyApp entrypoint. Do not edit.
    rhino::app()
    ```
    :::
    
    -   `rhino` has a 'minimal `app.R`' [philosophy](https://appsilon.github.io/rhino/articles/explanation/application-structure.html#minimal-app-r), and the call to `rhino::app()` [performs multiple operations](https://appsilon.github.io/rhino/reference/app.html) beyond `shiny::runApp()`


### `config.yml`

-   `config.yml` is a YAML file that follows the [`config` package](https://rstudio.github.io/config/) format. This file initially contains two calls to `Sys.getenv()`:

    ::: {style="font-size: 0.80em;"}
    ``` YAML
    default:
      rhino_log_level: !expr Sys.getenv("RHINO_LOG_LEVEL", "INFO")
      rhino_log_file: !expr Sys.getenv("RHINO_LOG_FILE", NA)
    ```
    :::
    
    - Read more about how to use `config.yml` in the **Environments** section of the [How to: Manage secrets and environments](https://appsilon.github.io/rhino/articles/how-to/manage-secrets-and-environments.html?#environments) vignette.


### `dependencies.R`

-   `dependencies.R` is an `.R` script that contains any other packages used by the application. Using this file is covered in the [Manage Dependencies vignette](https://appsilon.github.io/rhino/articles/how-to/manage-r-dependencies.html) on the package website, and I've covered `renv` in the [first application (`VanillaShiny`)](https://mjfrigaard.github.io/posts/vanilla-shiny/#renv). 

    -   As I can see from the note in the comments, the dependencies will be tracked using `packrat` in rsconnect. 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino-depends
    #| code-fold: false
    # This file allows packrat (used by rsconnect during deployment)
    # to pick up dependencies.
    library(rhino)
    ```
    :::
    
    -   I know I'll be using `ggplot2` and `stringr` in this application, so I'll load those there.

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: new-rhino-depends
    #| code-fold: false
    # This file allows packrat (used by rsconnect during deployment)
    # to pick up dependencies.
    library(rhino)
    library(ggplot2)
    library(stringr)
    ```
    :::
    
    -   Now I `install` and take a snapshot with `renv`:
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: snapshot-renv-depends
    #| code-fold: false
    renv::install(c("ggplot2", "stringr"))
    renv::snapshot()
    ```
    :::
    


### `renv/`

-   The `renv/` folder contains the R version and packages used to build the application: 

    -   `renv.lock` is the lock file and contains the packages and R version used in the application.
    
    ::: {style="font-size: 0.80em;"}
    ```{bash}
    #| label: rhino-renv
    #| code-fold: false
    myRhinoApp/
      ├── renv/
      │    ├── activate.R
      │    ├── library/
      │    │   └── R-4.2
      │    │       └── x86_64-apple-darwin17.0
      │    ├── sandbox/
      │    │   └── R-4.2
      │    │       └── x86_64-apple-darwin17.0
      │    └── settings.dcf
      └── renv.lock
    ```
    :::

    -   Read more about [getting started with `renv`](https://rstudio.github.io/renv/articles/renv.html) and using [`renv` in package development](https://rstudio.github.io/renv/articles/packages.html)


### `rhino.yml`

-   `rhino.yml` is the configuration file and contains options for setting how Sass is built or for importing from another application structure to `rhino`.

    - the code below showcases the optional arguments (and is not included in the application)
    
    ::: {style="font-size: 0.80em;"}
    ``` YAML
    sass: string               # required | one of: "node", "r"
    legacy_entrypoint: string  # optional | one of: "app_dir", "source", "box_top_level"
    ```
    :::
    
    - Read more about `rhino.yml` in the [Explanation: Configuring Rhino - rhino.yml](https://appsilon.github.io/rhino/articles/explanation/rhino-yml.html) vignette.


### `tests/`

-   `tests/` contains two sub-folders, `cypress/` and `testthat/`:

    ::: {style="font-size: 0.80em;"}
    ```{bash}
    tests/
        ├── cypress/
        │   └── integration/
        │       └── app.spec.js
        ├── cypress.json
        └── testthat/
            └── test-main.R
    ```
    :::



#### `cypress/`

-   `tests/cypress/` holds folders for using the [Cypress web and component testing framework](https://www.cypress.io/). 

    -   This is also covered in the ['Use `shinttest2` vignette'](https://appsilon.github.io/rhino/articles/how-to/use-shinytest2.html).

    ::: {style="font-size: 0.80em;"}
    ```bash
    tests/
        ├── cypress/
        │    └── integration/
        │        └── app.spec.js
        └── cypress.json
    ```
    :::
    

#### `testthat/`

-   `tests/testthat/` contains the architecture for writing tests with [testthat](https://testthat.r-lib.org/)

    -   `rhino` also has a helper function for running all tests in the `testthat/` folder ([`rhino::test_r()`](https://appsilon.github.io/rhino/reference/test_r.html))

    ::: {style="font-size: 0.80em;"}
    ```bash
    tests/
        └── testthat/
                └── test-main.R
    ```
    :::


## Build

Unlike the previous applications in this series, `rhino` applications don't use the `NAMESPACE` and `DESCRIPTION` to manage dependencies. Instead, they use the `box` modules to explicitly import packages and functions

### `box`

::: {layout-ncol=1}
![](box-logo.png){width=1in fig-align="right"}
:::

`rhino` apps use [`box`](https://klmr.me/box/index.html) to create modules, which is handy, because it's specifically designed for writing "*reusable, composable and modular R code*"

**Quick refresher:** if I'm building a shiny app, 

-   I install dependencies using `install.packages('<package>')` (or `renv::install('<package>')`)

-   When I want to use an installed package, I run `library(<package>)`, which loads the package namespace '*and attach[es] it on the search list*' (or I can use `<package>::<function>`)

-   If the application gets converted into an R package, I track these dependencies using `roxygen2` tags `@importFrom` or `@import` (which are converted into `NAMESPACE` directives) 

-   I also include them in the `DESCRIPTION` under `Imports:`

So, I run `library(<package>)` to load the entire package namespace when I want to use a function, but it's recommended I use `@importFrom` to *specify* the package functions if I'm developing my own R package.

Put another way, 

*"If I only need one or two items from a package, why am I loading* **everything** *in the namespace with `library()`?"*

This is where [`box`](https://klmr.me/box/index.html) comes in--it's designed to *'completely replace the base R `library` and `require` functions'*.

[`box`](https://klmr.me/box/index.html) handles dependencies by *'writing modular code'* and is perhaps best summarized in the following quote from [The Zen of Python](https://peps.python.org/pep-0020/) (also on the [package website](https://klmr.me/box/index.html#why-box))

> '*explicit is better than implicit.*'

A `box` module is essentially just an R script in a folder. However, in `box::use()`, instead of loading packages and functions using `library()` or `::`, I can **encapsulate and explicitly import packages and functions** in these R scripts using the syntax `package[function]`. 

-   The module below imports the `foo()` and `bar()` functions from the `pkg` package in the `mod.R` file (in the `box/` folder)

    ::: {style="font-size: 0.80em;"}
    ``` r
    # contents of box/mod.R
    #' @export
    box::use(
      pkg[foo, bar]
    )
    ```
    :::

-   I can now access `foo()` and `bar()` from `mod.R` using `box::use(box/mod)`:

    ::: {style="font-size: 0.80em;"}
    ``` r
    # using contents of box/mod.R
    box::use(
      box/mod
    )
    ```
    :::


#### `box` modules

Here is a quick example:

-   Below I attempt to use `tidyverse`s `tidyverse_logo()` function 

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: tidyverse_logo_test
    #| echo: true
    #| eval: true
    #| error: true
    tidyverse_logo()
    ```
    :::
    
    -   The error is expected, because `dplyr` has been installed, but hasn't been loaded. 

-   In a `box` module, I import the `tidyverse_logo()` from `tidyverse` (without using `library()` or `::`), by creating a `logo.R` file in a `tidy` folder. In  `logo.R`, I include `box::use()` and the following code:
    
    - I also include `#' @export` on the preceding line:

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: box_tidy
    #| eval: false
    # contents of tidy/logo.R
    #' @export
    box::use(
      tidyverse[tidyverse_logo]
    )
    ```
    :::
    
    -   Note I did not have to use `tidyverse::tidyverse_logo()`

-   To use this module, I call `box::use(tidy/logo)`, which loads `logo` into the environment. 

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: box_use_tidy_logo
    #| eval: false
    box::use(tidy/logo)
    ls(logo)
    ```
    
    ```bash
     <module: tidy/logo>
    ```
    :::
    
    -   I can use `ls()` on `logo` to return the imported names. 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: ls_logo
    #| eval: false
    ls(logo)
    ```
    
    ```bash
    [1] "tidyverse_logo"
    ```
    :::
    
-   To use the `tidyverse_logo()` function, I use `$`:

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: logo_tidyverse_logo
    #| eval: false
    logo$tidyverse_logo()
    ```
    
    ```bash
    ⬢ __  _    __   .    ⬡           ⬢  . 
     / /_(_)__/ /_ ___  _____ _______ ___ 
    / __/ / _  / // / |/ / -_) __(_-</ -_)
    \__/_/\_,_/\_, /|___/\__/_/ /___/\__/ 
         ⬢  . /___/      ⬡      .       ⬢ 
    ```
    :::

-   Note that `tidyverse_logo()` is still not loaded *outside* the `logo` module

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: tidyverse_logo_retest
    #| eval: true
    #| error: true
    tidyverse_logo()
    ```
    :::

I can also include (or wrap) `box::use()` inside custom functions, and then call these when I've imported the module: 

-   `tidy/plogo.R` imports `tidyverse_logo()` *inside* a custom function, `print_logo()`

    -   Note that to use a packages/functions from a module, you must include `#' @export` from `roxygen2` (in the line above):

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: plogo_tidyverse_logo
    #| eval: false
    # contents of tidy/plogo.R
    
    #' prints tidyverse logo
    #' @export
    print_logo <- function() {
      # import pkg[fun] inside function
      box::use(
        tidyverse[tidyverse_logo]
      )
      # use fun
      tidyverse_logo()
    }
    ```
    :::
    
    -   I load the module into the environment with `box::use(path/to/module)`
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: use_plogo
    #| eval: false
    # use tidy/plogo
    box::use(tidy/plogo)
    plogo
    ```
    
    ``` bash
    <module: tidy/plogo>
    ```
    :::
    
    -   I can use the `print_logo()` function the same way I used `tidyverse_logo()` in the `logo` module.
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: run_print_logo
    #| eval: false
    # access print_logo() with $
    plogo$print_logo()
    ```
    
    ```bash
    ⬢ __  _    __   .    ⬡           ⬢  . 
     / /_(_)__/ /_ ___  _____ _______ ___ 
    / __/ / _  / // / |/ / -_) __(_-</ -_)
    \__/_/\_,_/\_, /|___/\__/_/ /___/\__/ 
         ⬢  . /___/      ⬡      .       ⬢ 
    ```
    :::

-   Also note `print_logo()` doesn't exist outside the `plogo` module: 

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: check_plogo
    #| eval: true
    #| error: true
    print_logo()
    ```
    :::
    
    -   This is what is meant by *encapsulation*

`box` modules can also import functions and packages using aliases. 

-   The example below (`tidy/tidy_logo.R`) exports `tidyverse_logo()` as `tidy_logo()` and `print_logo()`

    -   Both the contents of `box::use()` and `print_logo()` need the `#' @export` tag 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: module_tidy_logo
    #| eval: false
    # contents of tidy/tidy_logo.R
    
    #' import alias tidyverse logo
    #' @export
    box::use(
      tidyverse[tidy_logo = tidyverse_logo]
    )
    
    #' prints tidyverse logo
    #' @export
    print_logo <- function() {
      # use fun alias
      tidy_logo()
    }
    ```
    :::

    - After I load the module with `box::use()`, I can see both functions in `tidy_logo` using `ls()`
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: ls_tidy_logo
    #| eval: false
    box::use(tidy/tidy_logo)
    ls(tidy_logo)
    ```

    ```bash
    [1] "print_logo" "tidy_logo"
    ```
    :::
    
    -   If I compare both functions, I find they are identical:
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: identical_tidy_logo
    #| eval: false
    identical(
      x = tidy_logo$print_logo(),
      y = tidy_logo$tidy_logo()
    )
    ```
    
    ```bash
    [1] TRUE
    ```
    :::
    
There are multiple methods for importing packages and functions with `box`. The table below list a few of these options:

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

```{r}
#| label: co_box_box_use
#| echo: false
#| eval: true
#| results: asis
co_box(
  color = "b",
  header = "**`box::use()` options**",
  contents = kable_styling(
    kable_input = knitr::kable(box_use_df,
      align = c("l", "l", "r"),
      bootstrap_options = c("striped", "hover", "condensed", "responsive")
    )
  )
)
```

:::

::: {style="font-size: 0.85em; color: [#E74A2F;"}
*These options are also listed on the [package website](https://klmr.me/box/index.html)*
:::

This has been a very brief overview of `box`, so I **highly recommend** consulting the [`box` website](https://klmr.me/box/index.html) and vignettes (especially ["the hierarchy of module environments"](https://klmr.me/box/articles/mod-env-hierarchy.html)). The `rhino` website also has a great overview on using [`box` with shiny apps](https://appsilon.github.io/rhino/articles/explanation/box-modules.html) (I also have a collection of `box` module examples in this [repo](https://github.com/mjfrigaard/rbox/blob/main/boxes.md).)

### Modules 

Now that I've covered a bit on how `box` modules work, I am going to create the *application* modules. New modules should be created in the `app/view/` folder. 

The first module we'll create is the `app/view/inputs.R` module for collecting the user inputs

-   The code below is placed in `app/view/inputs.R`

    ::: {style="font-size: 0.80em;"}
    *Click __Code__ to see `app/view/inputs.R`*
    :::

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: inputs_module
    #| eval: false
    #| code-fold: true
    # app/view/inputs.R
    
    # define module functions
    box::use(
      shiny[
        NS, tagList, selectInput, h3,
        sliderInput, textInput, moduleServer, reactive
      ],
    )
    
    #' input values UI
    #' @export
    ui <- function(id) {
      ns <- NS(id)
      tagList(
        selectInput(
          inputId = ns("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"
        ),
        selectInput(
          inputId = ns("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 = "imdb_rating"
        ),
        selectInput(
          inputId = ns("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"
        ),
        sliderInput(
          inputId = ns("alpha"),
          label = "Alpha:",
          min = 0, max = 1, step = 0.1,
          value = 0.5
        ),
        sliderInput(
          inputId = ns("size"),
          label = "Size:",
          min = 0, max = 5,
          value = 2
        ),
        textInput(
          inputId = ns("plot_title"),
          label = "Plot title",
          placeholder = "Enter plot title"
        )
      )
    }
    
    #' input values server
    #' @export
    server <- function(id) {
      moduleServer(id, function(input, output, session) {
        return(
          list(
            "x" = reactive({
              input$x
            }),
            "y" = reactive({
              input$y
            }),
            "z" = reactive({
              input$z
            }),
            "alpha" = reactive({
              input$alpha
            }),
            "size" = reactive({
              input$size
            }),
            "plot_title" = reactive({
              input$plot_title
            })
          )
        )
      })
    }
    ```
    :::
    
#### Init files 

Back in the `app/view/` folder, I want to use the `app/view/inputs.R` function in the `app/main.R`. I can do this by adding a `__init__.R` file in the `app/view/` folder with the following contents: 

-   The `__init__.R` files are covered [on the `rhino` website](https://appsilon.github.io/rhino/articles/explanation/box-modules.html#init-files): 

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: init_file
    #| eval: false
    #| code-fold: show
    # View: Shiny modules and related code.
    # https://go.appsilon.com/rhino-project-structure
    #' @export
    box::use(
      app/view/inputs)
    ```
    :::
    
-   After composing the module in `app/view/input.R`, I add the `input` module to the `app/main.R` file just like the examples above: 

    -   Note that I've added the necessary functions for using a `fluidPage()` layout (instead of the default `bootstrapPage()`)
    
    ::: {style="font-size: 0.80em;"}
    *Click __Code__ to see `app/main.R`*
    :::

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: inputs_module_in_main
    #| eval: false
    #| code-fold: show
    # app/main.R
    box::use(
      shiny[
        NS, fluidPage, sidebarLayout, sidebarPanel, mainPanel,
        tags, textOutput, moduleServer, renderText
      ],
    )
    # load inputs module ----
    box::use(
      app/view/inputs,
    )
    
    #' @export
    ui <- function(id) {
      ns <- NS(id)
      fluidPage(
        sidebarLayout(
          sidebarPanel(
            # use inputs module UI ----
            inputs$ui(ns("vals"))
          ),
          mainPanel(
            tags$h3("myRhinoApp"),
            tags$h3(textOutput(ns("message")))
          )
        )
      )
    }
    
    #' @export
    server <- function(id) {
      moduleServer(id, function(input, output, session) {
        # use inputs module server ----
        inputs$server("vals")
        output$message <- renderText("Hello!")
      })
    }
    ```
    :::

After saving both `app/view/inputs.R` and `app/main.R`, I can click **Run App** in `app.R` and check the output: 


::: {#fig-input-module .column}
![](input_module.png){height="100%" width="100%" fig-align="center"}

`inputs.R` module
:::

The `display.R` module will show the graph output, but I know this module will require adding the `movies` data *and* the `point_plot()` function (both of which I'll cover below). 

#### Logic 

`rhino` apps come with an `app/logic/` folder, which is used to store code for [*"data manipulation, generating non-interactive plots and graphs, or connecting to an external data source, but outside of definable inputs, it doesn’t interact with or rely on shiny in any way."*](https://appsilon.github.io/rhino/articles/explanation/application-structure.html#logic)

-   The `point_plot()` function definitely meets the definition above, so I will write two modules in `app/logic`: `data` for importing the `movies` data, and `plot` for creating a scatter plot with `point_plot()` 

    -   `app/logic/data.R`: imports `movies` from my [GitHub repo](https://github.com/mjfrigaard/shiny-app-setups/blob/main/data/movies.csv) with all the shiny frameworks. Using data in `box()` modules is tricky (and its a [known](https://appsilon.github.io/rhino/articles/explanation/box-modules.html#known-issues), [issue](https://github.com/klmr/box/issues/219)), but this method works for my application. 
    
    ::: {style="font-size: 0.80em;"}
    *Click __Code__ to see `app/logic/data.R`*
    :::

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: logic_data_module
    #| eval: false
    #| code-fold: show
    # contents of app/logic/data.R
    #' @export
    box::use(
      readr[get_csv = read_csv, cols]
    )
    
    #' @export
    movies_data <- function() {
      raw_csv_url <- "https://bit.ly/3Jds4g1"
      # use alias for read_csv()
      get_csv(raw_csv_url, col_types = cols())
    }
    ```
    :::
    
    -   The second module, `app/logic/plot.R`, holds the `point_plot()` function: 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: logic_point_plot_module
    #| eval: false
    #| code-fold: show
    # contents of app/logic/plot.R
    #' point plot function
    #' @export
    point_plot <- function(df, x_var, y_var, col_var, alpha_var, size_var) {
    
    box::use(
      ggplot2 = ggplot2[...]
    )
    
      ggplot(
        data = df,
        aes(
          x = .data[[x_var]],
          y = .data[[y_var]],
          color = .data[[col_var]]
        )
      ) +
        geom_point(alpha = alpha_var, size = size_var)
    }
    ```
    :::
    
    -   The `__init__.R` file in `app/logic` contains the following: 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: logic_init
    #| eval: false
    #| code-fold: show
    # Logic: application code independent from Shiny.
    # https://go.appsilon.com/rhino-project-structure
    #' @export
    box::use(
      app/logic/data,
      app/logic/plot)
    ```
    :::
    
    -   To make sure everything is working, I'll also include a `app/logic/check-point_plot.R` file that contains the following:
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: check-logic_point_plot_module
    #| eval: false
    #| code-fold: show
    # contents of app/logic/check-point_plot.R
    # contents for app/logic/check-point_plot.R
    
    # load modules from logic folder
    box::use(
      app/logic/data,
      app/logic/plot
    )
    
    # import movies data
    movies <- data$movies_data()
    
    # check point plot
    plot$point_plot(
      df = movies,
      x_var = 'critics_score', # as string
      y_var = 'imdb_rating', # as string
      col_var = 'mpaa_rating', # as string
      alpha_var = 2 / 3,
      size_var = 2
    )
    ```
    :::
    
    -   `check-point_plot.R` imports the two logic modules (`data` and `plot`), creates the movies data, and checks to see if the data and plotting function work: 
    
-   After saving `app/logic/data.R` and `app/logic/plot.R`, I can run the code in `check-point_plot.R` 

::: {#fig-check-point-plot .column}
![](check-point-plot.png){height="100%" width="100%" fig-align="center"}

`app/logic/check-point_plot.R` module
:::

The `app/view/display.R` module can now call `box::use()` to import the `app/logic/data` and `app/logic/plot`.
    
-   The `app/view/display.R` module contains the`ui` and the `server` functions:
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: display_module
    #| eval: false
    #| code-fold: true
    # app/view/display.R
    # import data and plot modules ----
    box::use(
      app/logic/data,
      app/logic/plot
    )
    
    #' display values ui ----
    #' @export
    ui <- function(id) {
    box::use(
      shiny[NS, tagList, tags, plotOutput]
    )
      ns <- NS(id)
      tagList(
        tags$br(),
        tags$blockquote(
          tags$em(
            tags$h6(
              "The code for this application comes from the ",
              tags$a("Building web applications with Shiny",
                href = "https://rstudio-education.github.io/shiny-course/"
              ),
              "tutorial"
            )
          )
        ),
        plotOutput(outputId = ns("scatterplot"))
      )
    }
    
    #' display values server ----
    #' @export
    server <- function(id, var_inputs) {
    
    # load plotting, shiny, tools, and stringr functions
    box::use(
      ggplot2 = ggplot2[...],
      shiny[NS, moduleServer, plotOutput, reactive, renderPlot],
      tools[toTitleCase],
      stringr[str_replace_all]
    )
    
      moduleServer(id, function(input, output, session) {
    
        # use data$movies_data() ----
        movies <- data$movies_data()
    
          inputs <- reactive({
            plot_title <- toTitleCase(var_inputs$plot_title())
            list(
              x = var_inputs$x(),
              y = var_inputs$y(),
              z = var_inputs$z(),
              alpha = var_inputs$alpha(),
              size = var_inputs$size(),
              plot_title = plot_title
            )
          })
    
        output$scatterplot <- renderPlot({
          # use plot$point_plot() ----
          plot <- plot$point_plot(
            df = movies,
            x_var = inputs()$x,
            y_var = inputs()$y,
            col_var = inputs()$z,
            alpha_var = inputs()$alpha,
            size_var = inputs()$size
          )
          plot +
            labs(
              title = inputs()$plot_title,
              x = str_replace_all(
                toTitleCase(
                  inputs()$x
                ),
                "_",
                " "
              ),
              y = str_replace_all(
                toTitleCase(
                  inputs()$y
                ),
                "_",
                " "
              )
            ) +
            theme_minimal() +
            theme(legend.position = "bottom")
        })
      })
    }
    ```
    :::

In `app/main.R`, I can place the `display` module in call to `box::use()`, then:

-   Add `display$ui()` to the `mainPanel()`  

-   In the `server`, the output from `inputs$server()` is assigned to `selected_vars`, which becomes the `var_inputs` input for `display$server()`:

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: display_module_in_main
    #| eval: false
    #| code-fold: show
    # app/view/main.R
    
    # shiny functions
    box::use(
      shiny[NS, fluidPage, sidebarLayout, sidebarPanel,
            mainPanel, tags, textOutput, moduleServer,
            renderText]
    )
    
    # import modules
    box::use(
      # load inputs module ----
      app/view/inputs,
      # load display module ----
      app/view/display
    )
    
    #' myRhinoApp ui
    #' @export
    ui <- function(id) {
      ns <- NS(id)
      fluidPage(
        sidebarLayout(
          sidebarPanel(
            # use inputs module UI ----
            inputs$ui(ns("vals"))
          ),
          mainPanel(
            tags$h3("myRhinoApp"),
            tags$h3(textOutput(ns("message"))),
            # use display module UI ----
            display$ui(ns("disp"))
          )
        )
      )
    }
    
    #' myRhinoApp server
    #' @export
    server <- function(id) {
      moduleServer(id, function(input, output, session) {
        # use inputs module server ----
        selected_vars <- inputs$server(id = "vals")
        # use display module server ----
        display$server(id = "disp",
                       var_inputs = selected_vars)
      })
    }
    ```
    :::
    

After saving `app/view/data.R` and `app/view/display.R` files, the `app/view/` and `app/logic/` folders contain the following modules: 

-   `app/logic/`:

    ::: {style="font-size: 0.80em;"}
    ```{bash}
    #| label: tree-app-logic
    #| eval: false
    #| code-fold: false
    app/logic/
          ├── __init__.R
          ├── check-point_plot.R
          ├── data.R
          └── plot.R
    
    1 directory, 4 files
    ```
    :::
    
-   `app/view/`:
    
    ::: {style="font-size: 0.80em;"}
    ```{bash}
    #| label: tree-app-view
    #| eval: false
    #| code-fold: false
    app/view/
          ├── __init__.R
          ├── display.R
          └── inputs.R
    
    1 directory, 3 files
    ```
    :::

When I click **Run App** in `app.R` I should see the following output:

::: {#fig-complete-rhino .column}
![](complete-rhino.png){height="100%" width="100%" fig-align="center"}

`myRhinoApp`
:::
    
    
### External scripts

It's fairly straightforward to add external resources (i.e., JavaScript, CSS, Sass, etc.) to `rhino` apps. I'll use the [example from the website](https://appsilon.github.io/rhino/articles/tutorial/create-your-first-rhino-app.html#add-javascript-code) to demonstrate because it adds *both* CSS and JavaScript to the codebase.

-   The first place to add code is the UI in `app/main.R`:

    -   Update the call to `box::use()` and include the layout functions (`fluidRow`, `column`, `icon`)

    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: js-main-box
    #| eval: false
    #| code-fold: false
    # app/view/main.R
    
    # shiny functions
    box::use(
      shiny[
        NS, fluidPage, sidebarLayout, sidebarPanel,
        mainPanel, fluidRow, column, tags, icon,
        textOutput, moduleServer, renderText
      ]
    )
    ```
    :::
    
    -   Update the `mainPanel()` to include the title, info button, and display module: 
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: js-main-ui
    #| eval: false
    #| code-fold: show
      mainPanel(
        fluidRow(
          column(
            width = 12,
            tags$h3("myRhinoApp")
          )
        ),
        fluidRow(
          column(
            width = 1,
            offset = 11,
            # example info button ---
            tags$button(
              id = "help-button",
              icon("info")
            )
          )
        ),
        fluidRow(
          column(
            width = 12,
            # use display module UI ----
            display$ui(ns("disp"))
          )
        )
      )
    ```
    :::
    
    -   The CSS added to `app/styles/main.css` is the `container` for the button.
    
    ::: {style="font-size: 0.80em;"}
    ```css
    // app/styles/main.scss
    
    .components-container {
      display: inline-grid;
      grid-template-columns: 1fr 1fr;
      width: 100%;
    
      .component-box {
        padding: 10px;
        margin: 10px;
        box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
      }
    }
    
    h1 {
      text-align: center;
      font-weight: 900;
    }
    
    #help-button {
      position: fixed;
      top: 0;
      right: 0;
      margin: 10px;
    }

    ```
    :::
    
    -   Run `rhino::build_sass()` to create the `app/static/css/app.min.css` file (**requires [node.js](https://nodejs.org/en/)**)
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino_build_sass
    #| eval: false
    #| code-fold: false
    rhino::build_sass()
    ```
    ```bash
    added 748 packages in 49s
    build-sass
    sass --no-source-map --style=compressed 
      ../app/styles/main.scss:../app/static/css/app.min.css
    ```
    :::
    
    -   This tells me `app.min.css` has been added to in `app/static/css/`
    
    ::: {style="font-size: 0.80em;"}
    ```bash
    app/static/
          └── css
               └── app.min.css
    ```
    :::
    
    -   Add the following to `app/js/index.js`:
    
    ::: {style="font-size: 0.80em;"}
    ```js
    export function showHelp() {
    alert('Learn more about shiny frameworks: https://mjfrigaard.github.io/posts/my-rhino-app/');
    }
    ```
    :::
    
    -   Run `rhino::build_js()` to build the `app/static/js/app.min.js` (**requires [node.js](https://nodejs.org/en/)**)
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino_build_js
    #| eval: false
    #| code-fold: false
    rhino::build_js()
    ```
    ```bash
    build-js
    webpack
    
    asset app.min.js 502 bytes [emitted] [minimized] (name: main)
    runtime modules 670 bytes 3 modules
    ../app/js/index.js 126 bytes [built] [code generated]
    webpack 5.69.0 compiled successfully in 1300 ms
    ```
    :::
    
    -   The output tells me the `app.min.js` has been created in `app/static/js`
    
    ::: {style="font-size: 0.80em;"}
    ```bash
    app/static/
          └── js
              └── app.min.js
    ```
    :::
    
    -   Back in `app/main.R`, I add the `onclick` to the `mainPanel()`
    
    ::: {style="font-size: 0.80em;"}
    ```{r}
    #| label: rhino_main_onclick
    #| eval: false
    #| code-fold: show
      mainPanel(
        fluidRow(
          column(
            width = 12,
            tags$h3("myRhinoApp")
          )
        ),
        fluidRow(
          column(
            width = 1,
            offset = 11,
            # example info button ---
            tags$button(
              id = "help-button",
              icon("info"),
              # add 'onclick' after rhino::build_sass()
              # and rhino::build_js()
              onclick = "App.showHelp()"
            )
          )
        ),
        fluidRow(
          column(
            width = 12,
            # use display module UI ----
            display$ui(ns("disp"))
          )
        )
      )
    ```
    :::
    
-   Now when I save everything and click '**Run App**' in `app.R` I should see the info button (and message): 

::: {#fig-js-button .column}
![](js-button.png){height="100%" width="100%" fig-align="center"}

Adding `.js` to `app/js/index.js`
:::

::: {#fig-js-button-onclick .column}
![](js-button-onclick.png){height="100%" width="100%" fig-align="center"}

Adding `.js` to `app/js/index.js` 'on click'
:::


## Use

-   To run a `rhino` application, use `rhino::app()` in the `app.R` file: 

::: {#fig-rhino-app .column}
![](rhino-app.png){height="100%" width="100%" fig-align="center"}

`rhino::app()`
:::


-   Most of the development takes place in `app/logic` and `app/view` (using `box` modules). The separation of the 'business logic' workflow from the 'app view' code is similar to the `dev` folder in `golem` and `leprechaun`, but the modules make it easy to move code and functions back and forth between the two folders. 

-   The `app/js/index.js` and `app/styles/main.css` are used to include any custom CSS or JavaScript code, but you won't create any new files (other than `index.js` and `main.css`).

    -   New JavaScript or CSS code is placed in `app/js/index.js` or `app/styles/main.css` and then the corresponding `rhino` function is run (`rhino::build_js()` or `rhino::build_sass()`). This **requires installing [node.js](https://nodejs.org/en/)**.
    
    -   These functions create output files in `app/static/js/app.min.js` and `app/static/css/app.min.css` that are used in the application.


- `tests/` functions like any `testthat` folder (and can be [used with `shinytest2`](https://appsilon.github.io/rhino/articles/how-to/use-shinytest2.html)) and comes with a helper function, [`rhino::test_r()`](https://appsilon.github.io/rhino/reference/test_r.html)