slides_rr2021_pagedown.Rmd

---
title: "Pagedown - utilisations possibles et création de thèmes"
subtitle: "Rencontres R 2021"
author: "Thomas Vroylandt"
date: "13 juillet 2021"
output:
  tourmentin::slides_simple
---

```{r setup, include=FALSE}
options(htmltools.dir.version = FALSE)

knitr::opts_chunk$set(echo = FALSE)
```

## Qui suis-je ?

+ Statisticien (à [l'Unédic](https://www.unedic.org/) actuellement)
+ Avec une [activité de conseil en plus](https://www.tillac-data.com/)
+ Développeur du package {`pagedreport`} : [documentation](https://pagedreport.rfortherestofus.com/)

+ Cette présentation est issue des travaux que j'ai pu mener

```{r, out.height='300px', fig.align='default', fig.show = "hold"}
knitr::include_graphics(
  c(
    "https://raw.githubusercontent.com/tvroylandt/sgdf_pagedown/master/img/page1.PNG",
    "https://p218.p3.n0.cdn.getcloudapp.com/items/4gumRNLp/Image%202020-03-22%20at%202.24.38%20PM.png",
    "https://mk0rfortheresto0o08q.kinstacdn.com/wp-content/uploads/2021/01/grid.gif"
  ),
  dpi = 300
)
```

---
class: inverse, center, middle

# {pagedown} ???

---
## Un problème ...

`r icon::fontawesome(style = "solid", "arrow-alt-circle-right")` On souhaite souvent générer des PDF directement depuis R car :

  + assure la reproductibilité
  
  + permet de ne pas changer d'outil
  
  + autorise des approches paramétrisées
  
  + c'est un format portable
  
  + très utilisé pour les rapports ou les documents d'entreprise
  
---
## Un problème ...

`r icon::fontawesome(style = "solid", "bomb")`  Sauf que :
  
  + les sorties LaTeX sont peu attrayantes
  
```{r, out.height='250px', fig.align = 'center'}
knitr::include_graphics("https://i.stack.imgur.com/Nug7W.png", dpi = 100)
```

  + elles demandent des compétences pointues de personnalisation
  + le multi-support (web + PDF est difficile à gérer)

---
## ... une solution

Il est possible d'imprimer des pages Web spécialement mises en forme grâce au projet [paged.js](https://www.pagedjs.org/).

`r icon::fontawesome(style = "solid", "lightbulb")` Transcrit pour être utilisé en R dans [pagedown](https://github.com/rstudio/pagedown) par Romain Lesur et Yihui Xie

`r icon::fontawesome(style = "solid", "arrow-alt-circle-right")` Les avantages :

  + Utilisation des outils du design Web (HTML / CSS / JS)
  + Qualité des rendus
  + Collaboration possible avec des spécialistes de ces technologies
  
`r icon::fontawesome(style = "solid", "exclamation")` Nécessite de comprendre au moins les bases du CSS et d'HTML

---
## Fondations

`r icon::fontawesome(style = "solid", "check")` Il existe un projet de spécifications officielles pour créer des documents paginés en CSS. Ce sont celles du [W3C](https://www.w3.org/TR/css-page-3/).

`r icon::fontawesome(style = "solid", "exclamation")` Sauf qu'elle ne sont pas encore implementées correctement dans les navigateurs.

`r icon::fontawesome(style = "solid", "key")` Le projet paged.js est une programme qui :

  + utilise les règles présentes dans un fichier CSS
  + pour construire un document paginé
  + c'est une sorte de "ciseaux" + "collage" à l'échelle d'une page Web
  
  
`r icon::fontawesome(style = "solid", "book")` La [documentation](https://www.pagedjs.org/documentation/) est extrêmement riche

---
## Comment ça fonctionne ?

{`pagedown`} implémente principalement :

+ Des formats RMarkdown, dont `html_paged` qui va appeler paged.js et des fonctions pour "découper" (*Fragmentation CSS*) et reconstruire le contenu en pages.

+ Des fichiers CSS standards liés aux formats `r icon::fontawesome(style = "solid", "arrow-alt-circle-right")` **nos modifications passent principalement par là**

+ Et une fonction pour permettre l'impression en PDF : `chrome_print` (utilise l'impression de Chrome ou de Edge).

`r icon::fontawesome(style = "solid", "video")` [Présentation à la RStudio Conf 2019](https://www.rstudio.com/resources/rstudioconf-2019/pagedown-creating-beautiful-pdfs-with-r-markdown-and-css/).

---
## {`pagedreport`}

+ `r icon::fontawesome(style = "solid", "code-branch")` [Github](https://github.com/rfortherestofus/pagedreport)
+ `r icon::fontawesome(style = "solid", "book")` [Documentation](https://pagedreport.rfortherestofus.com/)
+ `r icon::fontawesome(style = "solid", "blog")` [Article de blog](https://rfortherestofus.com/2021/01/announcing-pagedreport/)

`r icon::fontawesome(style = "solid", "question")` Projet en collaboration avec David Keyes de [R for the Rest of Us](https://rfortherestofus.com/).

`r icon::fontawesome(style = "solid", "lightbulb")` Le principe :

  + construire des templates déjà designés ;
  + qui sont personnalisables.
  
`r icon::fontawesome(style = "solid", "bullseye")` L'objectif : 

  + construire des produits viables et utlisables rapidement ;
  + itérer ensuite pour construire du sur-mesure.

---
  
## {`pagedreport`}

`r icon::fontawesome(style = "solid", "lightbulb")` Tout se personnalise directement dans le YAML :

```{yaml, echo = TRUE, eval= FALSE}
---
title: "Annual North"
subtitle: "Christmas activity report"
author: "Santa Claus"
date: "December 2020"
output:
  pagedreport::paged_hazelnuts:
    front_img: "https://images.pexels.com/photos/717988/pexels-photo-717988.jpeg?auto=compress&cs=tinysrgb&h=750&w=1260"
    back_img: "https://images.pexels.com/photos/3303615/pexels-photo-3303615.jpeg?auto=compress&cs=tinysrgb&dpr=1&w=500"
    logo: "https://www.flaticon.com/svg/static/icons/svg/268/268225.svg"
    img_to_dark: TRUE
    logo_to_white: TRUE
knit: pagedown::chrome_print
toc-title: "Table of Contents"
main-color: "#E40A2D"
secondary-color: "#00873E"
google-font: TRUE
main-font: "Raleway"
header-font: "Mountains of Christmas"
---
```

---
## {`pagedreport`}

```{r, out.height='450px', fig.align='center'}
knitr::include_graphics("https://user-images.githubusercontent.com/28248895/102329258-7a023800-3f88-11eb-8f4c-2f6c0cb9b562.png", dpi = 200)
```

---
## `r icon::fontawesome(style = "solid", "file")` Faire votre CV

Proposition la plus aboutie : `pagedown-cv` : le CV est une base de données (fichier Excel) et est généré ensuite.

```{r, out.height='300px', fig.align='default', fig.show = "hold"}
knitr::include_graphics(
  c(
    "https://ulyngs.github.io/pagedown-cv/examples/cur_cv_pg1.jpg",
    "https://ulyngs.github.io/pagedown-cv/examples/cur_cv_pg2.jpg"
  ),
  dpi = 200
)
```

`r icon::fontawesome(style = "solid", "book")` [Documentation](https://ulyngs.github.io/pagedown-cv/)

Un exemple : [mon CV](https://tvroylandt.netlify.app/pdf/cv_vroylandt.pdf)

---
class: inverse, center, middle

# Et si je veux construire mon propre thème ?

---
## Appliquer le reste du CSS

`r icon::fontawesome(style = "solid", "check")` On commence par construire les éléments classiques en CSS sur les différentes classes :

+ Les polices

```
p {
  font-family: "Roboto";
}

h1, h2, h3 {
  font-family: "Lato";
}
```

+ Les couleurs

```
ul, li {
  color: #741336;
}
```

---
## Appliquer le reste du CSS

+ Les tailles et styles

```
blockquote {
  font-size: 12pt;
  text-transform : uppercase;
}
```

+ Les bordures

```
h3 {
  border-bottom: solid black 1px;
}
```

+ Aux espacements (`line-height`) et marges (`margin` et `padding`) -> `r icon::fontawesome(style = "solid", "bomb")` attention aux interactions avec la suite !

+ Et ainsi de suite...

---
## Appliquer le reste du CSS

Il faut principalement penser :

+ Aux titres, de `h1` à `h3`, voire plus si besoin

+ Y compris les éléments de la première page : `h1.title`, `h1.subtitle`, `h2.date`, `h2.author`, sauf en ce qui concerne leur positionnement

+ Aux paragraphes et listes : `p`, `li`, `ul`

+ Aux liens : `a`

+ Aux blocs : `blockquote`

+ Aux tableaux éventuellement  `tr`, `td`

`r icon::fontawesome(style = "solid", "book")` [Documentation Mozilla](https://developer.mozilla.org/fr/docs/Web/CSS)

`r icon::fontawesome(style = "solid", "lightbulb")` Ce CSS peut être commun avec d'autres formats RMarkdown.

---
## La page

`r icon::fontawesome(style = "solid", "check")` **La page est l'élément central du package** :

+ Au travers de l'argument `@page`

+ On fixe ses dimensions au début par 

```
@page {
 size: 210mm 297mm;
}
```

+ Certaines pages ont des caractéristiques particulières :

  + `first` et `last`
  + `blank`
  + `left` et `right`
  + les [pages nommées](https://www.pagedjs.org/documentation/08-named-pages/)
  
```
.chapter {
    page: chapter;
}
```
---
## Tirer profit des contraintes de dimensions

 `r icon::fontawesome(style = "solid", "wifi")` Dans le monde du Web, tout est relatif :
 
 + les tailles des images 
 
 + les positions des éléments
 
 + tout dépend de la taille de l'écran de l'utilisateur

`r icon::fontawesome(style = "solid", "lightbulb")` Ici, la dimension aide :

+ les tailles des images sont fixes (ajouter un `img {max-width : 100%;}`)

+ on peut utiliser le `position: absolute;` de façon récurrente pour placer les objets (sans que ce soit obligatoire)

+ mais on peut avoir quelques problèmes sur les tableaux, avec des [solu](https://github.com/rstudio/pagedown/issues/162)-[tions](https://gitlab.pagedmedia.org/tools/pagedjs/issues/85)

---
## Page de garde et dernière page

Un exemple de première page :

```{r, fig.height=4, fig.align='center'}
knitr::include_graphics("img/page_first_proust.png", dpi = 200)
```

---
## Page de garde et dernière page

```
@page:first{
  margin: 0 0 0 0;
  background-image: url(../style/Marcel_Proust_signature.svg), 
                    var(--front-cover);
  background-repeat: no-repeat, no-repeat;
  background-size: 30%, 70%;
  background-position: 100px 900px, 200px 500px;
  background-color :  #ffeecb;
}
```

Et 

```
h1, h2, h3 {
	color: var(--main-color);
	font-weight: 900;
}

.title, .subtitle, .author, .date{
	color : black;
	margin-left: 1cm;
	margin-right: 3cm;
}
```

---
## Page de garde et dernière page

`r icon::fontawesome(style = "solid", "images")` On peut paramétriser les images depuis le YAML :

Dans le YAML :

```
output: 
  pagedown::html_paged:
    front_cover: style/mountain.png
    back_cover: style/proust.png
```

Dans le CSS :

`var(--front-cover)`
`var(--back-cover)`

Et on peut en mettre [plusieurs - page 42](https://pagedown.rbind.io/).

---
## Contenus dans les marges

On peut placer du contenu dans les marges

```{r, out.height='300px', fig.align='center'}
knitr::include_graphics("https://www.pagedjs.org/documentation/images/margin-boxes.png", dpi = 200)
```

---
## Contenus dans les marges

Exemple de ma page de garde

```
@page:first{
  @top-left {
    content: none;
  }
  @top-right {
    content: none;
  }
	@left-top {
		content: "";
		background-color: var(--main-color);
	}
	@left-middle {
		content: "";
	  	background-color: var(--color-paper);
	}
	@left-bottom {
		content: "";
	  	background-color: var(--color-paper);
	}
}
```
---
## Contenus dans les marges

Ou pour créer une pagination alternée par exemple

```
@page:left {
    @bottom-left {
      content: counter(page);
    }
```

```
@page:right {
    @bottom-right {
      content: counter(page);
    }
```

Ou pour mettre une image depuis une variable CSS 

```
@page chapter: {
    @top-right {
            content: string(title);
            background-image: var(--state-shape);
        }
```
---
## Sauts de pages

`r icon::fontawesome(style = "solid", "file")` Pour sauter une page :

+ la fin d'une page nommée termine la page ;

+ on peut utiliser les fonctions CSS :

  + `page-break-after: always;` ou `avoid`
  + `page-break-inside`
  + avec des comportements parfois étranges

---
## Autres fonctionnalités

D'autres fonctionnalités non évoquées existent ou sont en cours d'implémentation :

+ table des matières ;

+ [note de bas de page](https://gitlab.pagedmedia.org/tools/pagedjs/issues/161)

`r icon::fontawesome(style = "solid", "bolt")` Et le package est en plein développement.

---
## Développer en pratique

`r icon::fontawesome(style = "solid", "check")` Diviser ses fichiers CSS en :

  + interface : tout ce qui sert à calibrer les fichiers : avec le paramètre `screen`
  + modules : tout ce qui va effectivement faire le style
  + [un exemple](https://github.com/spyrales/gouvdown/blob/propre/inst/resources/css/propre/interface/interface.css)

`r icon::fontawesome(style = "solid", "check")` Diviser les blocs de styles en plusieurs fichiers par thématique :  layout, variables, colors, fonts, etc.

`r icon::fontawesome(style = "solid", "check")` Utiliser des variables CSS depuis `:root` pour construire le style : couleur, taille de marge, police, lien vers une image, etc.

```
:root {
    /* fonts */
    --font-body: "Calibri";
    --font-title: "Calibri";
    /* colors */
    --main-color: #e5801c; /* light orange */
    --secondary-color: #b35136; /* darker shade of orange */
    /* img */
    --state-shape: url(../img/state_shape/000_black_box.png);
  }
```

---
## Développer en pratique

`r icon::fontawesome(style = "solid", "check")` Construire des [templates Rmd](https://bookdown.org/yihui/rmarkdown/document-templates.html) pour une utilisation répétée

`r icon::fontawesome(style = "solid", "check")` Gérer les interactions depuis l'externe - option 1 : avec [JavaScript](https://github.com/rfortherestofus/pagedreport/blob/main/inst/resources/html/template_paged.html#L183)

`r icon::fontawesome(style = "solid", "lightbulb")` On génère une variable CSS qu'on va réutiliser

```
{
  let StateShapeCont = document.querySelector('h1.title')
                               .textContent
                               .replace(/\s+/g, "_");
  let StateShapeContUrl =
    `url(style/img/state_shape/${StateShapeCont}.png)`;
  document.documentElement
          .style
          .setProperty('--state-shape', StateShapeContUrl);
}
```

---
## Développer en pratique

`r icon::fontawesome(style = "solid", "check")` Gérer les interactions depuis l'externe - option 2 : [avec R](https://github.com/rfortherestofus/pagedreport/blob/main/R/paged_hazelnuts.R#L27)

`r icon::fontawesome(style = "solid", "lightbulb")` On génère une variable CSS ou une image qu'on va réutiliser (nécessite un template)

```
if (img_to_dark == TRUE) {
    front_img_init <-
      magick::image_read(front_img)
    front_img_ok <-
      magick::image_colorize(front_img_init, opacity = 50, color = "black")

  front_img <- paste0(tempfile("front_img"), ".jpg")
    magick::image_write(front_img_ok, front_img, format = "jpg")
  }
  
  pagedown::html_paged(
    front_cover = c(front_img),
    ...
  )
```

---
## Trouver de la documentation

`r icon::fontawesome(style = "solid", "file")` Regarder des utilisations existantes : 

  + Par [J-D Barillas](https://github.com/jdbarillas/executive_summary)
  + [Template SGDF](https://github.com/tvroylandt/sgdf_pagedown)
  + PROPRE (présentée plus bas)
  + [Omni](https://github.com/rfortherestofus/omni)

`r icon::fontawesome(style = "solid", "images")` [Présentation à uRos](https://speakerdeck.com/rlesur/reproducible-corporate-publications-with-pagedown) par Romain Lesur
  
`r icon::fontawesome(style = "solid", "code-branch")` [Une PR sur le Github](https://github.com/rstudio/pagedown/pull/81/files)

`r icon::fontawesome(style = "solid", "code-branch")` [Les issues](https://github.com/rstudio/pagedown/issues/)

`r icon::fontawesome(style = "solid", "book")` La documentation de [paged.js](https://www.pagedjs.org/documentation/)
  
`r icon::fontawesome(style = "solid", "code-branch")` [Le Gitlab de paged.js](https://gitlab.pagedmedia.org/tools/pagedjs)

---
class: inverse, center, middle

# Et en pratique, ça donne quoi ?

---
## La démarche PROPRE - rapport

Pour plus de détail sur le projet, voir les présentations d'hier sur PROPRE et [`gouvdown`](https://github.com/tvroylandt/gouvdown_rr_2021).

`r icon::fontawesome(style = "solid", "code-branch")` La [PR](https://github.com/spyrales/gouvdown/pull/34) et le [repo de démonstration de la brochure](https://github.com/spyrales/propre.brochure)

```{r, fig.height=4, fig.align='center'}
knitr::include_graphics("https://raw.githubusercontent.com/spyrales/propre.brochure/master/screenshot.png", dpi = 600)
```

---
## La démarche PROPRE - rapport

`r icon::fontawesome(style = "solid", "user-friends")` Une organisation du travail originale avec un graphiste et un dev R : un grand merci à Julien Taquet.

`r icon::fontawesome(style = "solid", "check")` A la source des bonnes pratiques mentionnées plus haut

`r icon::fontawesome(style = "solid", "terminal")` Des [interactions avec R](https://github.com/spyrales/gouvdown/pull/34/files#diff-2082c075edcc0879e60c8d3026822594d3bbe152713e013fa5d58d0a609e54e5) pour définir une largeur de colonne variable

```
width_css <- tempfile(fileext = ".css")

writeLines(paste(
  paste0(":root {--main-column-width:", width_main_column , "%;}"),
  paste0(":root {--secondary-column-width:", 100 - width_main_column - 5, 
          "%;}"), sep = "\n"
),
con = width_css)

# render
pagedown::html_paged(
  [...]
  css = c(css, book_css, width_css, made_with_css),
  ...
)
```

---
## CT Data - fiches automatisées

`r icon::fontawesome(style = "solid", "building")` Un projet en collaboration avec [R for the Rest of Us](https://rfortherestofus.com/) et [CTData](https://www.ctdata.org/) pour le [Partnership for Strong Communities](https://www.pschousing.org/)

`r icon::fontawesome(style = "solid", "map")` Générer des [rapports automatisés](https://housingprofiles.pschousing.org/) sur chaque ville du Connecticut : [Bloomfield](https://housing-profiles.s3.amazonaws.com/2020/Bloomfield.pdf)

```{r, fig.align='center', out.height='200px', out.width='400px'}
knitr::include_graphics("img/psc_housing_1.png", dpi = 300)
knitr::include_graphics("img/psc_housing_2.png", dpi = 300)
```

---
## CT Data - fiches automatisées

`r icon::fontawesome(style = "solid", "bomb")` La principale contrainte est la génération automatique :

  + les graphiques ne comportent pas forcément le même nombre d'éléments 
  + des textes générés peuvent se retrouver à vide
  + des trous dans les données peuvent créer des erreurs
  
`r icon::fontawesome(style = "solid", "check")` Il faut donc :

  + bien spécifier la taille de chaque sortie
  + remplir les valeurs manquantes dans les jeux de données et prévoir ces cas
  
`r icon::fontawesome(style = "solid", "file")` Pour une structure aussi stricte, la forme est très présente dans le Rmd :

  + pages nommées
  + utilisation de CSS pour les mises en colonnes

---
class: last, center, middle

# Merci de votre attention !

### Merci aussi à Romain Lesur, Julien Taquet, Christophe Dervieux, Diane Beldame, David Keyes pour leurs échanges et leur travail sur le sujet !

# `r icon::fontawesome(style = "solid", "phone")`  Pour discuter : [thomas@tillac-data.com](mailto:thomas@tillac-data.com)