Custom shortcode or lua filter for conditional evaluation of both titles and code chunks

[joanbadia]

Description

I want to do parametrised analyses modules, which would be conditionally evaluated affecting both titles and chunks, so that the titles aren't printed on the output but are still on the .qmd file for navigation purposes.

I have already tried the combination of :::{.content-hidden when-meta="params.pca"} & {r} #| eval: !expr !expr params$pca without success, specially when working with {{< includes ... >}}.

The following option also is not what I want because it'll make the title not available for navigation:

#| output: asis
cat("\n\n## My second level header\n\n)

Now I am trying to create my own shortcode or lua filter that achieves this purpose.

This is currently my first attempt, any help it'll be welcome:

conditional-evaluation.lua

function Meta(meta)
  modules = meta.params.module or {}  -- Access the 'module' field in YAML
end

function Div(el)
  local module_name = el.attributes['module']
  
  if module_name and modules[module_name] == false then
    return {}  -- Hide content
  end

  return el  -- Otherwise, render content as usual
end

analysis.qmd

---
title: "analysis"
format: 
  html: 
    echo: false
    warning: false
    message: false
params: 
  module: 
    pca: false
editor: visual
---

{{< include module-dimred.qmd >}}

module-dimred.qmd

---
title: ""
format: html
filters:
  - conditional_evaluation.lua
---

::: {module="pca"}
### Principal Component Analysis (PCA)

```{r}
#| eval: !expr params$module$pca

library(ggpubr)
set.seed(123)
pca_results <- prcomp(iris[,1:4], scale. = TRUE)
pca_df <- data.frame(Species=iris$Species, PC1 = pca_results$x[,1], PC2 = pca_results$x[,2])
ggscatter(pca_df, x="PC1",y="PC2", color="Species")
```
:::

[mcanouil]

A Lua filter could avoid the repetition but I just though of the following workaround.
This keep the outline but the title is only displayed conditionally on the parameter.
Would this work for you?

---
title: "Quarto Playground"
format: html
params:
  pca: true
execute:
  echo: false
---

::: {.content-hidden}
### Principal Component Analysis (PCA)
:::

```{r}
#| eval: !expr isTRUE(params[["pca"]])
#| output: asis
cat("\n\n#### Principal Component Analysis (PCA)\n\n")
```

```{r}
#| eval: !expr isTRUE(params[["pca"]])
plot(1)
```

[joanbadia]

This works with the behaviour I intended, but I cannot express enough how practical would be that there's a conditional evaluation at the level of the shortcode, not only for avoiding redundancy (expliciting twice the eval and hiding the title), but because it would be compatible with other shortcodes and for example, I could do a .{panel-tabset} that shows only the panels that were evaluated.

I think one of the strengths of Quarto is the use of shortcodes, which are compatible with the visual editor too, and the amazing things that could be done with a conditional-evaluation, not only a .content-hidden, would be awesome.

I'll try, when I have more time, to implement my own lua filter.

[Steinthal]

I second @joanbadia's request.

If the existing shortcode would be enhanced to support {.content-visible when-meta "<meta-var>[ = <value>]"} (the corresponding "content-hidden" shortcode as well), one could differentiate texts easier than now.

[mcanouil]

To be clear, it's unlikely to happen with the current state of Quarto. params in YAML header is a knitr R specific feature.
Making whatever use that would mean it would only work for one single engine.
So, as long as the "parameters" are not supported in an harmonised/standardised way across engines, I don't believe the team will add engine specific feature to engine agnostic features such as "conditional content".

"metadata" isn't the same thing as "parameters" and will very likely never be.

Also a word of clarification, conditional content feature is not a shortcode. It's a fenced div.
A shortcode is {{< ... >}}.

Finally, when-meta and unless-meta already exist: https://quarto.org/docs/authoring/conditional.html#matching-against-metadata

[Steinthal]

Thanks @mcanouil for the clarification and sorry for using the wrong terminology.

I know that when-meta and unless-metaexist but both just check for trueor false.

I'd like to declare a metadata entry, e.g. "customer". In a document with say 95% of content valid for all customers, 5% is customer specific. Instead of defining a metadata entry for each customer, I'd like to assign the customer value when rendering the document (e. g. with -M customer:"cust 01").

Hence my suggestion to enhance the existing conditional when-meta="<meta-var>" to when-meta "<meta-var>=<value>" (or when-meta="<meta-var>==<value>"?) or maybe create something new like when-meta-equals "<meta-var>" "value>".

This use case might be slightly different from that of the OP but I think it also might serve him. And I'm aware that only parameters can be used for R code chunks.

[mcanouil]

When/unless expects Booleans. It would be very unintuitive if they could get other values.
What would "when-meta='whatever'"?
In my opinion, this would be a bad design choice which would bring more headaches than it would help.

Note that there is also when/unless profile, so you can set different values.

[mcanouil]

Note that you can reply in the thread of the first comment instead of opening a new thread.

[cscheid]

I know that when-meta and unless-metaexist but both just check for trueor false.

This is by design and we want to keep that feature simple on purpose. We're unlikely to change it: the potential for confusion is just too large.

With that said, you should be able to do what you need with an actual Lua filter.

[Steinthal]

I'm no programmer by profession, so I don't know the subtleties of "when", "if", and other conditional statements. And I certainly didn't want to make design choices.

I agree with the OP's statement that "one of the strengths of Quarto is the use of shortcodes, which are compatible with the visual editor too, and the amazing things that could be done with a conditional-evaluation".

But as suggested by cscheid, I'm going to try to familiarize myself with Lua filters.

[joanbadia]

I think it's time to close this topic because I no longer believe a lua filter can affect both code and fenced divs / shortcodes. Lua filters are applied after the code chunks are evaluated, so it wouldn't prevent a code chunk from being evaluated and at much it could hide its content (which is not what I want).

Nonetheless I had good progress in other points:

• I prefer unless-meta than when-meta, as unless-meta evaluates by default as false (when-meta by default is true) if you use non-specified params or empty params (e.g.: when-meta="potato").
• I have one way to specify params now, using a "master" document, so that they correctly pass to their includes. Note: I have tried using a pca: r params$pca in the YAML header but it doesn't work.
• Optional: I found that it's better to specify title as a parameter, because with includes the last .qmd included is the one that decides the title.

I'll copy my final workflow, in case anyone is interested:

master.qmd

---
title: "analysis"
format: 
  html: 
    echo: false
    warning: false
    message: false
    self-contained: true
params: 
  title: "Analysis"
  pca: false
  boxplots: true
execute: 
  echo: false
editor: visual
---

{{< include module-dimred.qmd >}}

{{< include module-boxplots.qmd >}}

module-dimred.qmd

---
title: "`r params$title`"
format: html
---

::: {.content-hidden unless-meta="params.pca"}
### Principal Component Analysis (PCA)
:::

```{r}
#| eval: !expr params$pca
invisible(library(ggpubr))
cat("Doing PCA")
set.seed(123)
pca_results <- prcomp(iris[,1:4], scale. = TRUE)
pca_df <- data.frame(Species=iris$Species, PC1 = pca_results$x[,1], PC2 = pca_results$x[,2])
ggscatter(pca_df, x="PC1",y="PC2", color="Species")
```

module-boxplots.qmd

---
title: "`r params$title`"
format: html
---


::: {.content-hidden unless-meta="params.boxplots"}
### Boxplots
:::

```{r}
#| eval: !expr params$boxplots

invisible(library(ggpubr))
cat("Doing BoxPlots")
ggboxplot(iris, x="Species", y="Sepal.Length", color="Species", fill="Species", alpha=.25)
```

[joanbadia]

This is the attempt I did to try to make it work with quarto render analysis.qmd --execute-params params.yml, but it does NOT work because the params object is not updated when supplied with --execute-params. see: #11167

Careful, this does NOT work!

---
params:
  pca: "`r params$pca`"
---