---
title: "shinydashboardPlus"
author: "David Granjon"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{shinydashboardPlus}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
library(bslib)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

`{shinydashboardPlus}` relies on the same basis as `{shinydashboard}`, that is the AdminLTE HTML [template](https://adminlte.io/themes/AdminLTE/index2.html). It provides extra elements that will help you to develop Shiny apps with a more professional look and feel. Below is a summary of the main features.

|  Features (sample)  |      shinydashboard      |  shinydashboardPlus |
|----------|:-------------:|------:|
| right sidebar (controlbar) |    ❌   |  ✅ |
| semi collapsible sidebar (sidebar mini) |    ❌   |  ✅ |
| expand on hover sidebar |    ❌   |  ✅ |
| closable boxes | ❌ |   ✅|
| box sidebar | ❌ |   ✅|
| get box state on the server (open, closed, ...) | ❌ |   ✅|
| control sidebars on the server | ❌ |   ✅|
| dashboard user dropdown |    ❌   |  ✅ |
| theme selector | ❌ |   ✅|
| social box | ❌ |   ✅|
| user box | ❌ |   ✅|
| control AdminLTE options | ❌ |   ✅|
| seamlessly customize appearance | ❌ |   ✅|
| beautiful preloaders | ❌ |   ✅|
| scroll to top button! | ❌ |   ✅|


Since the 2.0.0 release, `{shinydashboardPlus}` overwrites most of the `{shinydashboard}` functions such as `dashboardPage()` and `box()` to facilitate the transition from one package to another.

## What changes in v2.0.0 ?

### Breaking changes 
v2.0.0 is clearly a __major breaking change__ for `{shinydashboardPlus}`. It means that coming
from v0.7.5 (latest CRAN version to date), you will have to rewrite most of the code.
It was not an easy decision to take but necessary to improve the package quality (naming consistency, ...). Now the transition from `{shinydashboard}` to `{shinydashboardPlus}` will be easier since function parameters have been harmonized. The old `rightSidebar()` component becomes the `dashboardControlbar()` to ease the transition from `{shinydashboardPlus}` to `{bs4Dash}`, the latter being the Bootstrap 4 [version](https://github.com/RinteRface/bs4Dash) with a more modern look and feel. 

### More checks
Under the hood, functions are safer and more controls are done on the user inputs to reduce the risk of accidentally providing wrong values. 

### New features
The most exiting features of 2.0.0 are probably the ability to leverage the awesome `{fresh}` package (see [here](https://dreamrs.github.io/fresh/articles/vars-shinydashboard.html) for more details) through the `dashboardPage()` _freshTheme_ parameter. Additionally, the `skinSelector()` allows to dynamically change the dashboard skin on the client side. There are also more `update_` functions to programmatically control elements from the server. Now the `dashboardSidebar()` may be collapsed, so it the `dashboardControlbar()`. The `dashboardPage()` _options_ parameter is an easy way to fine tune the AdminLTE behavior (see [here](https://adminlte.io/themes/AdminLTE/documentation/index.html#adminlte-options) for the
list of available options). The `box()` component has been reworked to reduce the number of parameters and include new sub-components like the `boxSidebar()` that may be programmatically collapsed, or the `boxLabel()`. `box()` has an input binding indicating its current state on the server side, to perform specific tasks. Finally, colors are better documented thanks to Victor Perrier from dreamRs. For instance, the primary color is shown as <span style='width:12px;height:12px;background:#3c8dbc;border-radius:2px;display:inline-block;margin-right:5px;'></span>, danger is <span style='width:12px;height:12px;background:#dd4b39;border-radius:2px;display:inline-block;margin-right:5px;'></span>, which eventually helps users to choose between all available options.


## Basic Example
Below is a simple app you may build with `{shinydashboardPlus}`. We explicitly configured the sidebar to expand on hover, through the options parameters. Interestingly, you'll be able to notice the scroll to top button feature if you scroll to the bottom (bottom-right corner).

```{r, eval=TRUE, echo=FALSE}
card(
  shiny::tags$iframe(
    class = "html-fill-item", 
    src = "https://shinylive.io/r/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMAGwEsAjAJykYE8AKAZwAtaJWAlAB0IdJiw48+rACZQe9IixnDRDZmy69+chUsYyACtQCunVVP4BBdOxEACRydr2AvPd3dFyw1ADmcHYQjiGcBIxE1NQAKkSxqG720VgAqgCiuA4h9txwUDJwjIme3gYAEnkFjOwCmcHZnLQF9CzF8l76MgDKTXAt1TB8tABmtHAyicnpuPbEUWic45OpabVZIYoyrG16ygBCRFtB2Y7UaKjUHACMiABMAAwzigAeMwDuTaTciVe3M6S0UjUOCJIRgF5g1QnNb1ELEMgRaj9HYdZQAYRIpER-RqdROAKBIPcYIAIu1SkZ-HAwesYaFCgA3QqJYYmCAEAEkdh8VAmUgzIh83mkAT2ED2AC+DgEYAlAF0gA", 
    height = "800", 
    width = "100%", 
    style = "border: 1px solid rgba(0,0,0,0.175); border-radius: .375rem;", 
    allowfullscreen = "", 
    allow = "autoplay", 
    `data-external` = "1"
  ),
  full_screen = TRUE,
  style = "margin: 0 auto; float: none;"
)
```

<div class="text-center mt-4">
<a class="btn btn-primary" data-bs-toggle="collapse" href="#basic-demo" role="button" aria-expanded="false" aria-controls="tabLayout">
Code
</a>
</div>

<div class="collapse" id="basic-demo">
```{r, eval=FALSE}
library(shiny)
library(shinydashboard)
library(shinydashboardPlus)
shinyApp(
   ui = dashboardPage(
     options = list(sidebarExpandOnHover = TRUE),
     header = dashboardHeader(),
     sidebar = dashboardSidebar(minified = TRUE, collapsed = TRUE),
     body = dashboardBody(
      lapply(1:20, box, width = 12, title = "box")
     ),
     controlbar = dashboardControlbar(),
     title = "DashboardPage"
   ),
   server = function(input, output) { }
 )
```
</div>