Merge pull request #391 from blockr-org/389-doc-update

389 doc update

.Rbuildignore

@@ -23,5 +23,6 @@ webpack.prod.js
 ^\.eslintrc\.js$
 ^CODEOWNERS$
 ^index\.md$
+^index\.Rmd$
 ^wiki
 ^\.vscode$

.gitignore

@@ -5,3 +5,5 @@ node_modules
 docs
 inst/doc
 wiki
+
+/.quarto/

NAMESPACE

@@ -159,6 +159,7 @@ export(from_json)
 export(generate_code)
 export(generate_server)
 export(generate_ui)
+export(get_field_name)
 export(get_stack_name)
 export(get_stack_title)
 export(get_workspace)

NEWS.md

@@ -1,7 +1,11 @@
 # blockr 0.0.2.9000
 
-## Fixes
+## Doc
+- Improved `registry` and `getting started` vignettes.
+- Add new `case studies` vignette to present blockr in various contexts.
+- Refine GitHub readme.
 
+## Fixes
 - Loading spinner is now correctly hidden when the block visual is updated.
 
 # blockr 0.0.2

R/field-core.R

@@ -280,6 +280,10 @@ get_sub_fields <- function(x) get_field_value(x, "sub_fields")
 
 set_sub_fields <- function(x, val) set_field_value(x, val, "sub_fields")
 
+#' @export
+#' @rdname update_field
+#' @param field Field element.
+#' @param name To pass a name if no title attribute.
 get_field_name <- function(field, name = "") {
   title <- attr(field, "title")
 

README.Rmd

@@ -9,12 +9,12 @@ always_allow_html: true
 knitr::opts_chunk$set(
   collapse = TRUE,
   comment = "#>",
-  fig.path = "man/figures/README-",
-  out.width = "100%"
+  fig.path = "man/figures/README-"
 )
 
 library(blockr)
 library(bslib)
+library(DiagrammeR)
 ```
 
 # blockr
@@ -24,31 +24,124 @@ library(bslib)
 [![codecov](https://codecov.io/github/blockr-org/blockr/graph/badge.svg?token=9AO88LK8FJ)](https://codecov.io/github/blockr-org/blockr)
 <!-- badges: end -->
 
-Building blocks for data manipulation and visualization operations.
+> {blockr} is Shiny's WordPress (John Coene, 2024)
+
+## Why blockr?
+
+`{blockr}` is an R package designed to democratize data analysis by providing a flexible, intuitive, and __code-free__ approach to building data pipelines. It allows users to create __powerful__ data workflows using pre-built __blocks__ that can be easily __connected__, all without writing a single line of code.
+
+```{r, echo=FALSE, eval=TRUE, message=FALSE}
+mermaid("
+  flowchart TD
+  subgraph LR workspace[Workspace]
+    subgraph stack1[Stack]
+      direction LR
+      subgraph input_block[Block 1]
+        input(Data: dataset, browser, ...)
+      end
+      subgraph transform_block[Block 2]
+        transform(Transform block: filter, select ...)
+      end
+      subgraph output_block[Block 3]
+        output(Result/transform: plot, filter, ...)
+      end
+      input_block --> |data| transform_block --> |data| output_block
+    end
+    subgraph stack2[Stack 2]
+      stack1_data[Stack 1 data] --> |data| transform2[Transform]
+    end
+    stack1 --> |data| stack2
+    subgraph stackn[Stack n]
+      stacki_data[Stack i data] --> |data| transformn[Transform] --> |data| Visualize
+    end
+    stack2 ---> |... data| stackn
+  end
+  ",
+  width = "100%"
+) |>
+  htmlwidgets::onRender(
+    "function(el, x) {
+      el.classList.add('text-center')
+    }
+    "
+  )
+```
 
-`{blockr}` has been built for webR (wasm) and is available for download with 
-`webr::install("blockr", repos = c("https://blockr-org.github.io/webr-repos", "https://repo.r-wasm.org"))`.
+To get started, we invite you to read this [vignette](https://blockr-org.github.io/blockr/articles/blockr.html).
 
-```r
-library(blockr)
-library(blockr.data)
+To get a better idea of `{blockr}` capabilities in various data context, you can look at this [vignette](https://blockr-org.github.io/blockr/articles/blockr_examples.html).
 
-data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+## Key features
 
-stack <- new_stack(
-  data_block,
-  new_select_block
-)
-serve_stack(stack)
-```
+1. **User-Friendly Interface**: Build data pipelines with intuitive interface.
+2. **Flexibility**: Easily add, remove, or rearrange blocks in your pipeline.
+3. **Extensibility**: Developers can create custom blocks to extend functionality.
+4. **Reproducibility**: Pipelines created with `blockr` are easily shareable and reproducible, with exportable code.
+5. **Interactivity**: Real-time feedback as you build and modify your pipeline.
 
 ## Installation
 
 You can install the development version of blockr from [GitHub](https://github.com/) with:
 
 ```r
-# install.packages("devtools")
-pak::pkg_install("blockr-org/blockr")
+pak::pak("blockr-org/blockr")
+```
+
+## Example: palmer penguins case study
+
+Below is a simple case study involving `{blockr}`. We use the palmerpenguins dataset to find out which
+femal species has the largest flippers. We create 2 custom blocks allowing to create our plot block (see the plot vignette for more details). Note that the `{blockr.ggplot2}` package exposes some ready to use blocks.
+
+```{r, eval=FALSE}
+library(blockr)
+library(palmerpenguins)
+library(ggplot2)
+
+new_ggplot_block <- function(col_x = character(), col_y = character(), ...) {
+
+  data_cols <- function(data) colnames(data)
+
+  new_block(
+    fields = list(
+      x = new_select_field(col_x, data_cols, type = "name"),
+      y = new_select_field(col_y, data_cols, type = "name")
+    ),
+    expr = quote(
+      ggplot(mapping = aes(x = .(x), y = .(y)))
+    ),
+    class = c("ggplot_block", "plot_block"),
+    ...
+  )
+}
+
+new_geompoint_block <- function(color = character(), shape = character(), ...) {
+
+  data_cols <- function(data) colnames(data$data)
+
+  new_block(
+    fields = list(
+      color = new_select_field(color, data_cols, type = "name"),
+      shape = new_select_field(shape, data_cols, type = "name")
+    ),
+    expr = quote(
+      geom_point(aes(color = .(color), shape = .(shape)), size = 2)
+    ),
+    class = c("plot_layer_block", "plot_block"),
+    ...
+  )
+}
+
+stack <- new_stack(
+  data_block = new_dataset_block("penguins", "palmerpenguins"),
+  filter_block = new_filter_block("sex", "female"),
+  plot_block = new_ggplot_block("flipper_length_mm", "body_mass_g"),
+  layer_block = new_geompoint_block("species", "species")
+)
+serve_stack(stack)
+```
+
+```{r blockr-penguins-stack, echo=FALSE, fig.cap='Penguins app demo', fig.align = 'center', out.width='100%'}
+knitr::include_graphics("vignettes/figures/blockr-penguins-stack.png")
 ```
 
 ## Contribute

README.md

@@ -9,34 +9,111 @@
 [![codecov](https://codecov.io/github/blockr-org/blockr/graph/badge.svg?token=9AO88LK8FJ)](https://codecov.io/github/blockr-org/blockr)
 <!-- badges: end -->
 
-Building blocks for data manipulation and visualization operations.
+> {blockr} is Shiny’s WordPress (John Coene, 2024)
 
-`{blockr}` has been built for webR (wasm) and is available for download
-with
-`webr::install("blockr", repos = c("https://blockr-org.github.io/webr-repos", "https://repo.r-wasm.org"))`.
+## Why blockr?
+
+`{blockr}` is an R package designed to democratize data analysis by
+providing a flexible, intuitive, and **code-free** approach to building
+data pipelines. It allows users to create **powerful** data workflows
+using pre-built **blocks** that can be easily **connected**, all without
+writing a single line of code.
+
+![](man/figures/README-unnamed-chunk-2-1.png)<!-- -->
+
+To get started, we invite you to read this
+[vignette](https://blockr-org.github.io/blockr/articles/blockr.html).
+
+To get a better idea of `{blockr}` capabilities in various data context,
+you can look at this
+[vignette](https://blockr-org.github.io/blockr/articles/blockr_examples.html).
+
+## Key features
+
+1.  **User-Friendly Interface**: Build data pipelines with intuitive
+    interface.
+2.  **Flexibility**: Easily add, remove, or rearrange blocks in your
+    pipeline.
+3.  **Extensibility**: Developers can create custom blocks to extend
+    functionality.
+4.  **Reproducibility**: Pipelines created with `blockr` are easily
+    shareable and reproducible, with exportable code.
+5.  **Interactivity**: Real-time feedback as you build and modify your
+    pipeline.
+
+## Installation
+
+You can install the development version of blockr from
+[GitHub](https://github.com/) with:
+
+``` r
+pak::pak("blockr-org/blockr")
+```
+
+## Example: palmer penguins case study
+
+Below is a simple case study involving `{blockr}`. We use the
+palmerpenguins dataset to find out which femal species has the largest
+flippers. We create 2 custom blocks allowing to create our plot block
+(see the plot vignette for more details). Note that the
+`{blockr.ggplot2}` package exposes some ready to use blocks.
 
 ``` r
 library(blockr)
-library(blockr.data)
+library(palmerpenguins)
+library(ggplot2)
+
+new_ggplot_block <- function(col_x = character(), col_y = character(), ...) {
+
+  data_cols <- function(data) colnames(data)
+
+  new_block(
+    fields = list(
+      x = new_select_field(col_x, data_cols, type = "name"),
+      y = new_select_field(col_y, data_cols, type = "name")
+    ),
+    expr = quote(
+      ggplot(mapping = aes(x = .(x), y = .(y)))
+    ),
+    class = c("ggplot_block", "plot_block"),
+    ...
+  )
+}
+
+new_geompoint_block <- function(color = character(), shape = character(), ...) {
 
-data_block <- new_dataset_block(selected = "lab", package = "blockr.data")
+  data_cols <- function(data) colnames(data$data)
+
+  new_block(
+    fields = list(
+      color = new_select_field(color, data_cols, type = "name"),
+      shape = new_select_field(shape, data_cols, type = "name")
+    ),
+    expr = quote(
+      geom_point(aes(color = .(color), shape = .(shape)), size = 2)
+    ),
+    class = c("plot_layer_block", "plot_block"),
+    ...
+  )
+}
 
 stack <- new_stack(
-  data_block,
-  new_select_block
+  data_block = new_dataset_block("penguins", "palmerpenguins"),
+  filter_block = new_filter_block("sex", "female"),
+  plot_block = new_ggplot_block("flipper_length_mm", "body_mass_g"),
+  layer_block = new_geompoint_block("species", "species")
 )
 serve_stack(stack)
 ```
 
-## Installation
+<div class="figure" style="text-align: center">
 
-You can install the development version of blockr from
-[GitHub](https://github.com/) with:
+<img src="vignettes/figures/blockr-penguins-stack.png" alt="Penguins app demo" width="100%" />
+<p class="caption">
+Penguins app demo
+</p>
 
-``` r
-# install.packages("devtools")
-pak::pkg_install("blockr-org/blockr")
-```
+</div>
 
 ## Contribute
 

_pkgdown.yml

@@ -13,7 +13,7 @@ navbar:
   bg: info
   type: light
   structure:
-    right: [reference, news, github, dark-mode]
+    right: [reference, github, dark-mode]
   components:
     home: ~
     dark-mode:
@@ -24,9 +24,11 @@ articles:
   desc: ~
   navbar: User Guide
   contents:
+  - "`blockr_examples`"
   - "`data-blocks`"
   - "`registry`"
   - "`plot-block`"
+  - "`new-field`"
   - "`developer-guide`"
 
 reference: