diff --git a/DESCRIPTION b/DESCRIPTION index 9b5a9dc..259bac8 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -11,7 +11,7 @@ URL: https://github.com/process-analytics/bpmn-visualization-R BugReports: https://github.com/process-analytics/bpmn-visualization-R/issues Encoding: UTF-8 LazyData: true -RoxygenNote: 7.1.2 +RoxygenNote: 7.2.1 Imports: htmlwidgets, rlang, diff --git a/R/bpmnVisualization.R b/R/bpmnVisualization.R index 14752f3..b90a96b 100644 --- a/R/bpmnVisualization.R +++ b/R/bpmnVisualization.R @@ -12,16 +12,40 @@ # See the License for the specific language governing permissions and # limitations under the License. -#' display -#' -#' Display BPMN diagram based on BPMN definition in XML format +#' @title Display BPMN diagram in an HTML Widget #' +#' @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. -#' @param width The width used to display the widget -#' @param height The height used to display the widget -#' @param elementId The id of the HTML element to enclose the widget +#' @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. +#' +#' @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") +#' +#' # 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"), +#' create_overlay("sequence_flow_1_1", "42"), +#' 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 @@ -49,21 +73,18 @@ display <- function( ) } -#' Shiny bindings for bpmnVisualization -#' -#' Output and render functions for using bpmnVisualization within Shiny -#' applications and interactive Rmd documents. +#' @title Shiny output binding for the \code{bpmn-visualization} HTML widget #' +#' @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. +#' #' @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. -#' @param expr An expression that generates a bpmnVisualization -#' @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. -#' -#' @name bpmnVisualization-shiny +#' +#' @returns An output function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. #' #' @export bpmnVisualizationOutput <- function( @@ -80,7 +101,19 @@ bpmnVisualizationOutput <- function( ) } -#' @rdname bpmnVisualization-shiny +#' @title Shiny render binding for the \code{bpmn-visualization} HTML widget +#' +#' @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. +#' +#' @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. +#' #' @export renderBpmnVisualization <- function( expr, diff --git a/R/funs.R b/R/funs.R index 4733647..eef7b07 100644 --- a/R/funs.R +++ b/R/funs.R @@ -1,13 +1,17 @@ -#' create_overlay +#' @title Create an overlay #' +#' @name create_overlay +#' @description #' An overlay can be added to existing elements in the diagram. -#' See \code{overlays} argument in \code{\link{bpmnVisualization}} function. +#' +#' 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 #' -#' @return An overlay object +#' @returns An overlay object #' #' @export create_overlay <- function(elementId, label) { @@ -18,10 +22,10 @@ create_overlay <- function(elementId, label) { ) } -#' Internal fun to build the htmlwidget content +#' @description Internal fun to build the htmlwidget content #' #' @inheritParams display -#' @return A list +#' @returns A list #' #' @noRd build_bpmnContent <- function( diff --git a/README.md b/README.md index 6e02a7b..2c00c13 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,7 @@ bpmn_file <- " ...xml_content" They are taken from the [BPMN 2.0 examples non-normative machine readable files](https://www.omg.org/spec/BPMN/2.0). - Email_Voting.bpmn - Nobel_Prize_Process.bpmn +- Order_Management.bpmn - Order_Process_for_Pizza_V4.bpmn - Travel_Booking.bpmn diff --git a/inst/examples/Order_Management.bpmn b/inst/examples/Order_Management.bpmn new file mode 100644 index 0000000..dd127e1 --- /dev/null +++ b/inst/examples/Order_Management.bpmn @@ -0,0 +1,186 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/man/bpmnVisualization-shiny-output.Rd b/man/bpmnVisualization-shiny-output.Rd new file mode 100644 index 0000000..165a95e --- /dev/null +++ b/man/bpmnVisualization-shiny-output.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bpmnVisualization.R +\name{bpmnVisualization-shiny-output} +\alias{bpmnVisualization-shiny-output} +\alias{bpmnVisualizationOutput} +\title{Shiny output binding for the \code{bpmn-visualization} HTML widget} +\usage{ +bpmnVisualizationOutput(outputId, width = "100\%", height = "400px") +} +\arguments{ +\item{outputId}{output variable to read from} + +\item{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.} +} +\value{ +An output function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. +} +\description{ +Helper to create output function for using the \code{bpmn-visualization} HTML widget within Shiny applications and interactive Rmd documents. +} diff --git a/man/bpmnVisualization-shiny-render.Rd b/man/bpmnVisualization-shiny-render.Rd new file mode 100644 index 0000000..b12c77e --- /dev/null +++ b/man/bpmnVisualization-shiny-render.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bpmnVisualization.R +\name{renderBpmnVisualization} +\alias{renderBpmnVisualization} +\title{Shiny render binding for the \code{bpmn-visualization} HTML widget} +\usage{ +renderBpmnVisualization(expr, env = parent.frame(), quoted = FALSE) +} +\arguments{ +\item{expr}{An expression that generates a \code{bpmn-visualization} HTML widget} + +\item{env}{The environment in which to evaluate \code{expr}.} + +\item{quoted}{Is \code{expr} a quoted expression (with \code{quote()})? This +is useful if you want to save an expression in a variable.} +} +\value{ +A render function that enables the use of the \code{bpmn-visualization} widget within Shiny applications. +} +\description{ +Helper to create render function for using the \code{bpmn-visualization} HTML widget within Shiny applications and interactive Rmd documents. +} diff --git a/man/bpmnVisualization-shiny.Rd b/man/bpmnVisualization-shiny.Rd deleted file mode 100644 index d4046b0..0000000 --- a/man/bpmnVisualization-shiny.Rd +++ /dev/null @@ -1,30 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/bpmnVisualization.R -\name{bpmnVisualization-shiny} -\alias{bpmnVisualization-shiny} -\alias{bpmnVisualizationOutput} -\alias{renderBpmnVisualization} -\title{Shiny bindings for bpmnVisualization} -\usage{ -bpmnVisualizationOutput(outputId, width = "100\%", height = "400px") - -renderBpmnVisualization(expr, env = parent.frame(), quoted = FALSE) -} -\arguments{ -\item{outputId}{output variable to read from} - -\item{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.} - -\item{expr}{An expression that generates a bpmnVisualization} - -\item{env}{The environment in which to evaluate \code{expr}.} - -\item{quoted}{Is \code{expr} a quoted expression (with \code{quote()})? This -is useful if you want to save an expression in a variable.} -} -\description{ -Output and render functions for using bpmnVisualization within Shiny -applications and interactive Rmd documents. -} diff --git a/man/create_overlay.Rd b/man/create_overlay.Rd index e1af9c2..ec6c45f 100644 --- a/man/create_overlay.Rd +++ b/man/create_overlay.Rd @@ -1,8 +1,8 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/bpmnVisualization.R +% Please edit documentation in R/funs.R \name{create_overlay} \alias{create_overlay} -\title{create_overlay} +\title{Create an overlay} \usage{ create_overlay(elementId, label) } @@ -16,6 +16,8 @@ An overlay object } \description{ An overlay can be added to existing elements in the diagram. -See \code{overlays} argument in \code{\link{bpmnVisualization}} function. + +See \code{overlays} argument in the \code{\link{display}} function. + Use this structure to create correct overlay structure. } diff --git a/man/display.Rd b/man/display.Rd index 9151eeb..88c4d1e 100644 --- a/man/display.Rd +++ b/man/display.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/bpmnVisualization.R \name{display} \alias{display} -\title{display} +\title{Display BPMN diagram in an HTML Widget} \usage{ display( bpmnXML, @@ -18,12 +18,38 @@ display( \item{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.} -\item{width}{The width used to display the widget} +\item{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.} -\item{height}{The height used to display the widget} +\item{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.} -\item{elementId}{The id of the HTML element to enclose the widget} +\item{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.} +} +\value{ +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. } \description{ Display BPMN diagram based on BPMN definition in XML format } +\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"), + create_overlay("sequence_flow_1_1", "42"), + create_overlay("task_1_1", "9") +) +display(bpmn_file, overlays, width='auto', height='auto') + +} +\seealso{ +\code{\link{create_overlay}} to create an overlay +}