Version 1.1 release
diff --git a/vignettes/awesome_table_in_html.Rmd b/vignettes/awesome_table_in_html.Rmd
index e23cf9f..576bcf9 100644
--- a/vignettes/awesome_table_in_html.Rmd
+++ b/vignettes/awesome_table_in_html.Rmd
@@ -119,6 +119,14 @@
kable_styling(bootstrap_options = "striped", font_size = 7)
```
+## Fixed Table Header Row
+If you happened to have a very long table, you may consider to use this `fixed_header` option to fix the header row on top as your readers scroll. By default, the background is set to white. If you need a different color, you can set `fixed_header = list(enabled = T, background = "red")`.
+
+```{r}
+kable(mtcars[1:10, 1:5]) %>%
+ kable_styling(fixed_thead = T)
+```
+
# Column / Row Specification
## Column spec
When you have a table with lots of explanatory texts, you may want to specified the column width for different column, since the auto adjust in HTML may not work in its best way while basic LaTeX table is really bad at handling text wrapping. Also, sometimes, you may want to highlight a column (e.g. a "Total" column) by making it bold. In these scenario, you can use `column_spec()`. You can find an example below.
@@ -176,13 +184,13 @@
mtcars[1:10, 1:2] %>%
mutate(
car = row.names(.),
- mpg = cell_spec(mpg, color = ifelse(mpg > 20, "red", "blue")),
- cyl = cell_spec(cyl, color = "white", align = "c", angle = 45,
+ 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(escape = F) %>%
+ kable(format = "html", escape = F) %>%
kable_styling("striped", full_width = F)
```
@@ -322,31 +330,49 @@
```
## Group rows via labeling
-Sometimes we want a few rows of the table being grouped together. They might be items under the same topic (e.g., animals in one species) or just different data groups for a categorical variable (e.g., age < 40, age > 40). With the new function `group_rows()` in `kableExtra`, this kind of task can be completed in one line. Please see the example below. Note that when you count for the start/end rows of the group, you don't need to count for the header rows nor other group label rows. You only need to think about the row numbers in the "original R dataframe".
+Sometimes we want a few rows of the table being grouped together. They might be items under the same topic (e.g., animals in one species) or just different data groups for a categorical variable (e.g., age < 40, age > 40). With the function `group_rows()`/`pack_rows()` in `kableExtra`, this kind of task can be completed in one line. Please see the example below. Note that when you count for the start/end rows of the group, you don't need to count for the header rows nor other group label rows. You only need to think about the row numbers in the "original R dataframe".
```{r}
kable(mtcars[1:10, 1:6], caption = "Group Rows") %>%
kable_styling("striped", full_width = F) %>%
- group_rows("Group 1", 4, 7) %>%
- group_rows("Group 2", 8, 10)
+ pack_rows("Group 1", 4, 7) %>%
+ pack_rows("Group 2", 8, 10)
```
-Another way to use `group_rows` is to provide an grouping index, similar with `add_header_above()`. This feature is only available in kableExtra > 0.5.2.
+Another way to use `pack_rows` is to provide an grouping index, similar with `add_header_above()`. This feature is only available in kableExtra > 0.5.2.
```{r, eval = F}
# Not evaluated. This example generates the same table as above.
kable(mtcars[1:10, 1:6], caption = "Group Rows") %>%
kable_styling("striped", full_width = F) %>%
- group_rows(index = c(" " = 3, "Group 1" = 4, "Group 2" = 3))
+ pack_rows(index = c(" " = 3, "Group 1" = 4, "Group 2" = 3))
```
For advanced users, you can even define your own css for the group labeling.
```{r}
kable(dt) %>%
kable_styling("striped", full_width = F) %>%
- group_rows("Group 1", 3, 5, label_row_css = "background-color: #666; color: #fff;")
+ pack_rows("Group 1", 3, 5, label_row_css = "background-color: #666; color: #fff;")
+```
+
+`r text_spec("Important Note!", bold = T, color = "#D7261E")`
+
+Note that `dplyr` 0.8.0+ introduced a `group_rows` function as well for a trivial feature. Therefore, I'm create this `pack_rows` function as an alias to the original `group_rows`. In the future, **I recommend all kableExtra users to use `pack_rows` instead of `group_rows` to get rid of the NAMESPACE conflict.**
+
+Alternatively, for pre-existing codes, you have two ways to solve this. You can either load `kableExtra` after `dplyr` or `tidyverse`, or to use the `conflicted` package. Here is an example.
+
+```{r, eval=F}
+# Method 1
+pack_rows() # instead of group_rows()
+
+# Method 2
+library(dplyr)
+library(kableExtra)
+
+# Method 3
+conflicted::conflict_prefer("group_rows", "kableExtra", "dplyr")
```
## Row indentation
-Unlike `group_rows()`, which will insert a labeling row, sometimes we want to list a few sub groups under a total one. In that case, `add_indent()` is probably more apporiate.
+Unlike `pack_rows()`, which will insert a labeling row, sometimes we want to list a few sub groups under a total one. In that case, `add_indent()` is probably more apporiate.
For advanced users, you can even define your own css for the group labeling.
```{r}
kable(dt) %>%
@@ -355,7 +381,7 @@
```
## Group rows via multi-row cell
-Function `group_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider to use `collapse_rows` instead, which will put repeating cells in columns into multi-row cells. The vertical allignment of the cell is controlled by `valign` with default as "top".
+Function `pack_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider to use `collapse_rows` instead, which will put repeating cells in columns into multi-row cells. The vertical allignment of the cell is controlled by `valign` with default as "top".
```{r}
collapse_rows_dt <- data.frame(C1 = c(rep("a", 10), rep("b", 5)),
@@ -436,10 +462,13 @@
```{r}
kable(cbind(mtcars, mtcars)) %>%
+ add_header_above(c("a" = 5, "b" = 18)) %>%
kable_styling() %>%
scroll_box(width = "100%", height = "200px")
```
+Starting from version 1.1.0, if you have a fixed-height box, the header row is fixed
+
## Save HTML table directly
If you need to save those HTML tables but you don't want to generate them through rmarkdown, you can try to use the `save_kable()` function. You can choose whether to let those HTML files be self contained (default is yes). Self contained files packed CSS into the HTML file so they are quite large when there are many.
```{r, eval=FALSE}
diff --git a/vignettes/awesome_table_in_pdf.Rmd b/vignettes/awesome_table_in_pdf.Rmd
index 881e5c6..257deb6 100644
--- a/vignettes/awesome_table_in_pdf.Rmd
+++ b/vignettes/awesome_table_in_pdf.Rmd
@@ -134,6 +134,13 @@
kable_styling(latex_options = "striped")
```
+You can also specify which rows you want to striped on via `stripe_index`. In most case, you might want to turn off the default 5 rows + a space setting in `knitr::kable()` by setting `linesep = ""`. See this SO answer for details. https://stackoverflow.com/questions/45409750/get-rid-of-addlinespace-in-kable.
+
+```{r}
+kable(mtcars[1:8, 1:4], "latex", booktabs = T, linesep = "") %>%
+ kable_styling(latex_options = "striped", stripe_index = c(1,2, 5:6))
+```
+
### Hold position
If you provide a table caption in `kable()`, it will put your LaTeX tabular in a `table` environment, unless you are using `longtable`. A `table` environment will automatically find the best place (it thinks) to put your table. However, in many cases, you do want your table to appear in a position you want it to be. In this case, you can use this `hold_position` options here.
```{r}
@@ -317,25 +324,25 @@
```
## Group rows via labeling
-Sometimes we want a few rows of the table being grouped together. They might be items under the same topic (e.g., animals in one species) or just different data groups for a categorical variable (e.g., age < 40, age > 40). With the new function `group_rows()` in `kableExtra`, this kind of task can be completed in one line. Please see the example below. Note that when you count for the start/end rows of the group, you don't need to count for the header rows nor other group label rows. You only need to think about the row numbers in the "original R dataframe".
+Sometimes we want a few rows of the table being grouped together. They might be items under the same topic (e.g., animals in one species) or just different data groups for a categorical variable (e.g., age < 40, age > 40). With the function `pack_rows`/`group_rows()` in `kableExtra`, this kind of task can be completed in one line. Please see the example below. Note that when you count for the start/end rows of the group, you don't need to count for the header rows nor other group label rows. You only need to think about the row numbers in the "original R dataframe".
```{r}
kable(mtcars[1:10, 1:6], "latex", caption = "Group Rows", booktabs = T) %>%
kable_styling() %>%
- group_rows("Group 1", 4, 7) %>%
- group_rows("Group 2", 8, 10)
+ pack_rows("Group 1", 4, 7) %>%
+ pack_rows("Group 2", 8, 10)
```
In case some users need it, you can define your own gapping spaces between the group labeling row and previous rows. The default value is `0.5em`.
```{r}
kable(dt, "latex", booktabs = T) %>%
- group_rows("Group 1", 4, 5, latex_gap_space = "2em")
+ pack_rows("Group 1", 4, 5, latex_gap_space = "2em")
```
If you prefer to build multiple groups in one step, you can use the short-hand `index` option. Basically, you can use it in the same way as you use `add_header_above`. However, since `group_row` only support one layer of grouping, you can't add multiple layers of grouping header as you can do in `add_header_above`.
```{r, eval=FALSE}
kable(mtcars[1:10, 1:6], "latex", caption = "Group Rows", booktabs = T) %>%
kable_styling() %>%
- group_rows(index=c(" " = 3, "Group 1" = 4, "Group 2" = 3))
+ pack_rows(index=c(" " = 3, "Group 1" = 4, "Group 2" = 3))
# Not evaluated. The code above should have the same result as the first example in this section.
```
@@ -355,7 +362,7 @@
LaTeX, somehow shows surprisingly high tolerance on that, which is quite unusual. As a result, it won't throw an error if you are just using `kable` to make some simple tables. However, when you use `kableExtra` to make some advanced modification, it will start to throw some bugs. As a result, please try to form a habit of using a vector in the `align` argument for `kable` (tip: you can use `rep` function to replicate elements. For example, `c("c", rep("l", 10))`).
## Row indentation
-Unlike `group_rows()`, which will insert a labeling row, sometimes we want to list a few sub groups under a total one. In that case, `add_indent()` is probably more appropriate.
+Unlike `pack_rows()`, which will insert a labeling row, sometimes we want to list a few sub groups under a total one. In that case, `add_indent()` is probably more appropriate.
For advanced users, you can even define your own css for the group labeling.
```{r}
kable(dt, "latex", booktabs = T) %>%
@@ -363,7 +370,7 @@
```
## Group rows via multi-row cell
-Function `group_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider using `collapse_rows` instead, which will put repeating cells in columns into multi-row cells.
+Function `pack_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider using `collapse_rows` instead, which will put repeating cells in columns into multi-row cells.
In LaTeX, `collapse_rows` adds some extra hlines to help differentiate groups. You can customize this behavior using the `latex_hline` argument. You can choose from `full` (default), `major` and `none`. Vertical alignment of cells is controlled by the `valign` option. You can choose from "top", "middle"(default) and "bottom". Be cautious that the vertical alignment option was only introduced in multirow in 2016. If you are using a legacy LaTeX distribution, you will run into trouble if you set `valign` to be either "top" or "bottom".
@@ -450,7 +457,7 @@
)
```
-If you need to add footnote marks in a table, you need to do it manually (no fancy) using `footnote_marker_***()`. Remember that similar with `cell_spec`, you need to tell this function whether you want it to do it in `HTML` (default) or `LaTeX`. You can set it for all using the `knitr.table.format` global option. Also, if you have ever used `footnote_marker_***()`, you need to put `escape = F` in your `kable` function to avoid escaping of special characters. Note that if you want to use these `footnote_marker` functions in `kableExtra` functions like `group_rows` (for the row label) or `add_header_above`, you need to set `double_escape = T` and `escape = F` in those functions. I'm trying to find other ways around. Please let me know if you have a good idea and are willing to contribute.
+If you need to add footnote marks in a table, you need to do it manually (no fancy) using `footnote_marker_***()`. Remember that similar with `cell_spec`, you need to tell this function whether you want it to do it in `HTML` (default) or `LaTeX`. You can set it for all using the `knitr.table.format` global option. Also, if you have ever used `footnote_marker_***()`, you need to put `escape = F` in your `kable` function to avoid escaping of special characters. Note that if you want to use these `footnote_marker` functions in `kableExtra` functions like `pack_rows` (for the row label) or `add_header_above`, you need to set `double_escape = T` and `escape = F` in those functions. I'm trying to find other ways around. Please let me know if you have a good idea and are willing to contribute.
```{r}
dt_footnote <- dt
@@ -492,7 +499,7 @@
col.names = linebreak(c("Item\n(Name)", "Value\n(Number)"), align = "c"))
```
-At the same time, since `kableExtra 0.8.0`, all `kableExtra` functions that have some contents input (such as `footnote` or `group_rows`) will automatically convert `\n` to linebreaks for you in both LaTeX and HTML.
+At the same time, since `kableExtra 0.8.0`, all `kableExtra` functions that have some contents input (such as `footnote` or `pack_rows`) will automatically convert `\n` to linebreaks for you in both LaTeX and HTML.
## Table on a Landscape Page
@@ -505,7 +512,7 @@
"Group 1 contains mpg, cyl and disp",
"Group 2 contains hp, drat and wt"),
notation = "symbol") %>%
- group_rows("Group 1", 4, 5) %>%
+ pack_rows("Group 1", 4, 5) %>%
landscape()
```
diff --git a/vignettes/best_practice_for_newline_in_latex_table.Rmd b/vignettes/best_practice_for_newline_in_latex_table.Rmd
index 5cd5006..f225193 100644
--- a/vignettes/best_practice_for_newline_in_latex_table.Rmd
+++ b/vignettes/best_practice_for_newline_in_latex_table.Rmd
@@ -75,7 +75,7 @@
```
### Linebreak in other kableExtra functions
-If you have a need to put a linebreak in `kableExtra` functions such as `add_header_above` and `group_rows`, just go ahead and use `\n` directly (in kableExtra >= 0.8.0) and it will be automatically converted. Note that this feature is also controlled by the `escape` option in those functions.
+If you have a need to put a linebreak in `kableExtra` functions such as `add_header_above` and `pack_rows`, just go ahead and use `\n` directly (in kableExtra >= 0.8.0) and it will be automatically converted. Note that this feature is also controlled by the `escape` option in those functions.
```{r}
dt2 %>%
@@ -83,6 +83,6 @@
kable("latex", booktabs = T, escape = F,
col.names = linebreak(c("Item\n(Name)", "Value\n(Number)"), align = "c")) %>%
add_header_above(c("Combined\nTitle" = 2)) %>%
- group_rows("Group\n1", 2, 2)
+ pack_rows("Group\n1", 2, 2)
```