A component's argument given v_bind() or v_model() in place of a
value follows state on the page, in the browser, with no round trip to
the server – as :size="size" and v-model="open" do in a Vue
template. The page's UI state stays in the browser; the server keeps
the data and the decisions.
Arguments
- expr
One Vue expression, a string: over
$vueStore,$inputs,$route, and in a template the component's own names.- ns
In a module, its namespace: the function
shiny::NS()gives,session$ns, or the module's id.- path
A store's field,
$vueStore.<id>.<field>, going on with.<name>,['<name>']or[<index>].- arg
In a template, the model's argument, as
v-model:titlewrites it:"title". A named attribute gives it too:title = v_model("t").- modifiers
Vue's modifiers, as
v-model.trim.lazywrites them:c("trim", "lazy").
Details
v_bind(expr)is one way, asv-bind(:prop="expr"): the argument follows the expression, any JavaScript expression –v_bind("$inputs.fold === 'collapse'").v_model(path)is both ways, asv-model: the argument follows a store's field, and when the component's user changes it – a dialog closed, a value picked – the field is set, so everything bound to it follows. The path is one a value can be assigned to:v_model("$vueStore.ui.open").
Each component is a Vue application of its own, so an expression sees the page, not another component's variables: the names it can use are
$vueStore.<id>: avue_store(), its state and getters;$inputs.<id>: the value a component reports asinput$<id>, as its component reports it (before any debounce, before an input handler converts it);$route: the route of the page'svue_router()–$route.path,$route.params.id.
Given a bound argument, update_*() sets the field; with v_model()
that sets the store too, so everything bound to it follows; with
v_bind() the field keeps the update until the expression changes.
v_bind() on a component's value makes it controlled: it starts from
and follows the expression, and its user's change stays the
component's until the expression changes. With Shiny on the page the
component reports input$<id> as ever, so the server sees what the
page did.
What can be bound: any of a component's props and its value, and what a
dialog's, drawer's, tabs' or collapse's update_*() can set. An
argument R reads to draw the component – a label, a class, whether
options are buttons – says it cannot be bound.
A bound value reaches the component as it is, as upstream's
:prop="value": functions, Dates and components (an icon) included.
Data R converts – a select's choices, a mention's options – has two
rules, as DT's JS(): an R value is given in R's terms (a named vector)
and converted; a v_bind() gives the library's own form, [{ value, label }], as its docs write it, and is not converted. Vue's development build
(the page's dev = TRUE) says when a bound list is not records.
A binding the page cannot read – a store it does not have, $route
with no vue_router(), a path that runs through nothing – leaves its
field unset and says so once in the browser's console, naming what is
missing. A field a store simply does not have reads as undefined, as
JavaScript does: that one is not said.
What expr is
One string, the Vue expression written between
the quotes of :prop="..." – as every v_*() takes one, v_if()'s
as v-if's. v_bind("$vueStore.ui.size") is :size="$vueStore.ui.size";
v_bind("large") reads a name large, and the text is
v_bind("'large'"), as :size="'large'"; v_bind("1") the number,
as :min="1". A JS() is a string too, and so is
jsonlite::toJSON()'s result, a JavaScript literal: R's data in a
raw template is v_bind(jsonlite::toJSON(df)) (with
auto_unbox = TRUE for a single value).
A constant needs no binding: an argument takes the R value itself,
size = "large", as Shiny's do. Anything but a string – a number,
a list, NULL, NA, I() – is an error saying what to write, as
htmlwidgets' JS() takes strings only.
Modules
Give ns, the module's shiny::NS() or its id, and
the expression is left as written while its names are the module's:
$inputs.size is input$size of the module, $vueStore.ui the store
made with vue_store(ns("ui")) – as input$size is inside
shiny::moduleServer(). Without ns, the names are the page's, and a
store named the same in two instances of a module is one store.
See also
v_on() for acting in the browser; vue_store() for state
shared by components.
Examples
# A size picked in one component, followed by another
htmltools::tagList(
vue_app(
"size",
htmltools::tags$select(
`v-model` = "size",
htmltools::tags$option("small"),
htmltools::tags$option("large")
),
data = list(size = "small"),
input = "size"
),
vue_app(
"shown",
htmltools::tags$span("Large: {{ large }}"),
data = list(large = v_bind("$inputs.size === 'large'"))
)
)
#> <div id="size" data-shiny-vue style="display: contents">
#> <script type="text/x-template" data-shiny-vue-template><select v-model="size">
#> <option>small</option>
#> <option>large</option>
#> </select></script>
#> <script type="application/json" data-shiny-vue-options>{"options":{"data":{"size":"small"}},"input":"size","evals":[]}</script>
#> </div>
#> <div id="shown" data-shiny-vue style="display: contents">
#> <script type="text/x-template" data-shiny-vue-template><span>Large: {{ large }}</span></script>
#> <script type="application/json" data-shiny-vue-options>{"options":{"data":{"large":null}},"bound":{"large":{"expr":"$inputs.size === 'large'"}},"evals":[]}</script>
#> </div>
# A store, set by one and followed by another
htmltools::tagList(
vue_store("ui", state = list(open = FALSE)),
vue_app(
"toggle",
htmltools::tags$button(`@click` = "open = !open", "Toggle"),
data = list(open = v_model("$vueStore.ui.open"))
),
vue_app("state", htmltools::tags$span("{{ $vueStore.ui.open }}"))
)
#> <div id="ui" data-shiny-vue style="display: contents">
#> <script type="text/x-template" data-shiny-vue-template><span hidden></span></script>
#> <script type="application/json" data-shiny-vue-options>{"options":{"data":{"open":false}},"store":true,"evals":[]}</script>
#> </div>
#> <div id="toggle" data-shiny-vue style="display: contents">
#> <script type="text/x-template" data-shiny-vue-template><button @click="open = !open">Toggle</button></script>
#> <script type="application/json" data-shiny-vue-options>{"options":{"data":{"open":null}},"bound":{"open":{"expr":"$vueStore.ui.open","model":true}},"evals":[]}</script>
#> </div>
#> <div id="state" data-shiny-vue style="display: contents">
#> <script type="text/x-template" data-shiny-vue-template><span>{{ $vueStore.ui.open }}</span></script>
#> <script type="application/json" data-shiny-vue-options>{"options":{"data":[]},"evals":[]}</script>
#> </div>
# In a module: the module's input and store
panel_ui <- function(id) {
ns <- shiny::NS(id)
htmltools::tagList(
vue_store(ns("ui"), state = list(open = FALSE)),
vue_app(
ns("shown"),
htmltools::tags$span("{{ open }}"),
data = list(open = v_bind("$vueStore.ui.open", ns = ns))
)
)
}