tlf-assemble.qmd

# Assemble TLFs {#assemble}

```{r, include=FALSE}
source("_common.R")
```

```{r}
library(r2rtf)
```

After TLFs are created and saved into individual files,
we need to assemble them into one file in a pre-specified order.

There are two general approaches to achieving the goal.

1. Combine RTF source code in individual files into one large RTF file.
1. Leverage the `Toggle Fields` feature in Microsoft Word to embed RTF files using
hyperlinks.

Let's illustrate the idea by using selected TLFs generated from previous chapters.
Here, we assume files are saved in the `tlf/` folder.

```{r}
tlf_path <- c(
  "tlf/tbl_disp.rtf", # Disposition table
  "tlf/tlf_eff.rtf", # Efficacy table
  "tlf/tlf_km.rtf" # K-M plot
)
```

```{r, out.width = "100%", out.height = if (knitr::is_html_output()) "400px", echo = FALSE, fig.align = "center"}
knitr::include_graphics("tlf/rtf-combine.pdf")
```

## Combine RTF Source Code

::: {.callout-note}
The code below requires r2rtf version >= 1.0.0.
:::

The `r2rtf::assemble_rtf()` function allows the user to combine RTF
source code in individual files into one larger RTF file.

::: {.callout-caution}
One limitation of combining RTF source code is that
we are not able to specify the page orientation of each TLF
in the combined document.
:::

```{r}
r2rtf::assemble_rtf(
  input = tlf_path,
  output = "tlf/rtf-combine.rtf"
)
```

## Using Toggle Fields

Microsoft Word uses toggle fields to embed files into one Word document.
The approach is a dynamic link between files by providing the absolute file path.

::: {.callout-tip}
There is a slight learning curve on how toggle fields work
in Microsoft Word.
After you become familiar with the workflow,
toggle fields can extend your capability to manage a large number of TLFs
in RTF format.
:::

The `assemble_docx()` function
allows you to create a `.docx` file with toggle fields as below.
One benefit is to control the page direction of each TLF as below.

```{r}
r2rtf::assemble_docx(
  tlf_path,
  output = "tlf/rtf-combine-toggle.docx",
  landscape = c(FALSE, FALSE, TRUE)
)
```

After opening the generated `.docx` file,
you will see a blank file because the file only contains fields
with hyperlinks.

By using Alt + F9 to display the fields and you will
see information similar to the screenshot below.

```{r, echo=FALSE, out.width="99%", fig.cap="Using Alt + F9 to display fields", fig.align="center"}
knitr::include_graphics("images/rtf-alt-f9.png")
```

::: {.callout-tip}
A typical error message is that system can not find the file
if you only provide a relative path.
Please double-check that the correct absolute file path is in the `INCLUDETEXT` field.
:::

To test the toggle field, you can right-click an `INCLUDETEXT` filed and
click `Update Field`.

If it works, you can see a table similar to the snapshot below
by using Alt + F9.
It is a shortcut to change between results and field display mode.

```{r, echo=FALSE, out.width="99%", fig.cap="Update fields", fig.align="center"}
knitr::include_graphics("images/rtf-after-update.png")
```

Now you can update all toggle fields to display all TLFs by
selecting all fields (Ctrl + A), then press F9.
We suggest testing one toggle field before updating all of them.

As the `.docx` file contain dynamic links,
you can keep updating the TLFs if you need to refresh content in
individual RTF files by selecting all fields (Ctrl + A), then press F9.

::: {.callout-tip}
If you modify table content in the combined `.docx` file,
you may get a weird table layout if you update all fields within a toggle field.
To resolve the issue, please remove all `\* MERGEFORMAT` in the filed mode using Alt + F9 before updating all toggle fields.
:::

After the combined TLF is ready for delivery,
you can also unlink toggle fields to save table contents,
because the absolute path may only work for some.
To unlink toggle fields, you can select all fields (Ctrl + A),
then press Ctrl + Shift + F9.