--- title: "Auxiliary Templates" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Auxiliary Templates} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include=FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r setup, include=FALSE} library(jinjar) ``` As the complexity of your templating project grows, it can be helpful to refactor common pieces into auxiliary templates so they can be reused. The [`{% include %}`](#include) and [`{% extends %}`](#extends) tags support two very different approaches to this, described below. ## Loading Auxiliary Templates When your main template makes reference to auxiliary templates, you'll need to specify how the templating engine can find these auxiliary templates. This is achieved using a template loader (see `help("loader")`). There are different types of loader, but `path_loader()` is the most commonly used. This allows you to specify the directory where auxiliary templates are stored in files. Imagine you have a main template that uses nested template inheritance (`content` inherits from `blog_post.html`, which in turns inherits from `base.html`). You might store these two auxiliary templates in a templates directory: ```shell /path/to/templates/ |-- base.html |-- blog_post.html ``` When rendering the main template, you create the loader object as part of the engine configuration: ```{r, eval=FALSE} config <- jinjar_config(loader = path_loader("path", "to", "templates")) output <- render(content, !!!data, .config = config) ``` ## Template Inclusion {#include} The `include` tag can be used to include an auxiliary template and return the rendered contents of that file into the main document. Included templates have access to the same variables as the main template. By default, an error is raised if the included template cannot be found. You can ignore these errors by setting the `ignore_missing_files` argument in `jinjar_config()`. As an example, we create an auxiliary file `header.html` with contents: ```{cat, engine.opts=list(file="header.html", lang="html")}
Welcome to my blog!
{% endblock %} ``` This child template defines the three blocks declared by the parent template: `head`, `title` and `content`. In the case of the `head` block, it uses `{{ super() }}` to render the contents of the `head` block defined by the parent template. If we were using nested `extends` tags, we could pass an argument to skip levels in the inheritance tree (e.g. `{{ super(2) }}`). ```{r clean_extends, include=FALSE} unlink(c("base.html")) ```