Skip to content

Commit 6229863

Browse files
utecoatless
ute
and
coatless
authored
Global cell defaults (#173)
* Add yaml-key for cell defaults Allow user to define code cell defaults in yaml * user defined editor font size Add a cell option for editor-font-size. You might perhaps want a different name? * Add an example * Remove font change from this PR as we're wanting to just focus on global settings. * Bump extension version * Re-write simple example to focus on the global feature * Switch to using `cell-defaults` in lua filter * Add a test case file * Add release note * Add documentation on the key * Switch from `cell-defaults` to `cell-options` * Switch from `cell-defaults` to `cell-options` --------- Co-authored-by: James J Balamuta <[email protected]>
1 parent 8c4cb89 commit 6229863

7 files changed

+177
-2
lines changed

‎_extensions/webr/_extension.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name: webr
22
title: Embedded webr code cells
33
author: James Joseph Balamuta
4-
version: 0.4.1
4+
version: 0.4.2-dev.1
55
quarto-required: ">=1.2.198"
66
contributes:
77
filters:

‎_extensions/webr/webr.lua

+8
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,14 @@ function setWebRInitializationOptions(meta)
170170
return meta
171171
end
172172

173+
-- Allow modification of code cells global defaults
174+
if isVariablePopulated(webr["cell-options"]) then
175+
for index, value in pairs(webr["cell-options"]) do
176+
qwebRDefaultCellOptions[index] = pandoc.utils.stringify(value)
177+
end
178+
end
179+
180+
173181
-- The base URL used for downloading R WebAssembly binaries
174182
-- https://webr.r-wasm.org/[version]/webr.mjs
175183
-- Documentation:

‎docs/demos/qwebr-feature-demos.qmd

+1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ title: "Feature Demonstrations"
44

55
Below is a list of different demonstrations of the extensions features. These demos were created to showcase different feature releases.
66

7+
- [Set Global Cell Options](qwebr-global-cell-defaults.qmd)
78
- [Read-only Interactive Code Cells](qwebr-read-only.qmd)
89
- [Autorun Interactive Code Cells](qwebr-auto-run.qmd)
910
- [Initial Code Cell Option Support](qwebr-code-cell-options.qmd)

‎docs/demos/qwebr-global-cell-defaults.qmd

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: "Demo: Set Global Cell Options"
3+
engine: knitr
4+
webr:
5+
cell-options:
6+
out-width: "100%"
7+
autorun: true
8+
read-only: true
9+
filters:
10+
- webr
11+
---
12+
13+
:::{.callout-important}
14+
This feature is currently experimental and is included in 0.4.2-dev.1 build of `{quarto-webr}`.
15+
:::
16+
17+
# Overview
18+
19+
This demo illustrates how to set cell-level options for the entire document by specifying them in the document header. Once established, these options govern the behavior and appearance of `{webr-r}` code cells. However, they can be overridden locally by specifying cell options within individual `{webr-r}` cells.
20+
21+
## `cell-options` Document Key
22+
23+
To establish default cell behavior, you can utilize the `cell-options` subkey in `webr`. For instance, consider the following structure:
24+
25+
```yaml
26+
webr:
27+
cell-options:
28+
<cell-option>: <value>
29+
```
30+
31+
Here, `<cell-option>` and `<value>` represent one of the [supported cell options](../qwebr-cell-options.qmd).
32+
33+
## Restricting Access
34+
35+
An example use case is to prevent modifications to interactive code cells while ensuring their content is executed. In this document, we've defined the global behavior with:
36+
37+
```md
38+
---
39+
title: "Demo: Set Global Cell Options"
40+
engine: knitr
41+
webr:
42+
cell-options:
43+
out-width: "100%"
44+
autorun: true
45+
read-only: true
46+
filters:
47+
- webr
48+
---
49+
```
50+
51+
Let's observe the outcome with a cell like this:
52+
53+
::: {.panel-tabset group="language"}
54+
#### `{quarto-webr}` Output
55+
```{webr-r}
56+
fit = lm(mpg ~ am, data = mtcars)
57+
summary(fit)
58+
```
59+
#### Cell Code
60+
````md
61+
```{webr-r}
62+
fit = lm(mpg ~ am, data = mtcars)
63+
summary(fit)
64+
```
65+
````
66+
:::
67+
68+
Attempting to modify the cell will be ineffective. However, in the subsequent cell, we've specified a local option that overrides the document's default, allowing modification. Feel free to try modifying the cell below.
69+
70+
::: {.panel-tabset group="language"}
71+
#### `{quarto-webr}` Output
72+
```{webr-r}
73+
#| read-only: false
74+
plot(fit)
75+
```
76+
#### Cell Code
77+
````md
78+
```{webr-r}
79+
#| read-only: false
80+
plot(fit)
81+
```
82+
````
83+
:::
84+
85+
# Conclusion
86+
87+
This approach eliminates the need to repeatedly specify options across multiple cells within the document, consolidating them in a single location. Should the need arise, you can always override the behavior by specifying a local value for the cell.

‎docs/qwebr-meta-options.qmd

+22-1
Original file line numberDiff line numberDiff line change
@@ -106,27 +106,48 @@ The extension also provides native options that affect its behavior:
106106

107107
- **Description**: Controls the display of the WebR initialization state in the document header.
108108
- **Default Value**: `true`
109+
- **Demo Document**: [Setting Options in Document Header](demos/qwebr-setting-options-in-document-yaml.qmd)
109110

110111
### `show-header-message`
111112

112113
- **Description**: Determines whether COOP and COEP headers are in use for faster page loads.
113114
- **Default Value**: `false`
115+
- **Demo Document**: [Setting Options in Document Header](demos/qwebr-setting-options-in-document-yaml.qmd)
116+
117+
### `cell-options`
118+
119+
- **Description**: Modifies default cell options for `{webr-r}` cells.
120+
- **Default Value**: Please see [Code Cell Options](qwebr-cell-options.qmd) for individual cell option defaults.
121+
- **Demo Document**: [Set Global Cell Options](demos/qwebr-global-cell-defaults.qmd)
122+
- **Example:**
123+
124+
```yaml
125+
webr:
126+
cell-options:
127+
autorun: true
128+
fig-height: 400
129+
fig-width: 300
130+
```
131+
132+
This modifies the default cell options for `autorun`, `fig-width`, and `fig-height` for all cells in the document.
114133

115134
### `repos`
116135

117136
- **Description**: Specify the repository locations to search for R packages when trying to install them in array form. Regardless of values specified, we will always conclude by checking to see if the package is present in the main webR repository: <https://repo.r-wasm.org/>.
118137
- **Default Value**: `['https://repo.r-wasm.org/']`
138+
- **Demo Document**: [Custom R WASM Package Repository](demos/qwebr-custom-repository.qmd)
119139
- **Example**: `['https://username.r-universe.dev', 'https://username.github.io/reponame']` will cause webR to first look for the package on `r-universe.dev`, then move to looking at the package on GitHub Pages, before finally landing on the official repository.
120140

121-
122141
### `packages`
123142

124143
- **Description**: Specifies R packages to install automatically when the document opens.
125144
- **Default Value**: `[]`
145+
- **Demo Document**: [Setting Options in Document Header](demos/qwebr-setting-options-in-document-yaml.qmd)
126146
- **Example:** `['ggplot2', 'dplyr']` will cause `ggplot2` and `dplyr` to be installed.
127147

128148
### `autoload-packages`
129149

130150
- **Description**: The `autoload-packages` option allows you to control whether R packages specified in the `packages` document option will be automatically loaded using `library()` calls when the document opens. By default, this option is set to `true`, meaning that packages listed in the `packages` option will be automatically loaded. If you set it to `false`, you will need to include a code cell with `library(package)` function calls for each package in `packages`.
131151
- **Default Value**: `true`
152+
- **Demo Document**: [Setting Options in Document Header](demos/qwebr-setting-options-in-document-yaml.qmd)
132153

‎docs/qwebr-release-notes.qmd

+14
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,20 @@ format:
88
toc: true
99
---
1010

11+
# 0.4.2-dev.1: ??????? (??-??-??)
12+
13+
:::{.callout-note}
14+
Features listed under the `-dev` version have not yet been solidified and may change at any point.
15+
:::
16+
17+
## Features
18+
19+
- Added `cell-options` document-level option to specify global defaults for `{webr-r}` options ([#173](https://github.com/coatless/quarto-webr/pulls/173), thanks [ute](https://github.com/ute)!)
20+
21+
## Bug fixes
22+
23+
## Documentation
24+
1125
# 0.4.1: Vivid Montage (03-25-2024)
1226

1327
## Features

‎tests/qwebr-test-global-cell-options.qmd

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: "Test: Setting Global Cell Options"
3+
format: html
4+
engine: knitr
5+
webr:
6+
cell-options:
7+
comment: "## "
8+
autorun: true
9+
filters:
10+
- webr
11+
---
12+
13+
Check that the global options array is correctly parsed and that local values of the cell can still override a global option.
14+
15+
## Interactive
16+
17+
### Global
18+
```{webr-r}
19+
print("test")
20+
```
21+
22+
### Local
23+
24+
```{webr-r}
25+
#| comment: ""
26+
print("test")
27+
```
28+
29+
30+
## Non-interactive
31+
32+
### Global
33+
```{webr-r}
34+
#| context: output
35+
print("test")
36+
```
37+
38+
### Local
39+
40+
```{webr-r}
41+
#| context: output
42+
#| comment: ""
43+
print("test")
44+
```

0 commit comments

Comments
 (0)