Add spec_tooltip & spec_popover; Update documentation
diff --git a/docs/awesome_table_in_html.Rmd b/docs/awesome_table_in_html.Rmd
index fa6c222..66ad67e 100644
--- a/docs/awesome_table_in_html.Rmd
+++ b/docs/awesome_table_in_html.Rmd
@@ -143,34 +143,134 @@
row_spec(3:5, bold = T, color = "white", background = "#D7261E")
```
-# Cell Specification
-`cell_spec` is different from the rest. You should use it before you pipe the table into the `kable` function. It is designed in such a way that you can easily use it inside a `dplyr::mutate()` together with conditional logic like `ifelse`. Since everything happens before `kable`, you have to tell this function which format you want to go to, `html` or `latex`. To reduce unnecessary finger typing, I linked the `format` argument here with `knitr::kable`'s global format option `knitr.table.format`. If you have defined this option to be `html` at the beginning of your document (as suggested earlier), it is not necessary for you to define format again for every `cell_spec`.
-```{r, message=FALSE}
-library(dplyr)
-mtcars[1:5, 1:3] %>%
- mutate(
- car = row.names(.),
- mpg = ifelse(mpg > 20,
- cell_spec(mpg, "html", font_size = 18), mpg),
- cyl = cell_spec(cyl, "html", angle = (1:5)*60, hover_message = mpg,
- background = "red", color = "white", align = "center"),
- disp = ifelse(disp > 200,
- cell_spec(disp, "html", color = "red", bold = T),
- cell_spec(disp, "html", color = "green", italic = T)),
- fancy = c(12, 14, 16, 18, 20),
- fancy = cell_spec(fancy, "html", font_size = fancy,
- color = viridisLite::inferno(length(fancy), end = 0.8)),
- car = cell_spec(car, "html", bold = T,
- color = viridisLite::inferno(length(fancy), end = 0.8))
- ) %>%
- select(car, everything()) %>%
- kable("html", escape = F) %>%
- kable_styling("hover", full_width = F) %>%
- add_header_above(c(" ", "Hello" = 2, "World" = 2))
+
+## Header Rows
+One special case of `row_spec` is that you can specify the format of the header row via `row_spec(row = 0, ...)`.
+```{r}
+kable(dt, format = "html") %>%
+ kable_styling("striped", full_width = F) %>%
+ row_spec(0, angle = -45)
```
-##
+# Cell/Text Specification
+Function `cell_spec` is introduced in version 0.6.0 of `kableExtra`. Unlike `column_spec` and `row_spec`, **this function is designed to be used before the data.frame gets into the `kable` function**. Comparing with figuring out a list of 2 dimentional index for targeted cells, this design is way easier to learn and use and it fits perfectly well with `dplyr`'s `mutate` and `summarize` functions. With this design, there are two things to be noted:
+* Since `cell_spec` generates raw `HTML` or `LaTeX` code, make sure you remember to put `escape = FALSE` in `kable`. At the same time, you have to escape special symbols including `%` manually by yourself
+* `cell_spec` needs a way to know whether you want `html` or `latex`. You can specify it locally in function or globally via the `options(knitr.table.format = "latex")` method as suggested at the beginning. If you don't provide anything, this function will output as HTML by default.
+
+Currently, `cell_spec` supports features including bold, italic, monospace, text color, background color, align, font size & rotation angle. More features may be added in the future. Please see function documentations as reference.
+
+## Conditional logic
+It is very easy to use `cell_spec` with conditional logic. Here is an example.
+```{r, message=FALSE, warning=FALSE}
+library(dplyr)
+mtcars[1:10, 1:2] %>%
+ mutate(
+ car = row.names(.),
+ # You don't need format = "html" if you have ever defined options(knitr.table.format)
+ mpg = cell_spec(mpg, "html", color = ifelse(mpg > 20, "red", "blue")),
+ cyl = cell_spec(cyl, "html", color = "white", align = "c", angle = 45,
+ background = factor(cyl, c(4, 6, 8),
+ c("#666666", "#999999", "#BBBBBB")))
+ ) %>%
+ select(car, mpg, cyl) %>%
+ kable("html", escape = F) %>%
+ kable_styling("striped", full_width = F)
+```
+
+## Visualize data with Viridis Color
+This package also comes with a few helper functions, including `spec_color`, `spec_font_size` & `spec_angle`. These functions can rescale continuous variables to certain scales. For example, function `spec_color` would map a continuous variable to any [viridis color palettes](https://cran.r-project.org/web/packages/viridis/vignettes/intro-to-viridis.html). It offers a very visually impactful representation in a tabular format.
+
+```{r}
+iris[1:10, ] %>%
+ mutate_if(is.numeric, function(x) {
+ cell_spec(x, "html", bold = T, color = spec_color(x, end = 0.9),
+ font_size = spec_font_size(x))
+ }) %>%
+ mutate(Species = cell_spec(
+ Species, "html", color = "white", bold = T,
+ background = spec_color(1:10, end = 0.9, option = "A", direction = -1)
+ )) %>%
+ kable("html", escape = F, align = "c") %>%
+ kable_styling("striped", full_width = F)
+```
+
+In the example above, I'm using the `mutate` functions from `dplyr`. You don't have to use it. Base R solutions like `iris$Species <- cell_spec(iris$Species, color = "red")` also works.
+
+## Text Specification
+If you check the results of `cell_spec`, you will find that this function does nothing more than wrapping the text with appropriate HTML/LaTeX formatting syntax. The result of this function is just a vector of character strings. As a result, when you are writing a `rmarkdown` document or write some text in shiny apps, if you need extra markups other than **bold** or *italic*, you may use this function to `r text_spec("color", color = "red")`, `r text_spec("change font size ", font_size = 16)` or `r text_spec("rotate", angle = 30)` your text.
+
+An aliased function `text_spec` is also provided for a more literal writing experience. In HTML, there is no difference between these two functions.
+
+```{r}
+sometext <- strsplit(paste0(
+ "You can even try do do some crazy things like this paragraph. ",
+ "It seems to be a useless feature at this moment but who cares. ",
+ "It is so fun to play with color that I can't stop. ;)"
+), " ")[[1]]
+text_formatted <- paste(
+ text_spec(sometext, "html", color = spec_color(1:length(sometext), end = 0.9),
+ font_size = spec_font_size(1:length(sometext), begin = 5, end = 20)),
+ collapse = " ")
+
+# To display the text, type `r text_formatted` outside of the chunk
+```
+`r text_formatted`
+
+## Tooltip
+It's very easy to add a tooltip to text via `cell_spec`. For example, `text_spec("tooltip", color = "red", tooltip = "Hello World")` will give you something like `r text_spec("Hover over me", color = "red", tooltip = "Hello World")` (you need to wait for a few seconds before your browser renders it).
+
+Note that the original browser-based tooltip is slow. If you want to have a faster response, you may want to initialize bootstrap's tooltip by putting the following HTML code on the page.
+```
+<script>
+$(document).ready(function(){
+ $('[data-toggle="tooltip"]').tooltip();
+});
+</script>
+```
+
+In a rmarkdown document, you can just drop it outside of any R chunks. Unfortunately however, for rmarkdown pages with a **floating TOC** (like this page), you can't use bootstrap tooltips because there is a conflict in namespace between Bootstrap and JQueryUI (tocify.js). As a result, I can't provide a live demo here. If you want to have a tooltip together with a floating TOC, you should use `popover` which has a very similar effect.
+
+
+
+## Popover Message
+The popover message looks very similar with tooltip but it can hold more contents. Unlike tooltip which can minimally work without you manually enable that module, you **have to** enable the `popover` module to get it work. The upper side is that there is no conflict between Bootstrap & JQueryUI this time, you can use it without any concern.
+
+```
+<script>
+$(document).ready(function(){
+ $('[data-toggle="popover"]').popover();
+});
+</script>
+```
+
+<script>
+$(document).ready(function(){
+ $('[data-toggle="popover"]').popover();
+});
+</script>
+
+```{r}
+popover_dt <- data.frame(
+ position = c("top", "bottom", "right", "left"),
+ stringsAsFactors = FALSE
+)
+popover_dt$`Hover over these items` <- cell_spec(
+ paste("Message on", popover_dt$position), # Cell texts
+ popover = spec_popover(
+ content = popover_dt$position,
+ title = NULL, # title will add a Title Panel on top
+ position = popover_dt$position
+ ))
+kable(popover_dt, "html", escape = FALSE) %>%
+ kable_styling("striped", full_width = FALSE)
+```
+
+## Links
+You can add links to text via `text_spec("Google", link = "https://google.com")`: `r text_spec("Google", link = "https://google.com")`. If you want your hover message to be more obvious, it might be a good idea to put a `#` in the `link` option.
+`text_spec("Hover on me", link = "#", popover = "Hello")`:
+`r text_spec("Hover on me", link = "#", popover = "Hello")`
+
# Grouped Columns / Rows
## Add header rows to group columns