From 02df294f2f32038c17925afee5bb923416c7ab2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Souchet=20C=C3=A9line?= Date: Thu, 27 Oct 2022 15:09:12 +0200 Subject: [PATCH 1/5] Update readme to indicate how to install the goodpractice package --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 231034a..c77ebd7 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,15 @@ It is made possible by [htmlwidgets](http://www.htmlwidgets.org/), which provide It can be installed from the R console: ```r install.packages('devtools') +library('devtools') +``` + +#### Install _goodpractice_ +[goodpractice](https://github.com/mangothecat/goodpractice) is an R package used to have advice about good practices when building R packages. +It can be installed from the R console: +```r +install.packages('goodpractice') +library('goodpractice') ``` #### Install _BPMN Visualization - R Package_ from GitHub From 37b5c78350ee4a93240f7152bee55f72155ac13b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Souchet=20C=C3=A9line?= Date: Thu, 27 Oct 2022 15:11:50 +0200 Subject: [PATCH 2/5] Format code --- R/bpmnVisualization.R | 84 +++++++++++++++++++------------------------ R/funs.R | 48 +++++++++---------------- 2 files changed, 53 insertions(+), 79 deletions(-) diff --git a/R/bpmnVisualization.R b/R/bpmnVisualization.R index b90a96b..50010d4 100644 --- a/R/bpmnVisualization.R +++ b/R/bpmnVisualization.R @@ -16,7 +16,7 @@ #' #' @name display #' @description Display BPMN diagram based on BPMN definition in XML format -#' +#' #' @param bpmnXML A file name or xml document or string in BPMN XML format #' @param overlays An element or a list of elements to be added to the diagram's existing elements. #' Use overlay function to create an overlay object with content and relative position. @@ -26,17 +26,17 @@ #' Use an explicit element ID for the widget (rather than an automatically #' generated one). Useful if you have other JavaScript that needs to explicitly #' discover and interact with a specific widget instance. -#' -#' @returns A \code{bpmn-visualization} Widget that will intelligently print itself into HTML in a variety of contexts +#' +#' @returns A \code{bpmn-visualization} Widget that will intelligently print itself into HTML in a variety of contexts #' including the R console, within R Markdown documents, and within Shiny output bindings. -#' -#' @examples +#' +#' @examples #' # Load the BPMN file #' bpmn_file <- system.file("examples/Order_Management.bpmn", package = "bpmnVisualization") -#' +#' #' # Display the BPMN diagram #' display(bpmn_file, width='auto', height='auto') -#' +#' #' # Display the BPMN diagram with overlays #' overlays <- list( #' create_overlay("start_event_1_1", "42"), @@ -44,24 +44,20 @@ #' create_overlay("task_1_1", "9") #' ) #' display(bpmn_file, overlays, width='auto', height='auto') -#' +#' #' @seealso \code{\link{create_overlay}} to create an overlay #' #' @import htmlwidgets #' @import xml2 #' #' @export -display <- function( - bpmnXML, - overlays = NULL, - width = NULL, - height = NULL, - elementId = NULL -) { - x <- build_bpmnContent( - bpmnXML, - overlays = overlays - ) +display <- function(bpmnXML, + overlays = NULL, + width = NULL, + height = NULL, + elementId = NULL) { + x <- build_bpmnContent(bpmnXML, + overlays = overlays) # create widget htmlwidgets::createWidget( name = "bpmnVisualization", @@ -76,37 +72,33 @@ display <- function( #' @title Shiny output binding for the \code{bpmn-visualization} HTML widget #' #' @name bpmnVisualization-shiny-output -#' @description +#' @description #' Helper to create output function for using the \code{bpmn-visualization} HTML widget within Shiny applications and interactive Rmd documents. -#' +#' #' @param outputId output variable to read from #' @param width,height Must be a valid CSS unit (like \code{'100\%'}, #' \code{'400px'}, \code{'auto'}) or a number, which will be coerced to a #' string and have \code{'px'} appended. -#' +#' #' @returns An output function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. #' #' @export -bpmnVisualizationOutput <- function( - outputId, - width = "100%", - height = "400px" -) { - htmlwidgets::shinyWidgetOutput( - outputId, - "bpmnVisualization", - width, - height, - package = "bpmnVisualization" - ) +bpmnVisualizationOutput <- function(outputId, + width = "100%", + height = "400px") { + htmlwidgets::shinyWidgetOutput(outputId, + "bpmnVisualization", + width, + height, + package = "bpmnVisualization") } #' @title Shiny render binding for the \code{bpmn-visualization} HTML widget -#' +#' #' @rdname bpmnVisualization-shiny-render -#' @description +#' @description #' Helper to create render function for using the \code{bpmn-visualization} HTML widget within Shiny applications and interactive Rmd documents. -#' +#' #' @param expr An expression that generates a \code{bpmn-visualization} HTML widget #' @param env The environment in which to evaluate \code{expr}. #' @param quoted Is \code{expr} a quoted expression (with \code{quote()})? This @@ -115,20 +107,16 @@ bpmnVisualizationOutput <- function( #' @returns A render function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. #' #' @export -renderBpmnVisualization <- function( - expr, - env = parent.frame(), - quoted = FALSE -) { +renderBpmnVisualization <- function(expr, + env = parent.frame(), + quoted = FALSE) { # Checking that shiny is installed rlang::check_installed("shiny") if (!quoted) { expr <- substitute(expr) } # force quoted - htmlwidgets::shinyRenderWidget( - expr, - bpmnVisualizationOutput, - env, - quoted = TRUE - ) + htmlwidgets::shinyRenderWidget(expr, + bpmnVisualizationOutput, + env, + quoted = TRUE) } diff --git a/R/funs.R b/R/funs.R index eef7b07..54732aa 100644 --- a/R/funs.R +++ b/R/funs.R @@ -1,13 +1,13 @@ #' @title Create an overlay #' #' @name create_overlay -#' @description +#' @description #' An overlay can be added to existing elements in the diagram. -#' +#' #' See \code{overlays} argument in the \code{\link{display}} function. -#' +#' #' Use this structure to create correct overlay structure. -#' +#' #' @param elementId The bpmn element id to which the overlay will be attached #' @param label HTML element to use as an overlay #' @@ -16,10 +16,8 @@ #' @export create_overlay <- function(elementId, label) { ret <- - .not_null_list( - elementId = elementId, - label = label - ) + .not_null_list(elementId = elementId, + label = label) } #' @description Internal fun to build the htmlwidget content @@ -28,27 +26,17 @@ create_overlay <- function(elementId, label) { #' @returns A list #' #' @noRd -build_bpmnContent <- function( - bpmnXML, - overlays = NULL -) { +build_bpmnContent <- function(bpmnXML, + overlays = NULL) { # load bpmn content - if (inherits( - bpmnXML, - "xml_document" - )) { + if (inherits(bpmnXML, + "xml_document")) { bpmnContent <- as.character(bpmnXML) - } else if ( - inherits( - bpmnXML, - "character" - )) { - if ( - substring( - bpmnXML, - 1, - 38 - ) == "") { + } else if (inherits(bpmnXML, + "character")) { + if (substring(bpmnXML, + 1, + 38) == "") { # this must be a string corresponding to the BPMN content of a file bpmnContent <- bpmnXML } else { @@ -59,10 +47,8 @@ build_bpmnContent <- function( } else { stop("bpmnXML must be a absolute path of BPMN file or the string of the BPMN content !!") } - x <- list( - bpmnContent = bpmnContent - ) - + x <- list(bpmnContent = bpmnContent) + if (length(overlays)) { # In case the user passes a single parameter as overlays (instead of a list), we wrap it into a list so the js can work x$overlays <- if (is.list(overlays[[1]])) { From 8ecf98c75cb09b314237cd10a3fe2081b3c681fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Souchet=20C=C3=A9line?= Date: Thu, 27 Oct 2022 15:35:14 +0200 Subject: [PATCH 3/5] Make lines shorter than 80 characters --- R/bpmnVisualization.R | 41 +++++++++++++++++++++++++++-------------- R/funs.R | 6 ++++-- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/R/bpmnVisualization.R b/R/bpmnVisualization.R index 50010d4..e065585 100644 --- a/R/bpmnVisualization.R +++ b/R/bpmnVisualization.R @@ -18,21 +18,29 @@ #' @description Display BPMN diagram based on BPMN definition in XML format #' #' @param bpmnXML A file name or xml document or string in BPMN XML format -#' @param overlays An element or a list of elements to be added to the diagram's existing elements. -#' Use overlay function to create an overlay object with content and relative position. -#' @param width Fixed width for widget (in css units). The default is \code{NULL}, which results in intelligent automatic sizing based on the widget's container. -#' @param height Fixed height for widget (in css units). The default is \code{NULL}, which results in intelligent automatic sizing based on the widget's container. +#' @param overlays An element or a list of elements to be added to the diagram's +#' existing elements. +#' Use overlay function to create an overlay object with content and +#' relative position. +#' @param width Fixed width for widget (in css units). +#' The default is \code{NULL}, which results in intelligent automatic +#' sizing based on the widget's container. +#' @param height Fixed height for widget (in css units). +#' The default is \code{NULL}, which results in intelligent automatic +#' sizing based on the widget's container. #' @param elementId The id of the HTML element to enclose the widget. #' Use an explicit element ID for the widget (rather than an automatically -#' generated one). Useful if you have other JavaScript that needs to explicitly -#' discover and interact with a specific widget instance. +#' generated one). Useful if you have other JavaScript that needs to +#' explicitly discover and interact with a specific widget instance. #' -#' @returns A \code{bpmn-visualization} Widget that will intelligently print itself into HTML in a variety of contexts -#' including the R console, within R Markdown documents, and within Shiny output bindings. +#' @returns A \code{bpmn-visualization} Widget that will intelligently print +#' itself into HTML in a variety of contexts including the R console, +#' within R Markdown documents, and within Shiny output bindings. #' #' @examples #' # Load the BPMN file -#' bpmn_file <- system.file("examples/Order_Management.bpmn", package = "bpmnVisualization") +#' bpmn_file <- system.file("examples/Order_Management.bpmn", +#' package = "bpmnVisualization") #' #' # Display the BPMN diagram #' display(bpmn_file, width='auto', height='auto') @@ -73,14 +81,16 @@ display <- function(bpmnXML, #' #' @name bpmnVisualization-shiny-output #' @description -#' Helper to create output function for using the \code{bpmn-visualization} HTML widget within Shiny applications and interactive Rmd documents. +#' Helper to create output function for using the \code{bpmn-visualization} +#' HTML widget within Shiny applications and interactive Rmd documents. #' #' @param outputId output variable to read from #' @param width,height Must be a valid CSS unit (like \code{'100\%'}, #' \code{'400px'}, \code{'auto'}) or a number, which will be coerced to a #' string and have \code{'px'} appended. #' -#' @returns An output function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. +#' @returns An output function that enables the use of the +#' \code{bpmn-visualization} widget within Shiny applications. #' #' @export bpmnVisualizationOutput <- function(outputId, @@ -97,14 +107,17 @@ bpmnVisualizationOutput <- function(outputId, #' #' @rdname bpmnVisualization-shiny-render #' @description -#' Helper to create render function for using the \code{bpmn-visualization} HTML widget within Shiny applications and interactive Rmd documents. +#' Helper to create render function for using the \code{bpmn-visualization} +#' HTML widget within Shiny applications and interactive Rmd documents. #' -#' @param expr An expression that generates a \code{bpmn-visualization} HTML widget +#' @param expr An expression that generates a \code{bpmn-visualization} HTML +#' widget #' @param env The environment in which to evaluate \code{expr}. #' @param quoted Is \code{expr} a quoted expression (with \code{quote()})? This #' is useful if you want to save an expression in a variable. #' -#' @returns A render function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. +#' @returns A render function that enables the use of the +#' \code{bpmn-visualization} widget within Shiny applications. #' #' @export renderBpmnVisualization <- function(expr, diff --git a/R/funs.R b/R/funs.R index 54732aa..c979901 100644 --- a/R/funs.R +++ b/R/funs.R @@ -45,12 +45,14 @@ build_bpmnContent <- function(bpmnXML, bpmnContent <- as.character(xml) } } else { - stop("bpmnXML must be a absolute path of BPMN file or the string of the BPMN content !!") + stop("bpmnXML must be a absolute path of BPMN file or the string of the BPMN + content !!") } x <- list(bpmnContent = bpmnContent) if (length(overlays)) { - # In case the user passes a single parameter as overlays (instead of a list), we wrap it into a list so the js can work + # In case the user passes a single parameter as overlay (instead of a list), + # we wrap it into a list, so the js can work. x$overlays <- if (is.list(overlays[[1]])) { overlays } else { From 66ebb743fba40ffef5aabc6d6db6909da7332bd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Souchet=20C=C3=A9line?= Date: Thu, 27 Oct 2022 15:57:11 +0200 Subject: [PATCH 4/5] Add final line as recommended --- tests/testthat/test-funs.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/testthat/test-funs.R b/tests/testthat/test-funs.R index 9490881..2a4b646 100644 --- a/tests/testthat/test-funs.R +++ b/tests/testthat/test-funs.R @@ -147,4 +147,4 @@ test_that("not_null_list works", { res, c("x") ) -}) \ No newline at end of file +}) From 6654f5bb0ac14433ef23841825ade16065365cb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Souchet=20C=C3=A9line?= Date: Fri, 28 Oct 2022 09:39:29 +0200 Subject: [PATCH 5/5] Update doc --- CONTRIBUTING.md | 9 +++++++++ README.md | 14 +++----------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2de7168..5e23406 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,6 +106,15 @@ At this point, you're ready to make your changes! Feel free to ask for help. Eve devtools::install() ``` +### Install the `goodpractice` package +[`goodpractice`](https://github.com/mangothecat/goodpractice) is an R package used to have advice about good practices when building R packages. +It can be installed from the R console: +```r +install.packages('goodpractice') +library('goodpractice') +``` +Then, follow the `goodpractice` documentation to execute the package. + ### Regenerate the R documentation The **R documentation** (.Rd) format is generated from the function comments thanks to [roxygen2](https://roxygen2.r-lib.org/). \ To regenerate this documentation after function comment updating, run this command: diff --git a/README.md b/README.md index c77ebd7..92c3628 100644 --- a/README.md +++ b/README.md @@ -28,23 +28,15 @@ It is made possible by [htmlwidgets](http://www.htmlwidgets.org/), which provide ## ♻️ Usage ### Installation -#### Install _devtools_ -[Devtools](https://www.rdocumentation.org/packages/devtools) is an R package used to ease the installation and the development of other R packages. +#### Install `devtools` +[`devtools`](https://www.rdocumentation.org/packages/devtools) is an R package used to ease the installation and the development of other R packages. It can be installed from the R console: ```r install.packages('devtools') library('devtools') ``` -#### Install _goodpractice_ -[goodpractice](https://github.com/mangothecat/goodpractice) is an R package used to have advice about good practices when building R packages. -It can be installed from the R console: -```r -install.packages('goodpractice') -library('goodpractice') -``` - -#### Install _BPMN Visualization - R Package_ from GitHub +#### Install `BPMN Visualization - R Package` from GitHub To install a dedicated version (available versions can be found in the [GitHub releases page](https://github.com/process-analytics/bpmn-visualization-R/releases)), run: ```r