Chapter 12 Building app with {golem}

Now the UI and the features are set, time to work on the backend.

This part is pretty standard — everybody can now work on the implementation of the functions that process the app inputs, in their own modules. As the UI, functionalities and modules have been defined in the previous steps, everyone (well, in theory) knows what they have to work on.

And also, as said before, there should be no “surprise implementation”, as the app has been well defined before.

12.1 Using {golem}

12.1.1 Create a package

Once the package is installed, you can got to File > New Project… in RStudio, and choose “Package for Shiny App Using golem” input.

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

golem::create_shiny_template(path = "path/to/package")

This command allows you to create “illegally-named” package (for example, 1234) by passing the check_name argument to FALSE. Note that this is not recommended and should only be done if you know what you are doing.

Once you’ve got that, a new RStudio project will be launched. Here is the structure of this project:

DESCRIPTION               
¦--dev/          
  ¦--01_start.R           
  ¦--02_dev.R           
  ¦--03_deploy.R           
  ¦--run_dev.R
¦--inst/ 
  ¦--app                
    ¦--server.R       
    ¦--ui.R           
    ¦--www/          
      ¦--favicon.ico
¦--man/ 
    ¦--run_app.Rd      
NAMESPACE
myapp.Rproj
¦--R/ 
  ¦--app_server.R       
  ¦--app_ui.R           
  ¦--run_app.R      

If you’re already familiar with R packages, most of these files will appear very familiar to you. That’s because a {golem} app IS a package.

  • DESCRIPTION & NAMESPACE: Package meta-data.

  • dev/: Scripts that will be used along the process of developing your app.

  • inst/app: You’ll add external dependencies in www (images, css, etc). Don’t touch app_ui and app_server.

  • man: Package doc, to be generated by R.

  • myapp.Rproj: RStudio project.

  • R/app_server.R, R/app_ui.R: Top level UI and server elements.

  • R/run_app.R: a function to configure and launch the application.

12.2 dev/01_start.R

Once you’ve 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.

12.2.1 Fill the DESC

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

golem::fill_desc(
  pkg_name = "shinyexample", # The Name of the package containing the App 
  pkg_title = , # The Title of the package containing the App 
  pkg_description = , # The Description of the package containing the App 
  author_first_name = , # Your First Name
  author_last_name = ,  # Your Last Name
  author_email = ,      # Your Email
  repo_url = NULL)      # The (optional) URL of the GitHub Repo

12.2.2 Set common Files

If you want to use the MIT licence, README, code of conduct, lifecycle badge, and news

usethis::use_mit_license(name = "Your Name")  # You can set another licence here
usethis::use_readme_rmd()
usethis::use_code_of_conduct()
usethis::use_lifecycle_badge("Experimental")
usethis::use_news_md()

12.2.3 Add a data-raw folder

If you have data in your package

usethis::use_data_raw()

12.2.4 Init Tests

Create a template for tests:

golem::use_recommended_tests()

12.2.6 Add various tools

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

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

golem::use_utils_ui()
golem::use_utils_server()

12.2.7 If you want to change the default favicon

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.

rstudioapi::navigateToFile("dev/02_dev.R")

12.3 Day to Day Dev with {golem}

Now that you’re all set with your project init, time to move to development :)

App development should happen through the dev/02_dev.R file, which contains common commands for developping.

12.4 Launching the app

To run the app, go to the dev/run_dev.R file, and run the all thing.

12.5 dev/02_dev.R

12.5.1 Add modules

The golem::add_module() functions 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.

golem::add_module(name = "my_first_module") # Name of the module

The new file will contain:

# mod_UI
mod_my_first_module_ui <- function(id){
  ns <- NS(id)
  tagList(
  
  )
}

mod_my_first_module_server <- function(input, output, session){
  ns <- session$ns
}
    
## To be copied in the UI
# mod_my_first_module_ui("my_first_module_1")
    
## To be copied in the server
# callModule(mod_my_first_module_server, "my_first_module_1")

In order not to make 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.

12.5.2 Add dependencies

To be called each time you need a new package as a dependency:

usethis::use_package("pkg")

12.5.3 Add tests

Add more tests to your application:

usethis::use_test("app")

12.5.4 Add a browser button

Learn more about this: https://rtask.thinkr.fr/blog/a-little-trick-for-debugging-shiny/

golem::browser_button()

12.5.5 Add external files

These functions create external dependencies (JavaScript and CSS). add_js_file() creates a simple JavaScript file, while add_js_handler() adds a file with a skeleton for shiny custom handlers.

golem::add_js_file("script")
golem::add_js_handler("script")
golem::add_css_file("custom")

12.6 Adding these external resources to your app

You can add any external resource (JS, css) into inst/app/www.

Then, You’ll need to point to these external resources in golem_add_external_resources(). For example, if you’ve created a CSS file with golem::add_css_file("custom"), you can add the file with:

tags$link(rel="stylesheet", type="text/css", href="www/custom.css")

Also, you can list here the use of other packages, for example useShinyalert() from the {shinyalert} package.

Note: we’ve chosen to leave it “raw”, in the sense that there is a addResourcePath and a tags$head. If you’re comfortable with {htmltools}, you can build a htmltools::htmlDependency.

12.7 Documentation

12.7.1 Vignette

usethis::use_vignette("shinyexample")
devtools::build_vignettes()

12.7.2 Code coverage

usethis::use_travis()
usethis::use_appveyor()
usethis::use_coverage()

12.8 Using {golem} dev functions

There’s a series of tools to make your app behave differently whether it’s in dev or prod mode. Notably, the app_prod() and app_dev() function tests for options( "golem.app.prod") (or return TRUE if this option doesn’t exist).

Setting this options at the beginning of your dev process allows to make your app behave in a specific way when you are in dev mode. For example, printing message to the console with cat_dev().

options( "golem.app.prod" = TRUE)
golem::cat_dev("hey\n")
options( "golem.app.prod" = FALSE)
golem::cat_dev("hey\n")
hey

You can then make any function being “dev-dependant” with the make_dev() function:

log_dev <- golem::make_dev(log)
log_dev(10)
[1] 2.302585
options( "golem.app.prod" = TRUE)
log_dev(10)

ThinkR Website