basic-ui.Rmd

# Basic UI

```{r, include = FALSE}
source("common.R")
```

## Introduction

Now that you've got a basic app under your belt, we're going to explore the details that make it tick. As you saw in the previous chapter, Shiny encourages separation of the code that generates your user interface (the front end) from the code that drives your app's behaviour (the backend). In this chapter, we'll dive deeper into the front end and explore the HTML inputs, outputs, and layouts provided by Shiny.

Learning more about frontend will allow you to generate visually compelling, but simple apps. In the next chapter, you'll learn more about the reactivity that powers Shiny's backend, allowing you to create richer responses to interaction.

As usual, we'll begin by loading the shiny package:

```{r setup}
library(shiny)
```

## Inputs {#inputs}

As we saw in the previous chapter, you use functions like `sliderInput()`, `selectInput()`, `textInput()`, and `numericInput()` to insert input controls into your UI specification. Now we'll discuss the common structure that underlies all input functions and give a quick overview of the inputs built into Shiny.

### Common structure

All input functions have the same first argument: `inputId`. This is the identifier used to connect the front end with the back end: if your UI has an input with ID `"name"`, the server function will access it with `input$name`.

The `inputId` has two constraints:

* It must be a simple string that contains only letters, numbers, and 
  underscores (no spaces, dashes, periods, or other special characters 
  allowed!). Name it like you would name a variable in R.
  
* It must be unique. If it's not unique, you'll have no way to refer to 
  this control in your server function!

Most input functions have a second parameter called `label`. This is used to create a human-readable label for the control. Shiny doesn't place any restrictions on this string, but you'll need to carefully think about it to make sure that your app is usable by humans! The third parameter is typically `value`, which, where possible, lets you set the default value. The remaining parameters are unique to the control. 

When creating an input, I recommend supplying the `inputId` and `label` arguments by position, and all other arguments by name:

```{r, results = FALSE}
sliderInput("min", "Limit (minimum)", value = 50, min = 0, max = 100)
```

The following sections describe the inputs built in to Shiny, loosely grouped according to the type of control they create. The goal is to give you a rapid overview of your options, not to exhaustively describe all the arguments. I'll show the most important parameters for each control below, but you'll need to read the documentation to get the full details.

### Free text

Collect small amounts of text with `textInput()`, passwords with `passwordInput()`[^password], and paragraphs of text with `textAreaInput()`.

[^password]: All `passwordInput()` does is hide what the user is typing, so that someone looking over their shoulder can't read it. It's up to you to make sure that any passwords are not accidentally exposed, so we don't recommend using passwords unless you have had some training in secure programming.

```{r}
ui <- fluidPage(
  textInput("name", "What's your name?"),
  passwordInput("password", "What's your password?"),
  textAreaInput("story", "Tell me about yourself", rows = 3)
)
```
```{r, echo = FALSE, out.width = NULL}
app <- testApp(ui)
app$setInputs(name = "Joe")
app$setInputs(password = "mypassword")
app_screenshot(app, "basic-ui/free-text")
```

If you want to ensure that the text has certain properties you can use `validate()`, which we'll come back to in Chapter \@ref(action-feedback). 

### Numeric inputs

To collect numeric values, create a slider with `sliderInput()` or a constrained textbox with `numericInput()`. If you supply a length-2 numeric vector for the default value of `sliderInput()`, you get a "range" slider with two ends.

```{r}
ui <- fluidPage(
  numericInput("num", "Number one", value = 0, min = 0, max = 100),
  sliderInput("num2", "Number two", value = 50, min = 0, max = 100),
  sliderInput("rng", "Range", value = c(10, 20), min = 0, max = 100)
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/numeric")
```

Generally, I recommend only using sliders for small ranges, or cases where the precise value is not so important. Attempting to precisely select a number on a small slider is an exercise in frustration! 

Sliders are extremely customisable and there are many ways to tweak their appearance. See `?sliderInput` and <https://shiny.rstudio.com/articles/sliders.html> for more details.

### Dates

Collect a single day with `dateInput()` or a range of two days with `dateRangeInput()`. These provide a convenient calendar picker, and additional arguments like `datesdisabled` and `daysofweekdisabled` allow you to restrict the set of valid inputs.

```{r}
ui <- fluidPage(
  dateInput("dob", "When were you born?"),
  dateRangeInput("holiday", "When do you want to go on vacation next?")
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/date")
```

Date format, language, and the day on which the week starts defaults to US standards. If you are creating an app with an international audience, set `format`, `language`, and `weekstart` so that the dates are natural to your users.

### Limited choices

There are two different approaches to allow the user to choose from a prespecified set of options: `selectInput()` and `radioButtons()`. 

```{r}
animals <- c("dog", "cat", "mouse", "bird", "other", "I hate animals")

ui <- fluidPage(
  selectInput("state", "What's your favourite state?", state.name),
  radioButtons("animal", "What's your favourite animal?", animals)
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/limited-choices")
```

Radio buttons have two nice features: they show all possible options, making them suitable for short lists, and via the `choiceNames`/`choiceValues` arguments, they can display options other than plain text.

```{r}
ui <- fluidPage(
  radioButtons("rb", "Choose one:",
    choiceNames = list(
      icon("angry"),
      icon("smile"),
      icon("sad-tear")
    ),
    choiceValues = list("angry", "happy", "sad")
  )
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/radio-icon")
```

Dropdowns created with `selectInput()` take up the same amount of space, regardless of the number of options, making them more suitable for longer options. You can also set `multiple = TRUE` to allow the user to select multiple elements.

```{r}
ui <- fluidPage(
  selectInput(
    "state", "What's your favourite state?", state.name,
    multiple = TRUE
  )
)
```
```{r, eval = FALSE, echo = FALSE, out.width = NULL}
# Doesn't work: https://github.com/rstudio/shinytest/issues/262
app <- testApp(ui)
app$setInputs(state = "Texas")
app$setInputs(`state-selectized` = "Cali")
app_screenshot(app, "basic-ui/limited-choices-multi")
```
```{r, echo = FALSE, out.width = NULL}
knitr::include_graphics("images/basic-ui/multi-select.png", dpi = 300)
```

There's no way to select multiple values with radio buttons, but there's an alternative that's conceptually similar: `checkboxGroupInput()`.

```{r}
ui <- fluidPage(
  checkboxGroupInput("animal", "What animals do you like?", animals)
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/multi-radio")
```

If you want a single checkbox for a single yes/no question, use `checkboxInput()`:

```{r}
ui <- fluidPage(
  checkboxInput("cleanup", "Clean up?", value = TRUE),
  checkboxInput("shutdown", "Shutdown?")
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/yes-no")
```

### File uploads

Allow the user to upload a file with `fileInput()`:

```{r}
ui <- fluidPage(
  fileInput("upload", NULL)
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/upload")
```

`fileInput()` requires special handling on the server side, and is discussed in detail in Chapter \@ref(action-transfer).

### Action buttons

Let the user perform an action with `actionButton()` or `actionLink()`. These are most naturally paired with `observeEvent()` or `eventReactive()` in the server function; I haven't discussed these functions yet, but we'll come back to them in the next chapter. 

```{r}
ui <- fluidPage(
  actionButton("click", "Click me!"),
  actionButton("drink", "Drink me!", icon = icon("cocktail"))
)
```
```{r, echo = FALSE, out.width = NULL}
ui_screenshot(ui, "basic-ui/action")
```

### Exercises

1.  When space is at a premium, it's useful to label text boxes using a 
    placeholder that appears _inside_ the text entry area. How do you call 
    `textInput()` to generate the UI below?
    
    ```{r, echo = FALSE, out.width = NULL}
    ui <- fluidPage(
      textInput("name", NULL, placeholder = "Your name")
    )
    ui_screenshot(ui, "basic-ui/placeholder")
    ```

1.  Carefully read the documentation for `sliderInput()` to figure out how to 
    create a date slider, as shown below.

    ```{r, echo = FALSE, out.width = NULL, message=FALSE}
    today <- Sys.Date()
    ui <- fluidPage(
      sliderInput("delivery", "When should we deliver?", today, min = today, max = today + 7, value = today + 1, step = 1, round = TRUE)
    )
    ui_screenshot(ui, "basic-ui/date-slider")
    ```

1.  If you have a moderately long list, it's useful to create sub-headings that
    break the list up into pieces. Read the documentation for `selectInput()` 
    to figure out how. (Hint: the underlying HTML is called `<optgroup>`.)

1.  Create a slider input to select values between 0 and 100 where the interval 
    between each selectable value on the slider is 5. Then, add animation to the 
    input widget so when the user presses play the input widget scrolls through 
    automatically.

1.  Using the following numeric input box the user can enter any value between 
    0 and 1000. What is the purpose of the step argument in this widget?

    ```{r eval=FALSE}
    numericInput("number", "Select a value", value = 150, min = 0, max = 1000, step = 50)
    ```

## Outputs {#outputs}

Outputs in the UI create placeholders that are later filled by the server function. Like inputs, outputs take a unique ID as their first argument: if your UI specification creates an output with ID `"plot"`, you'll access it in the server function with `output$plot`. 

Each `output` function on the front end is coupled with a `render` function in the back end. There are three main types of output, corresponding to the three things you usually include in a report: text, tables, and plots. The following sections show you the basics of the output functions on the front end, along with the corresponding `render` functions in the back end.

### Text

Output regular text with `textOutput()` and fixed code and console output with `verbatimTextOutput()`. 

```{r}
ui <- fluidPage(
  textOutput("text"),
  verbatimTextOutput("code")
)
server <- function(input, output, session) {
  output$text <- renderText({ 
    "Hello friend!" 
  })
  output$code <- renderPrint({ 
    summary(1:10) 
  })
}
```
```{r, echo = FALSE, out.width = NULL}
app_screenshot(testApp(ui, server), "basic-ui/output-text")
```

Note that the `{}` are not required in render functions, unless you need to run multiple lines of code. You could also write the server function more compactly. I think this is generally good style as you should do as little computation in your render functions as possible.

```{r}
server <- function(input, output, session) {
  output$text <- renderText("Hello friend!")
  output$code <- renderPrint(summary(1:10))
}
```

Note that there are two render functions that can be used with either of the text output functions:

* `renderText()` which displays text _returned_ by the code.
* `renderPrint()` which displays text _printed_ by the code.

To help understand the difference, examine the following function. It prints `a` and `b`, and returns `"c"`. A function can print multiple things, but can only return a single value.

```{r}
print_and_return <- function() {
  print("a")
  print("b")
  "c"
}
x <- print_and_return()
x 
```

### Tables

There are two options for displaying data frames in tables:

* `tableOutput()` and `renderTable()` render a static table of data, 
  showing all the data at once.
  
* `dataTableOutput()` and `renderDataTable()` render a dynamic table, showing
  a fixed number of rows along with controls to change which rows are visible.
  
`tableOutput()` is most useful for small, fixed summaries (e.g. model coefficients); `dataTableOutput()` is most appropriate if you want to expose a complete data frame to the user.
  
```{r}
ui <- fluidPage(
  tableOutput("static"),
  dataTableOutput("dynamic")
)
server <- function(input, output, session) {
  output$static <- renderTable(head(mtcars))
  output$dynamic <- renderDataTable(mtcars, options = list(pageLength = 5))
}
```
```{r, echo = FALSE, out.width = "100%"}
app_screenshot(testApp(ui, server), "basic-ui/output-table", width = 800)
```

### Plots

You can display any type of R graphic (base, ggplot2, or otherwise) with `plotOutput()` and `renderPlot()`:

```{r}
ui <- fluidPage(
  plotOutput("plot", width = "400px")
)
server <- function(input, output, session) {
  output$plot <- renderPlot(plot(1:5), res = 96)
}
```
```{r, echo = FALSE, out.width = NULL}
app_screenshot(testApp(ui, server), "basic-ui/output-plot")
```

By default, `plotOutput()` will take up the full width of its container (more on that shortly), and will be 400 pixels high. You can override these defaults with the `height` and `width` arguments. We recommend always setting `res = 96` as that will make your Shiny plots match what you see in RStudio as closely as possible.

Plots are special because they are outputs that can also act as inputs. `plotOutput()` has a number of arguments like `click`, `dblclick`, and `hover`. If you pass these a string, like `click = "plot_click"`, they'll create a reactive input (`input$plot_click`) that you can use to handle user interaction on the plot. We'll come back to interactive plots in Shiny in Chapter XYZ.

### Downloads

You can let the user download a file with `downloadButton()` or `downloadLink()`. These require new techniques in the server function, so we'll come back to that in Chapter \@ref(action-transfer).

### Exercises

1.  Re-create the Shiny app from the plots section, this time setting height to 
    300px and width to 700px.

1.  Add an additional plot to the right of the existing plot, and size it so
    that each plot takes up half the width of the app.

1.  Update the options for `renderDataTable()` below so that the table is 
    displayed, but nothing else, i.e. remove the search, ordering, and filtering
    commands. You'll need to read `?renderDataTable` and review the options 
    at <https://datatables.net/reference/option/>.

    ```{r eval=FALSE}
    ui <- fluidPage(
      dataTableOutput("table")
    )
    server <- function(input, output, session) {
      output$table <- renderDataTable(mtcars, options = list(pageLength = 5))
    }
    ```

## Layouts {#layout}

Now that you know how to create a full range of inputs and outputs, you need to be able to arrange them on the page. That's the job of the layout functions, which provide the high-level visual structure of an app. Here we'll focus on `fluidPage()`, which provides the layout style used by most apps. In future chapters you'll learn about other layout families like dashboards and dialog boxes.

### Overview

Layouts are created by a hierarchy of function calls, where the hierarchy in R matches the hierarchy in the output. When you see complex layout code like this:

```{r, eval = FALSE}
fluidPage(
  titlePanel("Hello Shiny!"),
  sidebarLayout(
    sidebarPanel(
      sliderInput("obs", "Observations:", min = 0, max = 1000, value = 500)
    ),
    mainPanel(
      plotOutput("distPlot")
    )
  )
)
```

First skim it by focusing on the hierarchy of the function calls:

```{r, eval = FALSE}
fluidPage(
  titlePanel(),
  sidebarLayout(
    sidebarPanel(
      sliderInput("obs")
    ),
    mainPanel(
      plotOutput("distPlot")
    )
  )
)
```

Even without knowing anything about the layout functions you can read the function names to guess what this app is going to look like. You might imagine that this code will generate a classic app design: a title bar at top, followed by a sidebar (containing a slider), with the main panel containing a plot.

### Page functions

The most important, but least interesting, layout function is `fluidPage()`. You've seen it in every example above, because we use it to put multiple inputs or outputs into a single app. What happens if you use `fluidPage()` by itself?

```{r, echo = FALSE}
knitr::include_graphics("images/basic-app/fluid-page.png", dpi = 300)
```

It looks very boring because there's no content, but behind the scenes, `fluidPage()` is doing a lot of work. The page function sets up all the HTML, CSS, and JS that Shiny needs. `fluidPage()` uses a layout system called **Bootstrap**, <https://getbootstrap.com>, that provides attractive defaults[^bs3]. Later on, in Chapter XYZ, we'll talk about how you can use a little knowledge of Bootstrap to gain greater control of the visual appearance of your app in order to make your app look more polished or match your corporate style guide.

[^bs3]: Currently Shiny uses Bootstrap 3.3.7, <https://getbootstrap.com/docs/3.3/>, but the Shiny team is planning to update to 4.0.0, the latest version, in the near future.

Technically, `fluidPage()` is all you need for an app, because you can put inputs and outputs directly inside of it. But while this is fine for learning the basics of Shiny, dumping all the inputs and outputs in one place doesn't look very good, so you need to learn more layout functions. Here I'll introduce you to two common structures, a page with sidebar and a multirow app, and then we'll finish off with a quick discussion of themes.

<!-- When to used fixedPage()? Probably most of the time, because it constrains the width. If you want you app to be full page, use fluidPage() -->

### Page with sidebar

`sidebarLayout()`, along with `titlePanel()`, `sidebarPanel()`, and `mainPanel()`,  makes it easy to create a two-column layout with inputs on the left and outputs on the right. The basic code is shown below; it generates the structure shown in Figure \@ref(fig:ui-sidebar).

```{r, eval = FALSE}
fluidPage(
  titlePanel(
    # app title/description
  ),
  sidebarLayout(
    sidebarPanel(
      # inputs
    ),
    mainPanel(
      # outputs
    )
  )
)
```

```{r ui-sidebar, echo = FALSE, out.width = NULL, fig.cap = "Structure of a basic app with sidebar"}
knitr::include_graphics("diagrams/basic-ui/sidebar.png", dpi = 300)
```

The following example shows how to use this layout to create a very simple app that demonstrates the Central Limit Theorem. If you run this app yourself, you can see how increasing the number of samples makes a distribution that looks very similar to a normal distribution.

```{r}
ui <- fluidPage(
  headerPanel("Central limit theorem"),
  sidebarLayout(
    sidebarPanel(
      numericInput("m", "Number of samples:", 2, min = 1, max = 100)
    ),
    mainPanel(
      plotOutput("hist")
    )
  )
)

server <- function(input, output, session) {
  output$hist <- renderPlot({
    means <- replicate(1e4, mean(runif(input$m)))
    hist(means, breaks = 20)
  }, res = 96)
}
```
```{r, echo = FALSE, out.width = "100%"}
app <- testApp(ui, server)
Sys.sleep(0.5)
app_screenshot(app, "basic-ui/sidebar", width = 800)
```

### Multi-row

Under the hood, `sidebarLayout()` is built on top of a flexible multi-row layout, which you can use directly to create more visually complex apps. As usual, you start with `fluidPage()`. Then you create rows with `fluidRow()`, and columns with `column()`. The following template generates the structure shown in Figure \@ref(fig:ui-multirow).

```{r, eval = FALSE}
fluidPage(
  fluidRow(
    column(4, 
      ...
    ),
    column(8, 
      ...
    )
  ),
  fluidRow(
    column(6, 
      ...
    ),
    column(6, 
      ...
    )
  )
)
```

```{r ui-multirow, echo = FALSE, out.width = NULL, fig.cap = "The structure underlying a simple multi-row app"}
knitr::include_graphics("diagrams/basic-ui/multirow.png", dpi = 300)
```

Note that the first argument to `column()` is the width, and the width of each row must add up to 12. This gives you substantial flexibility because you can easily create 2-, 3-, or 4-column layouts (more than that starts to get cramped), or use narrow columns to create spacers.

### Themes

In Chapter XYZ, we'll cover the full details of customising the visual appearance of your Shiny app. Creating a complete theme from scratch is a lot of work (but often worth it!), but you can get some easy wins by using the shinythemes package. The following code shows four options:

```{r, results = FALSE}
theme_demo <- function(theme) {
  fluidPage(
    theme = shinythemes::shinytheme(theme),
    sidebarLayout(
      sidebarPanel(
        textInput("txt", "Text input:", "text here"),
        sliderInput("slider", "Slider input:", 1, 100, 30)
      ),
      mainPanel(
        h1("Header 1"),
        h2("Header 2"),
        p("Some text")
      )
    )
  )
}
theme_demo("darkly")
theme_demo("flatly")
theme_demo("sandstone")
theme_demo("united")
```

```{r, echo = FALSE, out.width = "50%", fig.show="hold", fig.align='default'}
ui_screenshot(theme_demo("darkly"), "basic-ui/theme-darkly")
ui_screenshot(theme_demo("flatly"), "basic-ui/theme-flatly")
ui_screenshot(theme_demo("sandstone"), "basic-ui/theme-sandstone")
ui_screenshot(theme_demo("united"), "basic-ui/theme-united")
```

As you can see, theming your app is quite straightforward: you just need to use the `theme` argument to `fluidPage()`. To find out what themes are available, and what they look like, take a look at the Shiny theme selector app at <https://shiny.rstudio.com/gallery/shiny-theme-selector.html>.

### Exercises

1.  Modify the Central Limit Theorem app so that the sidebar is on the right 
    instead of the left.
    
1.  Browse the themes available in the shinythemes package, pick an attractive 
    theme, and apply it the Central Limit Theorem app.

<!--

Exercise ideas

1. A sample app where some commas are missing between layout elements
1. Write the code that generates the layouts in these drawings

-->

## Under the hood

In the previous example you might have been surprised to see that I create a Shiny app using a function, `theme_demo()`. This works because Shiny code **is** R code, and you can use all of your existing tools for reducing duplication. Remember the rule of three: if you copy and paste code more than three times, you should consider writing a function or using a for loop[^map].

[^map]: Or using `lapply()` or `purrr::map()` if you know a little about functional programming.

All input, output, and layout functions return HTML, the descriptive language that underpins every website. You can see that HTML by executing UI functions directly in the console:

```{r, eval = FALSE}
fluidPage(
  textInput("name", "What's your name?")
)
```
```html
<div class="container-fluid">
  <div class="form-group shiny-input-container">
    <label for="name">What's your name?</label>
    <input id="name" type="text" class="form-control" value=""/>
  </div>
</div>
```

Shiny is designed so that, as an R user, you don't need to learn about the details of HTML. However, if you already know HTML (or want to learn!) you can also work directly with HTML tags to achieve any level of customization you want. And these approaches are by no means exclusive: you can mix high-level functions with low-level HTML as much as you like. We'll come back to these ideas in Chapter \@ref(advanced-ui), where you'll learn more about the lower-level features for authoring HTML directly.