---
title: "Communication"
format: html
editor: visual

vignette: >
  %\VignetteIndexEntry{Communication}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

## Introduction

Basically, communication **to** the module server relies on the server function arguments and UI-Server interactions, while communication **from** the module server (to its parent) relies on the server function return value(s).

::: callout-note
The framework communication strategy has been implemented based on the research & exploration work captured in this eBook: [Communication between shiny modules](https://thekangaroofactory.github.io/communication-between-shiny-modules/){target="_blank"}.
:::

## UI-Server

When you implement the package widgets into your app UI, the communication from and to the widgets will be automatically handled by the module server.

- capture user actions (click on the buttons, in table selection)
- detect whether date filter is implemented and if so listen to strategy or date range modification
- update the item table when necessary.

## Arguments

Among the arguments that can be passed to the module server function to tune its internal behaviors are the reactive parameters named `trigger` & `filter` that behave like event managers.

Whenever they receive a reactive object **reference** as input value, the module will take a dependency on it and declare an observer to react to specific events for the module to execute dedicated actions on the items.

- `trigger` is used to pass create / update / delete actions
- `filter` is used to set / unset filters

Reactive arguments are key features for the module to be used within advanced [implementations](./implementations.html).

## Return value(s)

The module server function returns a list of elements that are accessible outside the module.

Among these elements are reactive object's **references** that are used as communication objects. You can take a dependency / listen to those objects to trigger further actions in your app.

A typical example is a plot that will be updated as soon as the items are modified.

``` r
# -- call the module server
mydata <- kitems::kitems(id = "my_data")

# -- plot
output$plot <- renderPlot({
  
  # -- do something here
  
}) |> bindEvent(mydata$items())
```

## Considerations

The magic with passing **references** is that the value itself is not copied or duplicated.[^1]

[^1]: See *Advanced R* <https://adv-r.hadley.nz/names-values.html#names-values>

All the reactive objects of the return value are created with the `shiny::reactive()` function, so that it is not possible to update them from outside of the module server function.

It makes the framework more robust against data model or *item* corruption.

It also allows to use the exported functions of the package from outside of the module server, which provides more flexible implementation options.

## Useful links

- Scenarios & use cases – [implementations](./implementations.html)
- Module server function – `kitems()`
- Arguments & return value(s) – [shiny-module](./shiny-module.html)
- Item workflows – [workflows](./workflows.html)