---
title: "Introduction to shinyglide"
author: "Julien Barnier"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to shinyglide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


`shinyglide` allows to add carousel-like components to shiny applications thanks to the [Glide](https://www.glidejs.com) Javascript library.


## Creating a glide

To add a *glide* component to an app, you must call the `glide()` function in you application UI declaration :

```{r eval = FALSE}
ui <- fluidPage(
  titlePanel("App title"),
  glide(
    ...
  )
)
```

## Adding screens

Once your glide is created, you have to add *screens* to it. This is done by calling the `screen()` function :


```{r eval = FALSE}
ui <- fluidPage(
  titlePanel("App title"),
  glide(
    screen(
      p("This is the first screen of this glide.")
    ),
    screen(
      p("This is the second and final screen.")
    )
  )
)
```

Of course, *screens* can contain anything you want, including shiny inputs and outputs. Here is a very basic complete app :

```{r eval = FALSE}
ui <- fluidPage(
  titlePanel("Basic shinyglide app"),
  glide(
    screen(
      p("Please choose a value for n :"),
      numericInput("n", "n :", value = 100)
    ),
    screen(
      p("Here is your plot :"),
      plotOutput("plot")
    )
  )
)

server <- function(input, output, session) {
  output$plot <- renderPlot({
    hist(rnorm(input$n), main = paste("n =", input$n))
  })
}

shinyApp(ui, server)
```

You can see that default controls are added to your glide in the form of a "next" button (which doesn't appear on last screen) and a "back" button (which doesn't appear on the first one). There are different ways to customize these controls, which are explained in the [custom controls](https://juba.github.io/shinyglide/articles/c_custom_controls.html) vignette.


## Customizing glide

The `glide()` function accepts several arguments to modify its behavior or appearance :

- `id` : allows to ass an HTML `id` to the glide root
- `height` : height of the glide in any CSS unit
- `keyboard` : set to `FALSE` to disable keyboard arrows navigation 
- `controls_position` : wether to place the controls on `"top"` or `"bottom"` of the glide.
- `next_label`, `previous_label` : allow to specify custom labels for the "Back" and "Next" buttons. You can use text, HTML, `icon()`, etc.

The `loading_label`, `label_class` and `disable_type` options will be described in the [conditional controls and screen output](https://juba.github.io/shinyglide/articles/b_conditionals.html) vignette, and the `custom_controls` argument is explained in the [custom controls](https://juba.github.io/shinyglide/articles/c_custom_controls.html) vignette.

Here is an example of glide customization :

```{r eval = FALSE}
ui <- fluidPage(
  glide(
    id = "plot-glide",
    height = "450px",
    controls_position = "top",
    next_label = "Go to next screen",
    previous_label = "Go back",
    
    screen(
      p("Please choose a value for n :"),
      numericInput("n", "n :", value = 100)
    ),
    screen(
      p("Here is your plot :"),
      plotOutput("plot")
    )
  )
)

server <- function(input, output, session) {
  output$plot <- renderPlot({
    hist(rnorm(input$n), main = paste("n =", input$n))
  })
}

shinyApp(ui, server)
```


## Customizing screens

You can also use arguments with `screen()` :

- `class` : allows to add a CSS class to the current screen
- `next_label`, `previous_label` : change the "back" and "next" controls labels for this screen

The `next_condition` and `previous_condition` arguments are explained in the [conditional inputs and screen outputs](https://juba.github.io/shinyglide/articles/b_conditionals.html)
 vignette.
 

## In app controls

It's possible to add controls inside the content of screens, such as a button which send the user back to the first screen, a link to go two screens forward, etc.

To do this, you have to create an element (usually a link or a button) with a `data-glide-dir` attribute, and wrap it inside an element (usually a `<div>`) with a ` `data-glide-el="controls"` attribute. 

For example, the following will create a link which will go back one screen :

```{r eval=FALSE}
div(`data-glide-el`="controls",
  a(`data-glide-dir`="<", href="#", "Go back")
)
```

And this will create a button that will go back to the first screen :

```{r eval=FALSE}
div(`data-glide-el`="controls",
  tags$button(`data-glide-dir`="<<", href="#", "Back to start")
)
```

The `data-glide-dir` attribute accepts the following values :

- `<`, `>` : move one screen backward/forward
- `<<`, `>>` : go to the first/last screen
- `=n` : go to the screen at index *n* (starting at 0)


## Getting back the current slide index into Shiny

`shinyglide` automatically updates a Shiny input with the current slide index. If you gave an `id` to your `glide()` element, you can access it with `input$shinyglide_index_id`, otherwise the variable name is `input$shinyglide_index`. Here is a quick example :

```{r eval=FALSE}
ui <- fluidPage(
  glide(
    id = "myglide",
    screen(h1("First screen")),
    screen(h1("Second screen")),
    screen(h1("Third screen"))
  ),
  textOutput("index")
)

server <- function(input, output, session){
  output$index <- renderText(
    input$shinyglide_index_myglide
  )
}
```

Note that this won't work if you put an hyphen in your glide `id`.