leprechaun.qmd

# leprechaun {#sec-leprechaun}

```{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 this section are under development. Thank you for your patience."
)
```


```{r}
#| label: co_box_tldr
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "b", 
  look = "default", hsize = "1.10", size = "1.05",
  header = "TLDR    ![](images/leprechaun.png){width='10%'}", 
  fold = TRUE,
  contents = "
<br>
  
- `leprechaun` has many of the same features found in the `golem` framework, but without the added dependencies (think `golem` à la carte)

- Helper functions for creating modules, `app.R` files, JavaScript, CSS, SCSS, HTML, etc.
  
- `leprechaun` apps also come 'pre-packaged' with UI, server, and standalone app functions
  
- Additional features and functionality are added with a variety of `use_*` functions 'bundle' resources in the `inst/` folder: 
  
  - `use_sass()`, `use_config()`, `use_packer()` (with `use_js_utils()`), etc.
  
"
)
```

------------------------------------------------------------------------

This chapter walks through building a version of the `sap` with the [`leprechaun`](https://leprechaun.opifex.org/#/) framework. The resulting app-package (`lap`) is in the [`19_leprechaun`](https://github.com/mjfrigaard/sap/tree/19_leprechaun) branch.

```{r}
#| eval: false
#| code-fold: false
install.packages("leprechaun")
library(leprechaun)
```

The version/description of `leprechaun` used in this Shiny app-package is: 

```{r}
#| echo: false
pkg_info('leprechaun', gt = TRUE)
```

After checking out the `19_leprechaun` branch, be sure to load, document, and install the application.

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

## `lap` (a `leprechaun` app-package)

`lap` exports the `movies` data and the standalone app function, `run()`.

```{r}
#| eval: false
#| code-fold: false
library(lap)
lap::run()
```

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

::: {#fig-leprechaun_run}
![`lap` movies app](images/leprechaun_run.png){width="100%" align="center"}

After loading, documenting, and installing `lap`, launch the movies with `run()`
:::

::: {.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 = 'leprechaun')
```

Launch the app:

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

Download the app:

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

## Set up

Creating a new leprechaun app-package can be done with `usethis::create_package()`[^leprechaun-1] (which we covered in [Packages](packages.qmd)). After your app-package is created, `leprechaun::scaffold()` builds the core app files:[^leprechaun-2]

[^leprechaun-1]: Remember to provide a list of fields to `usethis::create_package()` for the `DESCRIPTION` file (or edit this manually).

[^leprechaun-2]: `leprechaun::scaffold()` has arguments for `ui` (`fluidPage` or `navbarPage`) `bs_version` (bootstrap version) and `overwrite` (if you need to start over).

**Code files**: the code files in new `leprechaun` apps include the following:

-   `_disable_autoload.R`: Disables `shiny::loadSupport()` (covered in [Launch](launch.qmd))

-   `assets.R`: includes `serveAssets()` for serving JavaScript files, `remove_modules()` and `get_modules()` for adding/removing modules, and the `collapse_files()` helper function for collapsing files.[^leprechaun-3]

-   `input-handlers.R`: `leprechaun_handler_df()` and `leprechaun_handler_list()` are helper functions for including data and lists *"from Websocket"*.[^leprechaun-4]

-   `leprechaun-utils.R`: includes a `make_send_message()` function for *"send custom messages to the front-end"* with the *"namespace carried along"*. Read below for demonstration of how this is used.[^leprechaun-5]

-   `run.R`: the standalone app function for your leprechaun app (covered in [Launch](launch.qmd)). <br><br>

-   `server.R` & `ui.R` are applications primary UI and server functions.

    -   `ui`: contains the application UI and the `assets()` function (which calls `serveAssets()` covered above).[^leprechaun-6]
    -   `server.R`: creates `send_message` from `make_send_message(session)` (covered below).[^leprechaun-7]

-   `zzz.R` is a utility function file that holds the `.onLoad()` function for adding external resources (using methods covered in [Resources](resources.qmd)).[^leprechaun-8]

[^leprechaun-3]: [Link to `R/assets.R`]((https://github.com/mjfrigaard/sap/blob/19_leprechaun/R/assets.R)) file.

[^leprechaun-4]: [Link to `R/input-handlers.R`]((https://github.com/mjfrigaard/sap/blob/19_leprechaun/R/input-handlers.R)) file.

[^leprechaun-5]: [Link to `R/leprechaun-utils.R`](https://github.com/mjfrigaard/sap/blob/19_leprechaun/R/leprechaun-utils.R) file.

[^leprechaun-6]: [Link to `R/ui.R`]((https://github.com/mjfrigaard/sap/blob/19_leprechaun/R/ui.R)) file.

[^leprechaun-7]: [Link to `R/server.R`]((https://github.com/mjfrigaard/sap/blob/19_leprechaun/R/server.R)) file.

[^leprechaun-8]: [Link to `R/zzz.R`]((https://github.com/mjfrigaard/sap/blob/19_leprechaun/R/zzz.R)) file.

```{bash}
#| eval: false
#| code-fold: false
R
├── _disable_autoload.R # <1>
├── assets.R # <2>
├── input-handlers.R # <3>
├── leprechaun-utils.R # <4>
├── run.R # <5>
├── server.R # <6>
├── ui.R # <7>
└── zzz.R # <8>

1 directory, 8 files
```

1.  Disables `shiny::loadSupport()`\
2.  Includes functions for serving JavaScript files, adding/removing modules, and collapsing files.
3.  Utility functions for handling `list`s and `data.frame`s\
4.  Contains the `make_send_message()` function for 'send\[ing\] custom messages to the front-end'
5.  Standalone app function\
6.  App primary server function\
7.  App primary ui function\
8.  Includes wrapper for adding external files

-   **Adding dependencies**: `shiny`, `bslib`, `htmltools` and `pkgload` should be added to the `DESCRIPTION` with `usethis::use_package()` (covered in the [Dependencies](dependencies.qmd) chapter).

```{bash}
#| eval: false
#| code-fold: false
Imports: 
    bslib,
    htmltools,
    shiny
Suggests: 
    pkgload
```

The `lap` folder structure should look familiar if you've been following along with the previous chapters. The standard R package files (`DESCRIPTION`, `NAMESPACE`, and `.Rproj`) are accompanied by a `.leprechaun` lock file.

```{bash}
#| eval: false
#| code-fold: false
lap/
├── .leprechaun
├── DESCRIPTION
├── NAMESPACE
└── sap.Rproj

```

The initial call to `leprechaun::scaffold()` creates the following folders in the `inst/` folder (recall that `inst/` contents are available when the package is installed).

```{bash}
#| eval: false
#| code-fold: false
inst/
├── assets
├── dev
├── img
└── run
    └── app.R

5 directories, 1 file
```

`inst/run/app.R` contains a call to `leprechaun::build()`, `pkgload::load_all()`, then a call to the standalone app function, `run()`.[^leprechaun-9]

[^leprechaun-9]: [Link to `inst/run/app.R`](https://github.com/mjfrigaard/sap/blob/19_leprechaun/inst/run/app.R) file.

## Development

**Code files**: new code files in `leprechaun` apps can be created with `usethis::use_r()` or with a helper function:

-   Create modules with `add_module()`. Modules created with `add_module("name")` will have:[^leprechaun-10]
    -   A module file with a `module_name` prefix (`R/module_name.R`)\
    -   A module UI function: `nameUI()`\
    -   A module server function: `name_server()`\
        <br>
-   Create an `app.R` file with `add_app_file()`. This includes a call to `pkgload::load_all()` and `run()`.[^leprechaun-11] <br><br>
-   **App files**: `R/run.R` contains functions for running the app.[^leprechaun-12] <br><br>
-   Add the modules to `R/ui.R` and `R/server.R`. <br>
    -    `R/server.R` includes a call to `send_message` by default.[^leprechaun-13]
    -    `R/ui.R` holds the `ui()` and `assets()` functions.[^leprechaun-14]

[^leprechaun-10]: `leprechaun` modules do not have the same naming conventions as `golem` (or that I've recommended throughout this book).

[^leprechaun-11]: `pkgload::load_all()` has `reset` set to `TRUE` and `helpers` set to `FALSE`.

[^leprechaun-12]: `R/run.R` includes functions for running the production (`run()`) and development (`run_dev()`) version of the application.

[^leprechaun-13]: `make_send_message()` is in `R/leprechaun-utils.R`.

[^leprechaun-14]: `assets()` loads the resources called in the `R/assets.R` file with the `serveAssets()` function.

-   **Utility function**: `R/utils_scatter_plot.R` holds the `scatter_plot()` utility function.[^leprechaun-15] <br> 
-   **Adding files**: The `R/zzz.R` file contains the `.onLoad()` function, which wraps `system.file('img', package = 'lap')` and `addResourcePath()` for including external resources. <br><br>

[^leprechaun-15]: The same `scatter_plot()` function from `sap` (i.e, imports `.data` from `rlang`)

```{bash}
#| eval: false
#| code-fold: false
R
├── module_plot_display.R
├── module_var_input.R
├── run.R
├── server.R
├── ui.R
└── utils_scatter_plot.R

1 directory, 6 files
```

### Data files

-   **Including data files**: the `movies.RData` data was moved into `inst/extdata`, then loaded into `data/` with the script created with `usethis::use_data_raw('movies')` (similar to methods covered in the [Data](data.qmd) chapter):

```{bash}
#| eval: false
#| code-fold: false
data-raw/
└── movies.R

1 directory, 1 file
```

```{bash}
#| eval: false
#| code-fold: false
└── extdata
      └── movies.RData
1 directory, 1 file
```

```{bash}
#| eval: false
#| code-fold: false
data
└── movies.rda

1 directory, 1 file
```

### Adding features

The `leprechaun` workflow involves a combination of `use_` functions that are combined with `leprechaun::build()` to add various functionality to your application. I'll demonstrate three options in the sections below:

#### Use `packer`

I'll demo using the `make_send_message()` from the JavaScript example on the [package website](https://leprechaun.opifex.org/#/examples/basic#javascript):

-   Run `packer::scaffold_leprechaun()` <br><br>
    -   *Don't be alarmed when calling [`packer::scaffold_leprechaun()`](https://packer.john-coene.com/#/references/scaffold_leprechaun) downloads multiple folders into the root directory of your `leprechaun` app-package.* [^leprechaun-16] <br><br>
-   Run `leprechaun::use_packer()` <br><br>
-   Run `leprechaun::build()`

[^leprechaun-16]: `srcjs/`, `package-lock.json`, `package.json`, `webpack.common.js`, `webpack.dev.js` and `webpack.prod.js` are added to the `.Rbuildignore` (and `node_modules/` is added to the `.gitignore`).

This creates `inst/tidy-data/packer.R` and `inst/assets/index.js`.

```{bash}
#| eval: false
#| code-fold: false
inst
├── assets
│   └── index.js
├── dev
│   └── packer.R
├── extdata
│   └── movies.RData
├── img
└── run
    └── app.R
```

Assign the output from `make_send_message()` to `send_message()` in `R/server.R`, then pass the `msgId` and `text` of the message:

```{r}
#| eval: false
#| code-fold: false
server <- function(input, output, session){
	## New code -->
  send_message <- make_send_message(session) # <1>
  
	send_message("show-packer", # <2>
				  text = "this message is from your R/server.R file") # <2>
	
   selected_vars <- var_input_server("vars")

   plot_display_server("plot", var_inputs = selected_vars)
   ## New code <--

}
```

1.  Create `send_message()`\
2.  Use `send_message()` to send message the UI.

After loading, documenting, and installing your app-package:

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

Run the application:

```{r}
#| eval: false
#| code-fold: false
lap::run()
```

::: {#fig-leprechaun_send_message_server}
![`send_message()` in `lap::run()`](images/leprechaun_send_message_server.png){width="70%" align="center"}

Adding the `make_send_message()` functionality to `R/server.R`
:::

#### Add images

Adding images is simplified with the `.onLoad()` function, which I'll demonstrate by adding the `leprechaun.jpg` image file to the UI function.

-   Place the `leprechaun.jpg` file in `inst/img/` <br><br>
-   Add the `img/` path to the code to UI:

```{r}
#| eval: false
#| code-fold: false
tags$img(
  src = "img/leprechaun.jpg", 
  height = "25%", 
  width = "25%")
```

-   run `devtools::load_all()`, `devtools::document()`, and `devtools::install()`, then run the application with `run()`:

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

```{r}
#| eval: false
#| code-fold: false
lap::run()
```

::: {#fig-leprechaun_add_image}
![`leprechaun.jpg` in `R/ui.R`](images/leprechaun_add_image.png){width="100%" fig-align="center"}

Adding images to `inst/img/`
:::

#### Use Sass

To add Sass styling, I can use `leprechaun`'s [`use_sass()`](https://leprechaun.opifex.org/#/reference/use_sass) function

-   Run `leprechaun::use_sass()` <br><br>
-   a `scss/` folder will be created that contains `_core.scss` and `main.scss`

```{bash}
#| eval: false
#| code-fold: false
scss
├── _core.scss
└── main.scss

1 directory, 2 files
```

-   The original `_core.scss` file is below

``` scss
html{
    .error {
        color: red
    }
}
```

-   Change the `color:` from `red` to green (`#38B44A`) using `$accent: #38B44A;`

``` scss
$accent: #38B44A;

html{
    h1 {
        color: $accent;
    }
}
```

-   Save this file and run [`leprechaun::build()`](https://leprechaun.opifex.org/#/reference/build):[^leprechaun-17]

[^leprechaun-17]: The `scss` folder in the root directory is used by `leprechaun::build()` to create `inst/tidy-data/sass.R`.

```{r}
#| label: build-leprechaun
#| code-fold: false
#| eval: false
leprechaun::build()
```

```{bash}
#| label: build-running-sass-leprechaun
#| code-fold: false
#| eval: false
✔ Running packer.R
✔ Bundled       
✔ Running sass.R
```

-   Once again, run `devtools::load_all()`, `devtools::document()`, and `devtools::install()`, then run the application with `run()`:

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

```{r}
#| eval: false
#| code-fold: false
lap::run()
```

::: {#fig-leprechaun_add_scss}
![](images/leprechaun_add_scss.png){width="100%" fig-align="center"}

Running `lap` with new Sass
:::

#### New `root` folders

It's important to note that adding features to your `leprechaun` app-package will add non-standard directories to the root folder:

```{bash}
#| eval: false
#| code-fold: false
├── node_modules/ <- too many sub-folders to list here!
├── package-lock.json
├── package.json
├── scss/
│   ├── _core.scss
│   └── main.scss
├── srcjs/
│   ├── config
│   ├── index.js
│   └── modules
├── webpack.common.js
├── webpack.dev.js
└── webpack.prod.js
```

These folders are necessary for adding JavaScript/SCSS functionality, so don't remove them (just make sure they're added to the `.Rbuildignore`/`.gitignore`)

## Tests

`leprechaun` doesn't any specific support for testing (like the `golem` framework), but we can create tests using any combination of `testthat`, `testServer()`, and `shinytest2`.

## `lap` dependencies

It's also worth noting that using the `leprechaun` framework doesn't add itself as a dependency:

```{r}
#| eval: false 
#| code-fold: false
# in the 19_leprechaun branch of sap
pak::local_deps_explain(deps = 'leprechaun', root = ".")
```

```{verbatim}
x leprechaun  
```

## 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/leprechaun.png){width='8%'}",
  fold = FALSE,
  contents = "
<br>

[`leprechaun`](https://leprechaun.opifex.org/#/) apps are built using the same methods as app-packages (`devtools` and `usethis`), and are intended to be a 'leaner and smaller' version of `golem`.

> *'it generates code and does not make itself a dependency of the application you build; this means applications are leaner, and smaller'*

`leprechaun` is similar to `golem` in that it 'bundles' various app-package development functions into helper/utility functions. For example, the `.onLoad()` function saves some time (at the cost of making your app code less clear and explicit). 

`leprechaun` also relies on external packages like [`packer`](https://packer.john-coene.com/#/) to integrate and bundle external code files, so becoming more familiar with these packages will extend what you can build with `leprechaun`.")
```

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