---
title: "Main presentation title"
subtitle: "Subtitle if needed"
author: "Your name"
institute: "Bureau/Divisions"
date: "`r format(Sys.Date(),  '%d %B %Y')`"
output:
  unhcrdown::html_slides:
    self_contained: true
    nature:
      highlightStyle: github
      highlightLines: true
      countIncrementalSlides: false
      ratio: "16:9"
---

```{r setup, include=FALSE}
options(htmltools.dir.version = FALSE)
knitr::opts_chunk$set(
  warning = FALSE,
  message = FALSE,
  fig.showtext = TRUE
)
library(tidyverse)
library(unhcrthemes)
library(fontawesome)
```

# Template

**`html_slides`** is a simple online presentation template which is part of the [`unhcrdown`](https://github.com/unhcr-dataviz/unhcrdown) package.

Install the `unhcrdown` package from [Github](https://github.com/unhcr-dataviz/unhcrdown):

```{r eval=FALSE, tidy=FALSE}
# If pak is not yet installed, uncomment the following line:
# install.packages("pak")

pak::pkg_install("unhcr-dataviz/unhcrdown")
```

**Main resources:**

- [`unhcrdown::html_slides`](https://unhcr-dataviz.github.io/unhcrdown/articles/create_html_slides.html) vignette
- [`xaringan`](https://slides.yihui.org/xaringan/#1) slides
- [`remark.js`](https://remarkjs.com/#1) slides
- [R Markdown](https://rmarkdown.rstudio.com/lesson-1.html) documentation
- [`unhcrthemes`](https://unhcr-dataviz.github.io/unhcrthemes/) package
- [UNHCR Data Visualization Platform](https://dataviz.unhcr.org/)

---

# YAML

The default YAML arguments are below, but not all the YAML arguments are mandatory so change it accordingly.

```yaml
---
title: "Main presentation title"
subtitle: "Subtitle if needed"
author: "Your name"
institute: "Bureau/Divisions"
date: "`r format(Sys.Date(),  '%d %B %Y')`"
output:
  unhcrdown::html_slides:
    self_contained: true
    nature:
      highlightStyle: github
      highlightLines: true
      countIncrementalSlides: false
      ratio: "16:9"
---
```

All the arguments, coming after the `unhcrdown::html_slides` call, are part of the **xaringan** package.<br>See the help page `?xaringan::moon_reader` for all possible configurations.

---
name: shortcut

# Navigate

Press **h** or **?** to see the [`remark.js` keyboard shortcuts](https://bookdown.org/yihui/rmarkdown/xaringan-key.html), to help you navigate your presentation.

If you have two screens, a common workflow is to:

- Press **c** to clone your presentation

- **On the presentation screen:** Move cloned window here, then press **f** for full-screen mode

- **On the extra screen:** Press **p** for presenter mode. See below to learn how to add presenter notes

---
name: basic-slide

# Basic slides

.pull-left[
- Slide content starts immediately after the YAML ends

- Use 3 dashes in a row `---` on a line by itself to create a new slide

- Use 2 dashes in a row `--` for incremental content

- [Presenter notes can be created using `???`](#shortcut)
]

.pull-right[
```{r, eval=FALSE}
---
title: "Main presentation title"
output:unhcrdown::html_slides
---

# Slide one

Lorem ispum...

???
Notes on slide 1

---

# Slide Two

Lorem ispum...
```
]

???
Only you will see this when in presenter mode.

---

# Incremental reveal

As mentioned in [Basic slides](#basic-slide) use 2 dashes in a row `--` for incremental content.

--

- Bullet 1

--

- Bullet 2

--

- Bullet 3

---

# Alignement

You can use the following classes to align content within a slide:

- **Horizontal alignment:** `left`, `center`, `right`
- **Vertical alignment:** `top`, `middle`, `bottom`

```{r, eval=FALSE}
---
class: center, middle
```

Or you can align specific text, **horizontal only**

- for example, `.right[this text will be on the right]`

.right[this text will be on the right]

---

# Top-Left

No class added as default behavior

---
class: center

# Top-center

Apply to whole slide content

---
class: center, right

# Top-right

Apply to whole slide content

---
class: middle

# Middle-left

Apply to whole slide content

---
class: middle, center

# Middle-center

Apply to whole slide content

---
class: middle, right

# Middle-right

Apply to whole slide content

---
class: bottom

# Bottom-left

Apply to whole slide content

---
class: bottom, center

# Bottom-center

Apply to whole slide content

---
class: bottom, right

# Bottom-right

Apply to whole slide content

---

# Layout

You can move content to the left or right using the following classes `.pull-left[]` and `.pull-right[]`.

This will create a two-column layout, where each column takes up to **47% of the page width**.

All the column content needs to go within the respective `[]`.

.pull-left[
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
]

.pull-right[
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
]

You can even go back to the **entire width** if you need the two columns only for a certain portion of the slide.

---

# Columns within columns

The layout classes are really helpful and can **create complex layout** by nesting them.

.pull-left[
.pull-left[
### Col 1.1
This is a `.pull-left[]` within a `.pull-left[]`
]
.pull-right[
### Col 1.2
This is a `.pull-right[]` within a `.pull-left[]`
]
]

.pull-right[
.pull-left[
### Col 2.1
This is a `.pull-left[]` within a `.pull-right[]`
]
.pull-right[
### Col 2.2
This is a `.pull-right[]` within a `.pull-right[]`
]
]

---

# More layout

.left-column[
I am a narrow column that leaves a lot of space for my bigger `.right-column[]` friend.

I come with a lighter font colour. 
]

.right-column[
You can similarly use `.left-column[]` and `.right-column[]`, the sizes are then 20% and 75%.

I am a really wide column and I keep my font colour.

This layout is useful to draw attention to the **main content** on the right side and keeping the left side as an **aside**.

It is a specific layout and should be only use sporadically, e.g. showing a big picture on the right side.

Unlike `.pull-left[]` and `.pull-right[]` these columns are meant to be used for the entire slide. You avoid avoid adding content outside the respective `[]`.
]

---

# Basic style

The template comes with predefined styles for inline text, such as *italic*, **bold** or <u>underline text</u>.

It also includes the required styles for common elements such as:

.pull-left[
**Headers:**

## Heading 2

### Heading 3

**Lists:**

* item 1
* item 2
    1. sub-item 2.1
    2. sub-item 2.2
]

.pull-right[

**Quotes:**

> It is further proof that refugee movements and the broader issue of migration of populations ... is a global challenge that cannot be confined to a few countries.
>
> Filippo Grandi

**Footnotes:**

Footnotes are created using the `.footnote[]` class outside of the column. 

]

.footnote[
This is a footnote can be tied to a number in the main text using the `<sup>` html tag
]

---

# More style

.pull-left[
You can change the **size** of the text by using the `.large[]` or `.small[]` class

.large[Large text] followed by .small[small text] example

You can change the **colour** of the text by using the `.blue[]` or `.grey[]` class

.blue[Blue text] followed by .grey[grey text] example

You can change the **background** of the text by using the `.bg-blue[]` or `.bg-grey[]` class

Some of this text will be in a .bg-blue[blue background]

Some of this text will be in a .bg-grey[grey background]
]

--

.pull-right[
You can also create a call out box by wrapping the entire content with the background class.

```{r, eval=FALSE}
.bg-blue[
I will become a text box with background!
]
```

.bg-blue[

I will become a text box with background!

]
]

---

# Images

.pull-left[
Depending on your need and control over the image output you can use the following approaches to include images in your slides:

- Inline R Markdown: `![alt-text](path_to_image)`
- [Knitr](https://www.rdocumentation.org/packages/knitr/versions/1.30/topics/include_graphics): `knitr::include_graphics("path_to_image")`
- Plain [HTML](https://www.w3schools.com/html/html_images.asp): `<img src="path_to_image" width="90%"/>`

Inline R Markdown scale depends on the image size. To control the size use `knitr` or `html`:

```{r, out.width = '50%', eval=FALSE}
# set out.width="50%" code chunk parameter
# don't forget echo=FALSE to see only the image
knitr::include_graphics("path_to_image")
```
]

.pull-right[
.center[
```{r, echo=FALSE, out.width = '60%'}
knitr::include_graphics("https://raw.githubusercontent.com/vidonne/unhcrdown/master/inst/resources/img/cover-example.jpg")
```
]
]

---

# Icons

The brand unit recommends using the [Humanitarian icons](https://brand.unocha.org/d/xEPytAUjC3sH/icons) which are now part of the [Fontawesome](https://fontawesome.com/icons/categories/humanitarian) set.

To directly access Fontawesome in R, simply install and load the [`fontawesome`](https://rstudio.github.io/fontawesome/) R package.

.pull-left[
```{r, eval=FALSE}
# install.packages('fontawesome')
library(fontawesome)

.blue[`r fa("hands-holding-circle")`]
```
]

.pull-right[
.large[.blue[`r fa("hands-holding-circle")`] **Protection**]

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
]

---

# Background colour

- The default slide background is white but you can apply a branded UNHCR blue by adding the class `inverse` to the slide.

- The font colours will adapt automatically.

- This can be useful to create a section break in your presentation.

- The `inverse` class can be coupled with the alignment classes.

**Code for next slide:**

```{r, eval=FALSE}
---
class: inverse, center, middle

# My new section

### Be descriptive
```

---
class: inverse, center, middle

# My new section

### Be descriptive

---

# Background images

You can specify a background image (or multiple images) at the start of your slide, just like you set the class for the background colour:

--

- `background-image: url(path_to_image)`

--

- `background-size`:
  - `cover`: Scales the image (while preserving its ratio) to the smallest possible size to fill the container.
  - `contain`: Scales the image as large as possible within its container without cropping or stretching the image.
  
--

- `background-position`: [see here](https://www.w3schools.com/cssref/pr_background-position.asp) for different options.

--

- Play with the `inverse` class of the slide depending on the logo colour that works better with your picture.

--

- You can remove the logo altogether by putting the `hide-logo` class.

---
class: hide-logo
background-image: url(https://raw.githubusercontent.com/vidonne/unhcrdown/master/inst/resources/img/cover-example.jpg)
background-size: cover
background-position: center 25%

---
class: inverse, center, middle

# R content

### Code, tables and plots

---

# Highlighting code

.pull-left[
To highlight lines of code simply add `#<<` at the end of each targeted row and a light yellow background will be added.
]

.pull-right[
```{r, eval = FALSE}
library(tidyverse)
mtcars_select <- mtcars |> 
  select(hp, mpg, cyl) #<<
glimpse(mtcars_select)
```
]

--

.pull-left[
It is also possible to highlight the code output by adding `highlight.output = c(3,4)` to the code chunk options.
]

.pull-right[
```{r, echo = FALSE, highlight.output = c(3, 5)}
library(tidyverse)
mtcars_select <- mtcars |> 
  select(hp, mpg, cyl) #<<
glimpse(mtcars_select)
```
]

---

# Tables

.pull-left[
- We recommend the use of `kable` from the **knitr** package.

- Make sure to add the format HTML to your `kable` call: `knitr::kable(format = "html")`..small[<sup>1</sup>] 

- See [here](https://bookdown.org/yihui/rmarkdown-cookbook/kable.html) more information on `kable` and what it can do, like formatting numbers , changing column, etc.

- For more flexibility and advanced table style refer to other R packages like [`GT`](https://gt.rstudio.com/) or [`DT`](https://rstudio.github.io/DT/).
]

.pull-right[
```{r, echo = FALSE}
head(mtcars_select) |> 
  knitr::kable(format = "html",
               col.names = c("Fuel efficiency", "Horsepower", "Num. of cylinder"),
               caption = "Subset of mtcars dataset")
```
]

.footnote[
<sup>1</sup>You can also set this as a global option for all your slides using `options(knitr.table.format = "html")`.
]

---

# UNHCR table classes

For simple tables, we included a series of **classes** that can be applied to `kable` output format. Simply add the required class names to the `table.attr` parameter of the `kable` call, don't forget to use `\` to escape the quote character.


.pull-left[
The following classes are available:

- `.table`: initiate the possibility to stylize the table and provide base style. This class is **mandatory**.

- `.table-blue`: add blue background for alternate rows.

- `.table-grey`: add grey background for alternate rows.

- `.table-narrow`: fit the table width to the content.

- `.table-noborder`: remove all borders from the table.
]

.pull-right[
```{r, echo = FALSE}
head(mtcars_select) |> 
  knitr::kable(format = "html",
               col.names = c("Fuel efficiency", "Horsepower", "Num. of cylinder"),
               caption = "Subset of mtcars dataset",
               table.attr = "class=\"table  table-blue table-noborder\"")
```
]

---

# Plots

For the creation of charts, we recommend using the [**`unhcrthemes`**](https://unhcr-dataviz.github.io/unhcrthemes/) as it provides a `ggplot2` theme and a set of colour palettes for making charts and graphics.

.pull-left[
For more information on how to make a plot using `unhcrthemes` please refer to [package documentation](https://unhcr-dataviz.github.io/unhcrthemes/articles/unhcrthemes.html) and the [UNHCR Data Visualization Platform R tutorials](https://dataviz.unhcr.org/tools/r/).

Getting your plot right is not always easy, but you can control your plots by playing with individual chunk options like `fig.retina` and `out.width` (plus `fig.width` and `fig.height`). 
]

.pull-right[
```{r, echo=FALSE, dev = "ragg_png", fig.retina = 4, out.width="100%", fig.height=5}
ggplot(
  mtcars,
  aes(x = hp, y = mpg, color = as.factor(cyl))
) +
  geom_point(alpha = .8) +
  labs(
    title = "Simple scatterplot with ggplot",
    subtitle = "This plot shows the default style of theme_unhcr()",
    x = "Horsepower (hp)",
    y = "Fuel efficiency (mpg)",
    color = "Number of cylinder",
    caption = "Source: mtcars"
  ) +
  scale_color_unhcr_d() +
  theme_unhcr(legend_title = TRUE)
```
]

---

# Code and plot

**Show code alongside resulting plot**, practical for teaching purpose.

Use the `fig.show` and the `ref.label` code chunk options to avoid repeating your code.

* Chunk showing code: `{r plot-name, fig.show = 'hide'}`

* Chunk showing plot: `{r ref.label = 'plot-name', echo = FALSE}`

The chunk showing the plot will **NOT repeat** the code but rather reference the code chunk by name.

---

# Code and plot example

.pull-left[
#### Code:

```{r, mtcars-ex,  fig.show='hide'}
ggplot(
  mtcars,
  aes(x = hp, y = mpg, color = as.factor(cyl))
) +
  geom_point(alpha = .8) +
  labs(
    title = "Simple scatterplot with ggplot",
    subtitle = "This plot shows the default style of theme_unhcr()",
    x = "Horsepower (hp)",
    y = "Fuel efficiency (mpg)",
    color = "Number of cylinder",
    caption = "Source: mtcars"
  ) +
  scale_color_unhcr_d() +
  theme_unhcr(legend_title = TRUE)
```
]

.pull-right[
#### Plot:

```{r, ref.label="mtcars-ex", echo=FALSE, dev = "ragg_png", fig.retina = 4, out.width="100%", fig.height=5}

```
]

---

# Scrolling R output

.pull-left[
We recommend making sure your content fits the height of the slide, but sometimes output from R can be too big.

For this scenario, we include custom classes, to wrap the targeted content in the desired class:

* `.scroll-box-8[]`: show 8 lines
* `.scroll-box-10[]`: show 10 lines
* `.scroll-box-12[]`: show 12 lines
* `.scroll-box-14[]`: show 14 lines
* `.scroll-box-16[]`: show 16 lines
* `.scroll-box-18[]`: show 18 lines
* `.scroll-box-20[]`: show 20 lines


]

.pull-right[
**`.scroll-box-12[]` example:**

.scroll-box-12[
```{r, eval=FALSE}
library(tidyverse)
library(unhcrthemes)

ggplot(
  mtcars,
  aes(x = hp, y = mpg, color = as.factor(cyl))
) +
  geom_point(alpha = .8) +
  labs(
    title = "Simple scatterplot with ggplot",
    subtitle = "This plot shows the default style of theme_unhcr()",
    x = "Horsepower (hp)",
    y = "Fuel efficiency (mpg)",
    color = "Number of cylinder",
    caption = "Source: mtcars"
  ) +
  scale_color_unhcr_d() +
  theme_unhcr(legend_title = TRUE)
```
]
]

.footnote[
Thanks to [Garth Tarr from the University of Sydney](https://garthtarr.github.io/sydney_xaringan/#13) for the idea.
]

---
class: inverse, center, middle

# Thank you