---
title: "Templates"
output: rmarkdown::html_vignette
description: >
  Getting started with imola's layout templates.
vignette: >
  %\VignetteIndexEntry{Using Templates}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{css, echo = FALSE}
img {
  max-width: 100%;
}
```

Templates are a quick way of reusing the same layouts between different components and even projects. To accommodate this process imola introduces a simple template engine.

---

## Creating templates

Templates can be created via `gridTemplate()`.

They are collections of arguments that can be passed to a `grid` or `flex` function.

In practice this means they share all the properties of those arguments, including:

 -   Support for breakpoints
 -   Allowing both css notation (a string with values separated by a space) or vector notation (a vector where each element is a value).

It is important to note that templates require a name and a type.

The name is simply an identifier for the template (useful later for registering templates) and the type defines what type of functions it can be used for (`grid` or `flex`).

Trying to apply a template of the wrong type to a `panel` or page `function` is not possible.

``` r
mytemplate <- gridTemplate("myareas", "grid",
  areas = list(
    default = c(
      "area1 area1 area1",
      "area2 area3 area3",
      "area2 area3 area3"
    ),
    xs = c(
      "area1",
      "area2",
      "area3"
    )
  ),
  gap = "20px"
)
```

We can then use this template object as a value for the template argument in grid panels or pages:

``` r
#in ui.R
gridPanel(
  id = "somePanel"
  template = mytemplate
  area1 = div("area 1 content"),
  area2 = div("area 2 content"),
  area3 = div("area 3 content")
)
```

---

## Registering templates

Registered templates are templates that are either bundled with imola, or added to the global template list by using `registerTemplate()` on a template object.

You can view all registered templates by using `listTemplates()`.

By registering a template you are making it available outside of the scope where it is created, meaning it will be available to use even if the object itself was created somewhere else.

This approach allows us to create and register templates before they are needed, making them easier to bundle and manage when a lot of templates are needed.

``` r
#in global.R
mytemplate <- gridTemplate("myareas", "grid",
  areas = list(
    default = c(
      "area1 area1 area1",
      "area2 area3 area3",
      "area2 area3 area3"
    ),
    xs = c(
      "area1",
      "area2",
      "area3"
    )
  ),
  gap = "20px"
)

# register it globally
registerTemplate(mytemplate)
```

Calling `registerTemplate()` on a `gridTemplate()` object adds that template available to use in any `page` or `panel` page directly by its `name`:

``` r
#in ui.R
gridPanel(
  id = "somePanel"
  template = "myareas"
  area1 = div("area 1 content"),
  area2 = div("area 2 content"),
  area3 = div("area 3 content")
)
```

If needed you can also remove a template from the global list using `unregisterTemplate("name", "type")`:

``` r
# unregister a template
unregisterTemplate("myareas", "grid")
```

Registered templates can also be turned back into a template object using `getTemplate()`. This object can then be used and if created with `gridTemplate()`.

---

## Bundled templates

By default imola also includes some ready to use templates. Similar to manually registered templates these are also listed under `listTemplates()`.

These can be used just like registered templates, with the difference that they do not require manually registering them:

``` r
#in ui.R
gridPanel(
  template = "header-sidebar-right"
  header = div("header"),
  content = div("content"),
  sidebar = div("sidebar")
)
```

For a demo on all templates bundled with imola, [click here](https://sparktuga.shinyapps.io/imolatemplates/)

---

## Importing and Exporting

It is also possible to import and export template objects for future usage in different projects. In this case you can make use of `exportTemplate()` and `importTemplate()`.

`exportTemplate()` allows you to export a template object into a specific file.

This file will contain all the necessary information to rebuild the template, even in a different project, and can be turned back into a template object using `importTemplate()`.
