08-step-by-step-prototype.Rmd

# (PART) Step 2: Prototype {.unnumbered}

# Setting up for Success with `{golem}` {#setting-up-for-success}

Before starting to prototype and build anything, initialize a `{golem}` [@R-golem] project!
This will help you start your application on solid ground, and once the project is ready to be filled, you can start prototyping right inside it.

The general workflow for "prototype and build" is the following: the project manager sets up a `{golem}` project, where the first steps are filled, the general structure (potentially with `{shiny}` module) is set, and then the project is registered to the version control system.
Once we have this structure, package and modules combined, we can start prototyping the UI inside the module, work on the CSS and JavaScript elements that might be needed, and the back-end functionalities inside Rmarkdown files.
And then, once these two prototyping sides are finished, we work on the integration of everything inside the reactive context.

In this chapter and in chapter 11, we will be presenting the `{golem}` package in more depth.
`{golem}` is a framework that standardizes the process of building production-ready `{shiny}` applications.

## Create a `{golem}`

Once `{golem}` is installed and available on your computer, you can go to File \> New Project... in RStudio, and choose "Package for `{shiny}` app Using golem" input.

If you want to do it through the command line, you can use:

```{r 08-step-by-step-prototype-1, eval = FALSE}
# Creating a golem project from the command line
golem::create_golem(path = "path/to/package")
```

Once you have that, a new project will be launched.
Here is the structure of this project:

```{r 08-step-by-step-prototype-2, include=FALSE}
try({
  fs::file_delete(
    fs::path(
      here::here("golex"),
      "inst/app/www/plop.js"
    )
  )
  fs::file_delete(
    fs::path(
      here::here("golex"),
      "inst/app/www/script.js"
    )
  )
  fs::file_delete(
    fs::path(
      here::here("golex"),
      "inst/app/www/custom.css"
    )
  )
  fs::file_delete(
    fs::path(
      here::here("golex"),
      "R/mod_my_first_module.R"
    )
  )
})

```

```{r 08-step-by-step-prototype-3, comment="", eval = FALSE}
# This is what a default {golem} project looks like
# Listing the files from the `golex` project using {fs}
fs::dir_tree("golex")
```

```{r include = FALSE}
fs::dir_delete("golex")
testthat::with_mocked_bindings(
  .package = "usethis",
  allow_nested_project = function(){
    return(TRUE)
  },
  code = {
  golem::create_golem("golex", open = FALSE)
})
```


```{r echo = FALSE}
fs::dir_tree("golex")

```

```{r include = FALSE}
fs::dir_delete("golex")
source("golembuild.R")
```

If you already have some experience with R packages, most of these files will appear very familiar to you.
That's because a `{golem}` app IS a package, so it uses the standard R package structure (and yes, the good news is that everything you know about R packages will work in a `{golem}`-based application).

## Setting things up with `dev/01_start.R`

Once you have created your project, the first file that opens is `dev/01_start.R`.
This file contains a series of commands to run once, at the start of the project.

### Fill the DESCRIPTION and set options

First, fill the DESCRIPTION file by adding information about the package that will contain your app:

```{r 08-step-by-step-prototype-4, eval = FALSE}
golem::fill_desc(
  # The Name of the package containing the App
  pkg_name = "ipsumapp",
  # The Title of the package containing the App
  pkg_title = "PKG_TITLE",
  # The Description of the package containing the App
  pkg_description = "PKG_DESC.",
  # Your First Name
  author_first_name = "AUTHOR_FIRST",
  # Your Last Name
  author_last_name = "AUTHOR_LAST",
  # Your Email
  author_email = "AUTHOR@MAIL.COM",
  # The URL of the GitHub Repo (optional)
  repo_url = NULL
)
```

Then, call the `golem::set_golem_options()` function, which will add information to the `golem-config.yml` file, and set the `{here}` [@R-here] package root sentinel.
`{here}` is an R package designed to handle directory management in R.
When used in combination with `{golem}`, `{here}` helps ensure that everything you do in your console is performed relatively to the root directory of your project: the one containing the `DESCRIPTION` of your application.
That way, even if you change the working directory of your R session to a subfolder, you will still be able to create modules and CSS files in the correct folder.

### Set common files

If you want to use the MIT license, add README, a code of conduct, a lifecycle badge, and NEWS.

```{r 08-step-by-step-prototype-5, eval = FALSE}
# You can set another license here
usethis::use_mit_license( name = "Golem User" )
# Add a README, Code of Conduct, lifecycle badge and NEWS.md
# file to your application
usethis::use_readme_rmd( open = FALSE )
usethis::use_code_of_conduct()
usethis::use_lifecycle_badge( "Experimental" )
usethis::use_news_md( open = FALSE )
```

It's also where you will be invited to use `Git`:

```{r 08-step-by-step-prototype-6, eval = FALSE}
usethis::use_git()
```

### Use recommended elements

`golem::use_recommended_tests()` and `golem::use_recommended_deps()` sets a default testing infrastructure and adds dependencies to the application.

### Add utility functions

These two functions add a file with various functions that can be used along the process of building your app.

See each file in detail for a description of the functions.

```{r 08-step-by-step-prototype-7, eval = FALSE}
# These files will create R/golem_utils_ui.R
# and R/golem_utils_server.R
golem::use_utils_ui()
golem::use_utils_server()
```

In this file, you will, for example, find `list_to_li()`, which is a function to turn an R list into an HTML list or `with_red_star()`, a function to add a small red star after a UI input, useful for communicating that an input is mandatory.

### Changing the favicon

Favicons are the small icons located on the tab of your browser: in the default application, this favicon is the `{golem}` hex.

If you want to change the default favicon:

```{r 08-step-by-step-prototype-8, eval = FALSE}
golem::use_favicon( path = "path/to/favicon")
```

You're now set!
You've successfully initiated the project and can go to `dev/02_dev.R`.

## Setting infrastructure for prototyping

### Add modules in `dev/02_dev.R`

The `golem::add_module()` function creates a module in the `R` folder.
The file and the modules will be named after the `name` parameter, by adding `mod_` to the R file, and `mod_*_ui` and `mod_*_server` to the UI and server functions.

```{r 08-step-by-step-prototype-9, eval = FALSE}
# Creating a module skeleton
golem::add_module(name = "my_first_module")
```

```{r 08-step-by-step-prototype-10, echo = FALSE}
golem::add_module(name = "my_first_module", here::here("golex"), open = FALSE)
```

The new file will contain:

```{r 08-step-by-step-prototype-11, echo = FALSE, comment=""}
readLines("golex/R/mod_my_first_module.R") %>%
  cat(sep = "\n")
```

Note that to avoid making errors when putting these into your app, the end of the file will contain code that has to be copied and pasted inside your UI and server functions.

This is where you will be adding the core of your app.
The first time, these modules will contain prototyped UI for the application, and once the application is ready to be integrated, you will add the core logic here.

### Add CSS and JS files

Adding some infrastructure for JavaScript and CSS files from the very beginning can also formalize the set-up: you are giving the rest of your team a specific file where they can write the JavaScript and CSS code.

```{r 08-step-by-step-prototype-12, eval = FALSE}
golem::add_js_file( "script" )
```

```{r 08-step-by-step-prototype-13, include = FALSE}
golem::add_js_file("script", here::here("golex"), open = FALSE)
```

will generate the following file:

```{r 08-step-by-step-prototype-14, comment="", echo=FALSE}
readLines("golex/inst/app/www/script.js") %>%
  cat(sep = "\n")
```

Here, you will have an infrastructure for launching JavaScript code once the application is ready (this code is standard `jQuery` format: we will be back to JavaScript at the end of this book).

```{r 08-step-by-step-prototype-15, eval = FALSE}
golem::add_js_handler( "handlers" )
```

```{r 08-step-by-step-prototype-16, include = FALSE}
golem::add_js_handler("handlers", here::here("golex"), open = FALSE)
```

will generate the following file:

```{r 08-step-by-step-prototype-17, comment="", echo=FALSE}
readLines( "golex/inst/app/www/handlers.js" ) %>%
  cat(sep = "\n")
```

As you can see, there is already a skeleton for building `{shiny}` JavaScript handlers.

```{r 08-step-by-step-prototype-18, eval = FALSE}
golem::add_css_file( "custom" )
```

```{r 08-step-by-step-prototype-19, include = FALSE}
golem::add_css_file("custom", here::here("golex"), open = FALSE)
```

will create a blank CSS file inside the `inst/app/www` folder.

Note that as you are building your application with `{golem}`, these files will be linked automatically to your application.