Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/devOpifex/component

📄 Components for Shiny
https://github.com/devOpifex/component

Last synced: 3 months ago
JSON representation

📄 Components for Shiny

Awesome Lists containing this project

README 

        



# component



Creating components for [shiny](https://shiny.rstudio.com) inspired by [Vue](https://vuejs.org/)






It tackles three "issues" with Shiny modules:



1. Generating scoped (namespaced) CSS and JavaScript code.

2. Places all the code for a module in a single file.

3. Binds CSS, and JavaScript of a module to it



This is inspired from Vue where one defines a component in a single file.



```vue



import { ref } from 'vue'

const count = ref(0)



  Count is: {{ count }}



button {

  font-weight: bold;

}



```



Where the file includes the style, script, and template.

We reproduce the same with R with the addition of the server component.



## Installation



You can install the development version of component from [GitHub](https://github.com/) with:



``` r

# install.packages("remotes")

remotes::install_github("devOpifex/component")

```



## Create



From a package (see [lerprechaun](https://leprechaun.opifex.org) or 

[golem](https://thinkr-open.github.io/golem/)), create a component.



``` r

# create a component

# give it a name

component::create("test")

```



This creates a new file in `R/` named `component-test.R`.



Components generate code via `devtools::document()` (more on that later)

add the roxygen2 roclet to your `DESCRIPTION`, e.g.:



```

Roxygen: list(markdown = TRUE, roclets = c("collate", "namespace", "rd", "component::roclet_component"))

```



So `create()` creates the component file but `devtools::document()` generates 

the usable version of the component.



```r

component::create() => `component-.R` => devtools::document() => `component-generated-.R`

```



## Component Anatomy



The default component as created by `component::create()` looks something like the code below

(`R/component-test.R`).



```r

#' @component test

NULL



#' test javascript

#' 

#' test javascript component.

#' 

#' @param ... Any other argument.

#' 

#' @keywords internal

.test_javascript <- \(...) {

    "$('{{class red}}').on('mouseenter', (e) => {

        $(e.target).toggleClass('{{ns red}}');

    })"

}



#' test css

#' 

#' test css component.

#' 

#' @param ... Any other argument.

#' 

#' @keywords internal

.test_css <- \(...) {

  c(

    "{{class red}}{color:red;}",

    "h1{font-weight: bold;}"

  )

}



#' test ui

#' 

#' test UI component.

#' 

#' @param ns Shiny's namespace function.

#' @param ... Any other argument.

#' 

#' @keywords internal

.test_ui <- \(ns, ...) {

  shiny::div(

    shiny::h1("Component", class = ns("red")),

    plotOutput(ns("plot"))

  )

}



#' test server

#' 

#' test server component.

#' 

#' @param input,output,session Arguments passed from mdoule's server.

#' @param ... Any other argument.

#' 

#' @keywords internal

.test_server <- \(input, output, session, ...) {

  output$plot <- shiny::renderPlot(plot(stats::runif(200)))

}

```



### Component tag



The `@component` tag indicates the name of the component,

in this example `test`.

This tells component which functions to scan for:



- `._javascript`

- `._css`

- `._server`

- `._ui`



### JavaScript and CSS



The `.test_javascript` and `.test_css` functions are used to generate

scoped code.



- `class`: transforms `{{ class red }}` into `.namespace-red`

- `id`: transforms `{{ id red }}` into `#namespace-red`

- `ns`: transforms `{{ ns red }}` into `namespace-red`

- `json`: transforms `{{ json letters[1:2] }}` into `['a', 'b']`

- You may still use `{{ x }}` in which case it will evaluate `x` 

(passed `*ui` or `*server` function).



These functions should return a character vector of length one or more.



The CSS is minified using [sass](https://github.com/rstudio/sass/), if you have 

[uglifyjs](https://www.npmjs.com/package/uglify-js) installed

it is used to minify the JavaScript otherwise it is not

(install it with `npm install uglify-js -g`).



### UI and Server



Almost identical to the UI and server functions of a shiny module



### How to use



The created template __cannot__ be used as-is, by documenting the code with 

`devtools::document()` we create  a new file (`R/component-generated-.R`)

which contains:



- `_ui`

- `_server`



In this example, `test_ui`, and `server_ui`.



These are the functions that one should use in the application.

Always work on/edit the functions starting with a dot (e.g.: `.test_ui`),

as the generated files get regenerated at every `devtools::document()` call.



Example based on the abose "test" component, after running `devtools::document()`.



```r

library(shiny)



ui <- fluidPage(

    title = "Test",

    test_ui("test")

)



server <- function(...){

    test_server("test")

}



shinyApp(ui, server)

```



## Example



Here is the classic counter example but scoped and using JavaScript only.



```r

#' @component counter

NULL



#' counter javascript

#' 

#' counter javascript component.

#' 

#' @param ... Any other argument.

#' 

#' @keywords internal

.counter_javascript <- \(...) {

  "$(() => {

    let index = 0;

    $('{{id button}}').on('click', (e) => {

      index++;

      $('{{id output}}').html(index);

      $('{{id output}}').toggleClass('{{ns criminal}}');

    })

  })"

}



#' counter css

#' 

#' counter css component.

#' 

#' @param ... Any other argument.

#' 

#' @keywords internal

.counter_css <- \(...) {

  "{{class criminal}}{

    color: {{color}};

    font-weight: bold;

  }"

}



#' counter ui

#' 

#' counter UI component.

#' 

#' @param ns Shiny's namespace function.

#' @param ... Any other argument.

#' 

#' @keywords internal

.counter_ui <- \(ns, ...) {

  shiny::div(

    shiny::h1("Counter"),

    shiny::tags$button(

      class = "btn btn-sm btn-primary",

      id = ns("button"),

      "Counter"

    ),

    shiny::p(

      id = ns("output"), 

      0L

    )

  )

}



#' counter server

#' 

#' counter server component.

#' 

#' @param input,output,session Arguments passed from mdoule's server.

#' @param ... Any other argument.

#' 

#' @keywords internal

.counter_server <- \(input, output, session, ...) {}

```



Then, after documenting, it can be used as.



```r

library(shiny)



ui <- fluidPage(

    title = "Test",

    counter_ui("c1", color = "red"),

    counter_ui("c2", color = "blue"),

)



server <- function(...){

    counter_server("c1")

    counter_server("c2")

}



shinyApp(ui, server)

```