---
title: "Config files"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Config files}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Purpose

This vignette provides an overview of how to use a config file with the {aftables} package to set workbook properties and formatting.

## Workbook properties and formatting which can be set in a config file

Workbook properties:

 - Author
 - Title
 - Keywords
 - Subject
 - Category
 - Comments

Analysis Function guidance advises workbooks should have the author, title, keywords and language document properties completed. aftables provides functionality to set the author, title and keywords properties. See ['Releasing statistics in spreadsheets'](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) for more information including how to set the workbook language.

Workbook formatting:

 - Font name
 - Font sizes
 - Column widths

## Structure of a config file

The config file must include an `aftables` entry. {aftables} will only look for workbook configs below the `aftables` entry. The config file may include any other entries. This means {aftables} settings can be added to an existing config file without conflicts.

The `aftables` config file supports multiple entries. There must be at least one config below the `aftables` entry, which could be named `default` or be a user-specified custom config.

Each config must contain at least one of `workbook_properties` and `workbook_format`. The value of each key below `workbook_properties` must be a character string apart from `keywords`, which is a character vector. The value of every key below `workbook_format` must be an integer apart from `base_font_name` which must be a character string. {aftables} checks all config keys to ensure they are character strings or integers as required to process them correctly.

This is the contents of the example config file included with {aftables}:

```{r results='asis', echo = FALSE}
cat("```xml\n")
cat(readLines(system.file("ext-data",
                          "config.yaml",
                          package = "aftables")),
    sep = "\n")
cat("\n```\n")
```

Values of keys below `workbook_properties` will appear in the Excel workbook when it is saved using wb_save from openxlsx2. They can be found in the file properties or the workbook information.

Values of keys below `workbook_format` will be applied to the contents of the workbook. The values of `base_font_name` and `base_font_size` define the default font name and size used by the workbook. All text not formatted as a table header, sheet subheading or sheet heading will use the default settings. Font sizes of sheet headings, sheet subheadings, and table header rows will use the values of `sheet_heading_size`, `sheet_subheading_size` and `table_header_size` respectively, and they will additionally be formatted as bold.

The values of `cellwidth_default`, `cellwidth_wider` and `nchar_break` are used to define column widths. The units of `cellwidth_default` and `cellwidth_wider` are the column width values used by Excel. All columns widths are set by default to use the `cellwidth_default` value. If the number of characters in a column header or the contents of a column exceeds the value of `nchar_break` aftables will set the column width to the value of `cellwidth_wider`. Users can avoid text wrapping in columns or column headers by setting the value of `nchar_break` based on their data or the content of their column headers.

The `create_config_yaml()` function outputs a copy of this config file to a location of the users choice. The default location is the current working directory. We recommend using the example config file as a basis for developing your own {aftables} config file.

## Applying a config file with `generate_workbook()`

The `generate_workbook()` function has two arguments for config files: `config_path` and `config_name`. Both arguments are optional, and {aftables} will take different action based on which arguments are provided.

{aftables} will look for a config file using the `config_path` argument. By default {aftables} will look in the current working directory for a config file named `config.yaml`. `config_path` can be set to NULL and {aftables} will not look for a config file.

{aftables} will only use the `config_name` argument if a config file is found. {aftables} config files must have an `aftables` entry containing one or more configs. These configs can be a `default` config and/or any user-specified custom configs. Users can set up multiple custom configs to produce multiple workbooks from a single config file. Settings common to all workbooks would be set in the `default` config, and settings specific to each workbook would be set in separate custom configs. The `default` config is optional, and custom configs can be used to specify all workbook properties and formatting. When a config file contains both a `default` config and a user-specified custom config matching the `custom_name` argument a combined config is generated from the `default` config and the `config_name` custom config. Values specified in the `config_name` custom config are preferred over the `default` config.

### Example 1: No config arguments in generate_workbook

```{r config example 1, eval = FALSE}
my_wb <- generate_workbook(aftable = demo_aftable)
```

When the user does not provide any config arguments to {aftables} it will look in the working directory for a `config.yaml` file. If {aftables} finds a config file it will look for an `aftables` entry with a `default` config. If {aftables} cannot find a config file or the config file doesn't contain an `aftables` entry with a `default` config, it will generate an {openxlsx2} wbWorkbook object named `my_wb` without applying any config. Otherwise {aftables} will generate an {openxlsx2} wbWorkbook object named `my_wb` with the `default` config applied. This is the default behaviour of the {generate_workbook} function.

### Example 2: Using a custom config

```{r config example 2, eval = FALSE}
my_wb <- generate_workbook(
  aftable = demo_aftable,
  config_name = "workbook1"
)
```

{aftables} will look in the working directory for a file named `config.yaml` and import the `aftables` entry. It will look for the `workbook1` config as well as a `default` config. If there is no `aftables` entry or `workbook1` config, {aftables} will stop with an error. If both the `default` and `workbook1` configs exist {aftables} will combine them, preferring values specified in the `config_name` custom config over those in the `default` config. If there is no `default` config all values will be taken from the `workbook1` config. {aftables} will generate an {openxlsx2} wbWorkbook object named `my_wb` with the `workbook1` or combined config applied.

### Example 3: Using a custom config file

```{r config example 3, eval = FALSE}
dir.create("configs")

create_config_yaml(
  path = "configs",
  open_config = FALSE
)

my_wb <- generate_workbook(
  aftable = demo_aftable,
  config_path = "configs/config.yaml"
)
```

{aftables} will look for the user-specified config file from `config_path` and import the `aftables` entry. It will look for the `default` config. If there is no `aftables` entry or `default` config, {aftables} will stop with an error. Otherwise {aftables} will generate an {openxlsx2} wbWorkbook object named `my_wb` with the `default` config applied.

### Example 4: Using a custom config file with a custom config

```{r config example 4, eval = FALSE}
dir.create("configs")

create_config_yaml(
  path = "configs",
  open_config = FALSE
)

my_wb <- generate_workbook(
  aftable = demo_aftable,
  config_path = "configs/config.yaml",
  config_name = "workbook1"
)
```

{aftables} will look for the user-specified config file from `config_path` and import the `aftables` entry. It will look for the `workbook1` config as well as a `default` config. If there is no `aftables` entry or `workbook1` config, {aftables} will stop with an error. If both the `default` and `workbook1` configs exist {aftables} will combine them, preferring values specified in the `config_name` custom config over those in the `default` config. If there is no `default` config all values will be taken from the `workbook1` config. {aftables} will generate an {openxlsx2} wbWorkbook object named `my_wb` with the `workbook1` or combined config applied.