---
title: "Setting default options"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{setting-defaults}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

You can change the defaults for `tinify()` using `tinify_defaults()`. `tinify_defaults()` takes all the same arguments as `tinify()` except `file` and `key`.

Any arguments set in `tinify_defaults()` will apply to all subsequent calls of `tinify()`:

``` r
tinify("example.png")

#> Filesize reduced by 50%:
#> example.png (20K) => example_tiny.png (10K)
#> 13 Tinify API calls this month

tinify_defaults(suffix = "_small")

#> Tinify 'suffix' changed to: "_small"

tinify("example2.png")

#> Filesize reduced by 50%:
#> example2.png (20K) => example2_small.png (10K)
#> 14 Tinify API calls this month
```

Setting the defaults, and in particular `return_path`, lets you use easily use `tinify()` in other image functions that take a string as the image file path to automatically shrink, resize, and insert images throughout your document:

```r
tinify_defaults(suffix = "_resized",
                quiet = TRUE,
                return_path = "proj", 
                resize = list(method = "scale",
                             width = 100))

#> Tinify 'suffix' changed to: "_resized"
#> Tinify 'quiet' changed to: TRUE
#> Tinify 'return_path' changed to: "proj"
#> Tinify 'resize' method changed to: "scale"
#> Tinify 'resize' width changed to: 100

knitr::include_graphics(tinify("imgs/example1.png"))

knitr::include_graphics(tinify("imgs/example2.png"))
```

## Viewing current defaults

To see **all** the current defaults set, call `tinify_defaults()` without any arguments:

```r
tinify_defaults()

#> Tinify 'overwrite' set to: FALSE
#> Tinify 'suffix' set to: "_tiny"
#> Tinify 'quiet' set to: FALSE
#> Tinify 'return_path' set to: No return
#> Tinify 'resize' set to: No resize
```

## Overrule defaults

Any arguments supplied directly to `tinify()` will **always** overrule any default options:

``` r

tinify_defaults(suffix = "_small")

#> Tinify 'suffix' changed to: "_small"

tinify("example2.png", suffix = "_shrunk")

#> Filesize reduced by 50%:
#> example2.png (20K) => example2_shrunk.png (10K)
#> 15 Tinify API calls this month

tinify("example3.png")

#> Filesize reduced by 50%:
#> example2.png (20K) => example2_small.png (10K)
#> 16 Tinify API calls this month
```

## Setting defaults from YAML file

If you use Rstudio projects and would like to set the defaults for an entire project, you could also include a `tinify.yml` file in your project directory with your desired default options:

```yaml
suffix: "_resized"
quiet: true
resize:
  method: "scale"
  width: 300
```

If `tinify.yml` is present in your project directory, these options will be detected and set as the defaults when you load tinieR with `library(tinieR)` or using `tinieR::`. *Note: these will not change any options previously set manually using `options()` prior to loading tinieR.*

Once loaded, these options can still be changed with `tinify_defaults()` or overruled by providing arguments in `tinify()` as normal, if required.

## Returning to default options

The options `quiet` and `overwrite` only accept `TRUE` or `FALSE` as their settings. If you change one of these and wish to change it back, just set it again with the opposite option:

``` r
tinify_defaults(quiet = FALSE)

#> Tinify 'quiet' changed to: FALSE
```

For `suffix`, you must enter a character string as an option. If you change `suffix` and wish to set it back to the default, just set it again as `"_tiny"`:

``` r
tinify_defaults(suffix = "_tiny")

#> Tinify 'suffix' changed to: "_tiny"
```

If you set defaults for either `return_path` or `resize` and wish to switch these options back off again, just set them to `NULL`:

``` r
tinify_defaults(return_path = NULL)

#> Tinify 'return_path' changed to: No return
```

Finally, if you unload the tinieR package, you will also clear any default options currently set. If you then reload the package, tinieR will try and load any defaults from `tinify.yml` if present, then default to the package default settings.