Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ColinFay/gargoyle

Event-Based Structures for 'Shiny'
https://github.com/ColinFay/gargoyle

golemverse shiny shiny-r

Last synced: 3 months ago
JSON representation

Event-Based Structures for 'Shiny'

Awesome Lists containing this project

README 

        
---

output: github_document

---



```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

```

# gargoyle



[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)

[![R-CMD-check](https://github.com/ColinFay/gargoyle/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ColinFay/gargoyle/actions/workflows/R-CMD-check.yaml)



The goal of gargoyle is to provide an event-based mechanism for `{shiny}`.



## Installation



You can install the dev version of `{gargoyle}` with:



``` r

remotes::install_github("ColinFay/gargoyle")

```



## About



You're reading the doc about version : `r pkgload::pkg_version()`



This README has been compiled on the



```{r}

Sys.time()

```



Here are the test & coverage results :



```{r}

devtools::check(quiet = TRUE)

```



```{r echo = FALSE}

unloadNamespace("shinipsum")

```



```{r}

covr::package_coverage()

```



### What the heck?



`{gargoyle}` is a package that provides wrappers around `{shiny}` to turn your app into and event-based application instead of a full reactive app.

The framework is centered around a `watch` & `trigger` mechanism.



It works with classical UI, and just needs tweaking the server side of your app.



`{shiny}`'s default reactive behavior is very helpful when it comes to building small applications.

Because, you know, the good thing about reactivity is that when something moves somewhere, it's updated everywhere.

But the bad thing about reactivity is that when something moves somewhere, it's updated everywhere.

So it does work pretty well on small apps, but can get very complicated on bigger apps, and can quickly get out of hands.



That's where `{gargoyle}` comes into play: it provides an event based paradigm for building your apps, so that reactivity happens under a controlled flow.



### For whom?



If you're just building small `{shiny}` apps you're probably good with `{shiny}` default reactive behavior.

But if ever you've struggled with reactivity in larger apps you might find `{gargoyle}` useful: only invalidate contexts when you want and make the general flow of your app more predictable!



### The trade-off



`{gargoyle}` will be more verbose and will demand more work upfront to make things happen.

I believe this is for the best if you're working on a big project: from the very beginning 

it forces the user to think more carefully about app design and the reactive flow.



## Design pattern



`{gargoyle}` has:



+ `init`, `watch` & `trigger`, which allow to initiate, watch, and trigger an event



+ `on`, that runs the `expr` when the event is triggered



`gargoyle::trigger()` can print messages to the console using `options("gargoyle.talkative" = TRUE)`.



## Example



```{r eval = FALSE}

library(shiny)

library(gargoyle)

options("gargoyle.talkative" = TRUE)

ui <- function(request){

  tagList(

    h4('Go'),

    actionButton("y", "y"),

    h4('Output of z$v'),

    tableOutput("evt")

  )

}



server <- function(input, output, session){



  # Initiating the flags

  init("airquality", "iris", "renderiris")



  # Creating a new env to store values, instead of

  # a reactive structure

  z <- new.env()



  observeEvent(input$y , {

    z$v <- mtcars

    # Triggering the flag

    trigger("airquality")

  })



  on("airquality", {

    # Triggering the flag

    z$v <- airquality

    trigger("iris")

  })



  on("iris", {

    # Triggering the flag

    z$v <- iris

    trigger("renderiris")

  })



  output$evt <- renderTable({

    # This part will only render when the renderiris

    # flag is triggered

    watch("renderiris")

    head(z$v)

  })



}



shinyApp(ui, server)

```



You can then get & clear the logs of the times the triggers were called:



```{r eval = FALSE}

get_gargoyle_logs()

clear_gargoyle_logs()

```







## Code of Conduct



Please note that the gargoyle project is released with a [Contributor Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct/). By contributing to this project, you agree to abide by its terms.