rhino.qmd

# rhino {#sec-rhino}

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

```{r}
#| label: co_box_dev
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "r", 
  header = "Warning",
  contents = "The contents for section are under development. Thank you for your patience."
)
```

```{r}
#| label: co_box_tldr
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "o", 
  look = "default", hsize = "1.10", size = "1.05",
  header = "TLDR   ![](images/rhino.png){width='10%'}", 
  fold = TRUE,
  contents = "
<br>
**WARNING**: `rhino` isn't like the previous two frameworks we've covered in this section, because `rhino` doesn't create an app-package:
<br>

- `rhino` apps rely on [`renv`](https://rstudio.github.io/renv/articles/renv.html) and [`box`](https://klmr.me/box/) for managing imported dependencies (instead of the `DESCRIPTION` and `NAMESPACE` files in an R package).
  
- `rhino` requires [node.js](https://www.wikiwand.com/en/Node.js), an open-source JavaScript runtime environment.
  
"
)
```

---

This chapter briefly describes a version of `sap` built using [`rhino`](https://appsilon.github.io/rhino/). The resulting app (`rap`) is in the [`21_rhino`](https://github.com/mjfrigaard/sap/tree/21_rhino) branch. 

The branch in this chapter is slightly different than the previous `golem` and `leprechaun` branches, because instead of loading, documenting, and installing `rap`, we're going to re-initialize the IDE by selecting **Session** > **Terminate R...**

::: {#fig-rhino_session_terminate}

![Re-initialize the IDE](images/rhino_session_terminate.png){#fig-rhino_session_terminate width='30%' fig-align='center'}

On the `21_rhino` branch, re-initialize the IDE (instead of loading, documenting, and installing)
:::

When the IDE re-opens, we see the `rap` files and notice the **Build** pane has been removed: 

::: {#fig-rhino_app_ide}

![`rhino` app IDE](images/rhino_app_ide.png){#fig-rhino_session_terminate width='100%' fig-align='center'}

Notice the **Build** pane has been removed from the `21_rhino` branch
:::

The **Build** pane is deactivated because **`rhino` applications aren't R packages**.[^rhino-terminate] 

Launch the application in `rap` by opening the `app.R` file and clicking **Run App** (or by passing `rhino::app()` into the **Console**).

```{r}
#| label: git_box_rap
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  fig_pw = '75%', 
  branch = "21_rhino", 
  repo = 'sap')
```

::: {#fig-rhino_run_app}

![Calling `rhino::app()`](images/rhino_run_app.png){#fig-rhino_run_app width='100%' fig-align='center'}

Running the application in `rap`
:::

:::: {.callout-tip collapse='true' appearance='simple'}

## [Accessing applications]{style='font-weight: bold; font-size: 1.15em;'}

::: {style='font-size: 0.95em; color: #282b2d;'}

I've created the [`shinypak` R package](https://mjfrigaard.github.io/shinypak/) In an effort to make each section accessible and easy to follow:
  
Install `shinypak` using `pak` (or `remotes`):

```{r}
#| code-fold: false 
#| message: false
#| warning: false
#| eval: false
# install.packages('pak')
pak::pak('mjfrigaard/shinypak')
```

Review the chapters in each section:
  
```{r}
#| code-fold: false 
#| message: false
#| warning: false
#| collapse: true
library(shinypak)
list_apps(regex = 'rhino')
```

Launch the app: 

```{r}
#| code-fold: false 
#| eval: false
launch(app = "21_rhino")
```

Download the app: 

```{r}
#| code-fold: false 
#| eval: false
get_app(app = "21_rhino")
```

::: 

::::

[^rhino-terminate]: I re-initialize the session on the `21_rhino` branch so I'm not tempted to load, document, install, or test the code using the IDE.

## `rap` (a `rhino` app)

The files in `rap` are below: 

```{bash}
#| eval: false 
#| code-fold: false 
├── .Rprofile         # <1> 
├── .github/          # <2> 
│   └── workflows     # <2> 
├── .gitignore
├── .lintr            # <3> 
├── .renvignore       # <4> 
├── .rscignore        
├── README.md
├── app
│   ├── js
│   ├── logic
│   ├── main.R
│   ├── static
│   ├── styles
│   └── view
├── app.R
├── config.yml
├── dependencies.R.  # <5> 
├── sap.Rproj
├── renv             # <6> 
│   ├── .gitignore.   
│   ├── activate.R
│   ├── library
│   ├── settings.json
│   └── staging
├── renv.lock       # <6> 
├── rhino.yml
└── tests
    ├── cypress
    ├── cypress.json
    └── testthat

24 directories, 31 files
```
1. Activates the [`renv` package](https://rstudio.github.io/renv/articles/renv.html)
2. CI/CD via [GitHub actions](https://github.com/r-lib/actions)  
3. Lintr (from [`lintr`](https://lintr.r-lib.org/) package)  
4. `renv` ignore (works like `.gitignore`)   
5. `rhino` app dependencies 
6. `renv` library of packages in app project   

As we can see, most of the standard R package folders and files are missing from `rap`, because `rhino` applications use the [`box` package](https://klmr.me/box/) for importing dependencies and organizing code.[^rhino-box-depends] 

## `rhino` features

The [`rhino` website](https://appsilon.github.io/rhino/articles/explanation/application-structure.html) explains the philosophy behind the application structure above, so I won't repeat that information here. However, I highly recommend reading the available documentation on [`rhino`](https://appsilon.github.io/rhino/articles/tutorial/create-your-first-rhino-app.html) and [`box`](https://klmr.me/box/articles/box.html) before deciding to adopt this framework.[^rhino-recommended-documentation] 


[^rhino-box-depends]: Imported dependencies in `rhino` apps use [`box` modules](https://klmr.me/box/articles/box.html) instead of the `DESCRIPTION` and `NAMESPACE`.

[^rhino-recommended-documentation]: Be sure to read up on [testing box modules](https://klmr.me/box/articles/testing.html) and `rhino` applications [with cypress](https://appsilon.github.io/rhino/articles/tutorial/write-end-to-end-tests-with-cypress.html) and [`shinytest2`](https://appsilon.github.io/rhino/articles/how-to/use-shinytest2.html). 

## `box` modules

A `box` module (not to be confused with a Shiny module) is a collection of `.R` scripts in a specified folder. The modules in a new `rhino` app are stored in the `app/logic/` and `app/view/` folders:[^rhino-code-structure]

[^rhino-code-structure]: `rhino` [recommends](https://appsilon.github.io/rhino/articles/explanation/application-structure.html#philosophy) placing non-Shiny code in the `app/logic` folder and keeping all Shiny modules and reactive code in `app/view`.

```{bash}
#| eval: false 
#| code-fold: false 
app
├── js/ # <1>
├── logic/ # <2>
├── main.R # <3>
├── static/ # <4>
├── styles/ # <5>
└── view/ # <6>

6 directories, 1 file
```
1. JavaScript code
2. Non-shiny code  
3. Primary app file  
4. Static `.js` or `.css`  
5. App CSS files 
6. Shiny modules and app code

### Utility functions 

In `rap`, I've placed the non-Shiny utility functions (i.e., the business logic) in `app/logic`:

```{bash}
#| eval: false 
#| code-fold: false 
app/logic
├── __init__.R
├── data.R # <1>
└── plot.R # <2>

1 directory, 4 files
```
1. Load `movies` data  
2. `scatter_plot()` utility function 

### Shiny modules

Our Shiny `box` modules are placed in `app/view`, and separated into `inputs` and `display`: 

```{bash}
#| eval: false 
#| code-fold: false 
app/view
├── __init__.R
├── display.R # <1> 
└── inputs.R # <2>

1 directory, 3 files
```
1. similar to the code from `R/mod_var_input.R`
2. similar to the code from `R/mod_scatter_display.R`

`app/view/inputs` collects and returns the reactive values from the UI. The `app/view/display` module includes the `app/logic/data` and `app/logic/plot` modules.

```{r}
#| eval: false 
#| code-fold: false
# app/view/display.R

# import data and plot modules
box::use(
  app / logic / data,
  app / logic / plot
)
```

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

The `app/main.R` file contains the primary UI and Server functions for the application. This file adds the `shiny` functions *and* the `inputs` and `display` modules from `app/view`: 

```{r}
#| eval: false 
#| code-fold: false
# app/main.R

# shiny functions
box::use(
  shiny[
    NS, fluidPage, sidebarLayout, sidebarPanel,
    mainPanel, fluidRow, column, tags, icon,
    textOutput, moduleServer, renderText
  ]
)

# import modules
box::use(
  # load inputs module ----
  app / view / inputs,
  # load display module ----
  app / view / display
)
```

Note that we don't need to import `app/logic` modules in `app/main.R`, because they're imported in their respective `app/view` modules. 


## Tests

`rhino` apps have support for testing with `testthat`, `shiny::testServer()`, `shinytest2`, and [Cypress](https://appsilon.github.io/rhino/articles/tutorial/write-end-to-end-tests-with-cypress.html). 

```{bash}
#| eval: false 
#| code-fold: false 
tests/
├── cypress                 # <1>
│   └── integration
│       └── app.spec.js
├── cypress.json            # <1>
└── testthat                # <2>
    └── test-main.R         # <2>

4 directories, 3 files
```
1. Cypress test infrastructure  
1. `testthat` test infrastructure  

Below is the boilerplate test code in the `tests/testthat/test-main.R` file:

```{r}
#| eval: false 
#| code-fold: false 
box::use(                # <1>
  shiny[testServer], 
  testthat[...],
)

box::use(
  app/main[...],
)                       # <1>

test_that("main server works", {     # <2>
  testServer(server, {
    expect_equal(output$message, "Hello!")
  })
}) # <2>
```
1. `box` module importing test package functions
2. Using `shiny::testServer()` and `testthat::test_that()` functions in test. 

I've included tests for the utility functions and modules in the `21_rhino` branch, but I'll cover testing with rhino elsewhere.[^testing-rhino-apps]

[^testing-rhino-apps]: See the [Shiny frameworks](https://mjfrigaard.github.io/sfw/) supplemental website for more information on testing your `rhino` app.

## `rhino` dependencies 

In `rhino` apps, dependencies are managed by [`renv`](https://rstudio.github.io/renv/articles/renv.html) and the `dependencies.R` file. The `renv` package is designed to, 

> *"create[s] and manage[s] project-local R libraries, save[s] the state of these libraries to a 'lockfile', and later restore[s] the library as required."* [^rhino-renv-description] 

The `rhino::pkg_install()` helper function updates *both* the `dependencies.R` file and `renv` library. Using `dependencies.R`, `renv`, and `box` modules removes the need to manage dependencies in a `DESCRIPTION` or `NAMESPACE` file.[^rhino-renv-config]

[^rhino-renv-description]: As described in `renv`'s [DESCRIPTION file](https://github.com/rstudio/renv/blob/main/DESCRIPTION)

[^rhino-renv-config]: Be sure to read the [`renv` configuration article](https://appsilon.github.io/rhino/articles/explanation/renv-configuration.html) for a better understanding on how it works with rhino apps.

## Recap {.unnumbered}

```{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 &emsp; ![](images/rhino.png){width='10%'}",
  fold = FALSE,
  contents = "
<br>

`rhino` takes a novel and innovative approach to developing Shiny applications (and covering all the ways they differ from app-packages is beyond the scope of this book). Feel free to review the code in the [`21_rhino` branch](https://github.com/mjfrigaard/sap/tree/21_rhino) for a better understanding of how the `box` modules are structured and used within the `ui` and `server`. 

The `rhino` framework isn't used as wildly `golem`,[^rhino-cran-downloads] but it's been gaining popularity (and has been used in a recent [pilot FDA submission](https://github.com/appsilon/rhino-fda-pilot)). 

![`rhino` CRAN downloads](images/rhino_cran_downloads.png){width='100%' fig-align='center'}")
```



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

[^rhino-cran-downloads]: Check for yourself on  [cran-downloads](https://hadley.shinyapps.io/cran-downloads/)