---
title: "Introduction to condformat"
author: "Sergio Oller"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to condformat}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Quickstart

`condformat` prints a data frame with cells formatted according to several
rules or criteria. It is integrated with the RStudio Viewer or a web browser,
and it supports `knitr` and `rmarkdown` outputs using both HTML and PDF
($\LaTeX$) output formats. Other formats are not supported,
although patches to enable them are welcome.

## Basic syntax

Its syntax should be familiar to `ggplot` users, with tidy evaluation.

    condformat(a_data_frame) |>          # A data frame to print
      rule_fill_discrete(ColumnA) |>     # Add formatting rules to the data frame
      rule_fill_gradient(ColumnB)

## Example:

```{r}
data(iris)
library(condformat)
condformat(iris[c(1:5,70:75, 120:125),]) |>
  rule_fill_discrete(Species) |>
  rule_fill_discrete(c(Sepal.Width, Sepal.Length),
                     expression = Sepal.Width > Sepal.Length - 2.25,
                     colours = c("TRUE" = "#7D00FF")) |>
  rule_fill_gradient2(Petal.Length) |>
  rule_text_bold(Sepal.Length, Species == "setosa") |>
  rule_text_color(Sepal.Length, ifelse(Species == "setosa", "yellow", "")) |>
  rule_fill_bar(Petal.Width, limits = c(0, NA))
```

## The `.col` pronoun

When a rule targets several columns at once, its `expression` can use the
`.col` pronoun to refer to each targeted column's own values, instead of a
single shared expression applied identically to every column. This:

```{r, eval = FALSE}
condformat(iris) |>
  rule_fill_discrete(c(Sepal.Length, Sepal.Width), .col > 3)
```

is equivalent to chaining the rule once per column:

```{r, eval = FALSE}
condformat(iris) |>
  rule_fill_discrete(Sepal.Length, Sepal.Length > 3) |>
  rule_fill_discrete(Sepal.Width, Sepal.Width > 3)
```

`.col` works the same way in `rule_fill_gradient()`, `rule_fill_gradient2()`,
`rule_fill_bar()`, `rule_text_bold()`, `rule_text_color()` and `rule_css()`.
If `expression` is omitted entirely, it now defaults to `.col`, so each
selected column is formatted based on its own values.