feat(style)!: refactor how to build the overlay style (#245)

BREAKING CHANGE: `create_font`, `create_fill` and `create_stroke` functions are internal functions. `create_style` has been renamed in `create_overlay_style`, and now, we use only this function to create the style of an overlay.

Author: csouchet

NAMESPACE

@@ -1,11 +1,8 @@
 # Generated by roxygen2: do not edit by hand
 
 export(bpmnVisualizationROutput)
-export(create_fill)
-export(create_font)
 export(create_overlay)
-export(create_stroke)
-export(create_style)
+export(create_overlay_style)
 export(display)
 export(overlay_edge_position)
 export(overlay_shape_position)

R/bpmnVisualizationR.R

@@ -38,35 +38,38 @@
 #' # Load the BPMN file
 #' bpmn_file <- system.file("examples/Order_Management.bpmn", package = "bpmnVisualizationR")
 #'
-#' # Display the BPMN diagram
+#' # Example 1: Display the BPMN diagram
 #' bpmnVisualizationR::display(bpmn_file, width='auto', height='auto')
 #'
-#' # Display the BPMN diagram featuring overlays with their default positions and styles
+#' # Example 2: Display the BPMN diagram featuring overlays with their default positions and styles
 #' overlays <- list(
 #'   bpmnVisualizationR::create_overlay("start_event_1_1", "42"),
 #'   bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42"),
 #'   bpmnVisualizationR::create_overlay("task_1_1", "9"),
 #'   bpmnVisualizationR::create_overlay("sequence_flow_1_2", "8"),
 #'   bpmnVisualizationR::create_overlay("call_activity_1_1", "7")
 #' )
+#'
 #' bpmnVisualizationR::display(
 #'   bpmn_file,
 #'   overlays,
 #'   width='auto',
 #'   height='auto'
 #' )
 #'
-#' # Display the BPMN diagram featuring overlays using custom styles and positions
-#' taskStyle <- bpmnVisualizationR::create_style(
-#'   font = bpmnVisualizationR::create_font(color = 'DarkSlateGray', size = 23),
-#'   fill = bpmnVisualizationR::create_fill(color = 'MistyRose'),
-#'   stroke = bpmnVisualizationR::create_stroke(color = 'Red')
+#' # Example 3: Display the BPMN diagram featuring overlays using custom styles and positions
+#' taskStyle <- bpmnVisualizationR::create_overlay_style(
+#'   font_color = 'DarkSlateGray',
+#'   font_size = 23,
+#'   fill_color = 'MistyRose',
+#'   stroke_color = 'Red'
 #' )
 #'
-#' flowStyle <- bpmnVisualizationR::create_style(
-#'   font = bpmnVisualizationR::create_font(color = 'WhiteSmoke', size = 19),
-#'   fill = bpmnVisualizationR::create_fill(color = 'Teal'),
-#'   stroke = bpmnVisualizationR::create_stroke(color = 'SpringGreen')
+#' flowStyle <- bpmnVisualizationR::create_overlay_style(
+#'   font_color = 'WhiteSmoke',
+#'   font_size = 19,
+#'   fill_color = 'Teal',
+#'   stroke_color = 'SpringGreen'
 #' )
 #'
 #' overlays <- list(
@@ -78,13 +81,15 @@
 #' )
 #' bpmnVisualizationR::display(bpmn_file, overlays, width='auto', height='auto')
 #'
-#' # Display the BPMN diagram featuring overlays, but exclude their default styles and positions
+#' # Example 4: Display the BPMN diagram featuring overlays, 
+#' # but exclude their default styles and positions
 #' overlays <- list(
 #'   bpmnVisualizationR::create_overlay("start_event_1_1", "42", position = "middle-left"),
 #'   bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42", flowStyle, "end"),
 #'   bpmnVisualizationR::create_overlay("task_1_1", "9", taskStyle, "bottom-right"),
 #'   bpmnVisualizationR::create_overlay("sequence_flow_1_2", "8",  position = 'start')
 #' )
+#'
 #' bpmnVisualizationR::display(
 #'   bpmn_file,
 #'   overlays,

R/funs.R

@@ -3,33 +3,62 @@
 #' @description
 #' To specify the position when creating an overlay object that will be attached to BPMN \code{Shape} elements in the diagram.
 #'
-#' \code{overlay_shape_position} includes the following positions:
-#'
-#' - \code{"top-left"}
-#' - \code{"top-right"}
-#' - \code{"top-center"}
-#' - \code{"bottom-left"}
-#' - \code{"bottom-right"}
-#' - \code{"bottom-center"}
-#' - \code{"middle-left"}
-#' - \code{"middle-right"}
-#'
+#' @details
 #' Use these constants as the \code{position} argument in the \code{\link{create_overlay}} function.
 #'
+#' @section Positions:
+#'  \itemize{
+#'    \item{\code{top-left}}{}
+#'    \item{\code{top-right}}{}
+#'    \item{\code{top-center}}{}
+#'    \item{\code{bottom-left}}{}
+#'    \item{\code{bottom-right}}{}
+#'    \item{\code{bottom-center}}{}
+#'    \item{\code{middle-left}}{}
+#'    \item{\code{middle-right}}{}
+#'  }
+#'  
+#' @seealso
+#' \code{\link{create_overlay}}
+#' 
+#' @examples
+#' # Create an overlay at the top-left corner of a shape
+#' overlay <- create_overlay(elementId = 1, label = "My label", position = overlay_shape_position[1])
+#'
 #' @export
-overlay_shape_position <- c("top-left", "top-right", "top-center", "bottom-left", "bottom-right", "bottom-center", "middle-left", "middle-right")
+overlay_shape_position <-
+  c(
+    "top-left",
+    "top-right",
+    "top-center",
+    "bottom-left",
+    "bottom-right",
+    "bottom-center",
+    "middle-left",
+    "middle-right"
+  )
 
 #' @title The overlay positions on \code{Edge}
 #'
 #' @description
 #' To specify the position when creating an overlay object that will be attached to BPMN \code{Edge} elements in the diagram.
+#' 
+#' @details
+#' Use these constants as the \code{position} argument in the \code{\link{create_overlay}} function.
 #'
-#' \code{overlay_edge_position} includes the following positions:
-#' - \code{"start"}
-#' - \code{"end"}
-#' - \code{"middle"}
+#' @section Positions:
+#'  \itemize{
+#'    \item{\code{start}}{}
+#'    \item{\code{end}}{}
+#'    \item{\code{middle}}{}
+#'  }
 #'
-#' Use these constants as the \code{position} argument in the \code{\link{create_overlay}} function.
+#' @seealso
+#' \code{\link{create_overlay}}
+#'
+#' @examples
+#' # Create an overlay at the starting point of an edge
+#' overlay <- create_overlay(elementId = 1, label = "My label", position = overlay_edge_position[1])
 #' 
 #' @export
 overlay_edge_position <- c("start", "end", "middle")
@@ -47,36 +76,42 @@ overlay_edge_position <- c("start", "end", "middle")
 #' @param elementId The bpmn element id to which the overlay will be attached
 #' @param label 'HTML' element to use as an overlay
 #' @param style The style of the overlay.
-#'      Use \code{\link{create_style}} function to create the style object of an overlay and be aware of the `enableDefaultOverlayStyle` parameter in the \code{\link{display}} function.
+#'      Use \code{\link{create_overlay_style}} function to create the style object of an overlay and be aware of the `enableDefaultOverlayStyle` parameter in the \code{\link{display}} function.
 #' @param position The position of the overlay
 #'      If the bpmn element where the overlay will be attached is a Shape, use \code{\link{overlay_shape_position}}.
 #'      Otherwise, use \code{\link{overlay_edge_position}}.
 #'
 #' @returns An overlay object
 #'
 #' @examples
-#' # Create an overlay with shape position "top-left"
+#' # Example 1: Create an overlay with shape position "top-left"
+#' overlay_style <- create_overlay_style(
+#'   font_color = 'DarkSlateGray',
+#'   font_size = 23,
+#'   fill_color = 'MistyRose',
+#'   stroke_color = 'Red'
+#' )
+#'
 #' overlay <- create_overlay(
-#'   "my-element-id", 
-#'   "My Overlay Label", 
-#'   create_style(
-#'     font = create_font(color = 'DarkSlateGray', size = 23),
-#'     fill = create_fill(color = 'MistyRose'),
-#'     stroke = create_stroke(color = 'Red')
-#'   ),
-#'   overlay_shape_position[1]
+#'   "my-shape-id",
+#'   "My Overlay Label",
+#'   style = overlay_style,
+#'   position = overlay_shape_position[1]
+#' )
+#'
+#' # Example 2: Create an overlay with edge position "end"
+#' overlay_style <- create_overlay_style(
+#'   font_color = 'DarkSlateGray',
+#'   font_size = 23,
+#'   fill_color = 'MistyRose',
+#'   stroke_color = 'Red'
 #' )
 #'
-#' # Create an overlay with edge position "end"
 #' overlay <- create_overlay(
-#'   "my-edge-id", 
-#'   "My Overlay Label", 
-#'   create_style(
-#'     font = create_font(color = 'DarkSlateGray', size = 23),
-#'     fill = create_fill(color = 'MistyRose'),
-#'     stroke = create_stroke(color = 'Red')
-#'   ),
-#'   overlay_edge_position[2]
+#'   "my-edge-id",
+#'   "My Overlay Label",
+#'   style = overlay_style,
+#'   position = overlay_edge_position[2]
 #' )
 #'
 #' @export
@@ -102,49 +137,52 @@ create_overlay <- function(elementId, label, style = NULL, position = NULL) {
 
 #' @title Create the style of an overlay
 #'
-#' @name create_style
+#' @name create_overlay_style
 #' @description
 #' When adding an overlay to an existing element in a diagram, it's possible to customize its style.
 #'
 #' Refer to the \code{style} parameter in the \code{\link{create_overlay}} function for more information.
 #'
 #' Use this function to create the correct style structure for an overlay.
 #'
-#' @param font The font style of the overlay
-#'      Use \code{\link{create_font}} function to create the font style object for the overlay.
-#' @param fill The fill style of the overlay
-#'      Use \code{\link{create_fill}} function to create the fill style object for the overlay.
-#' @param stroke The stroke style of the overlay
-#'      Use \code{\link{create_stroke}} function to create the stroke style object for the overlay.
+#' @param font_color The font color of the overlay. Use all HTML color names or HEX codes.
+#' @param font_size The font size of the overlay. Specify a number in px.
+#' @param fill_color The color of the background of the overlay. Use all HTML color names or HEX codes.
+#' @param stroke_color The color of the stroke of the overlay. Use all HTML color names or HEX codes.
+#'      If you don't want to display a stroke, you can set the color to:
+#'      - \code{transparent},
+#'      - the same value as for the \code{fill_color}. This increases the \code{padding}/\code{margin}.
 #'
 #' @returns The style object of the overlay
 #'
 #' @export
-create_style <- function(font = NULL, fill = NULL, stroke = NULL) {
+create_overlay_style <- function(font_color = NULL,
+                                 font_size = NULL,
+                                 fill_color = NULL,
+                                 stroke_color = NULL) {
   ret <-
     .not_null_list(
-      font = font,
-      fill = fill,
-      stroke = stroke
+      font = create_font(color = font_color, size = font_size),
+      fill = create_fill(fill_color),
+      stroke = create_stroke(stroke_color)
     )
 }
 
-#' @title Create the font style of an overlay
+#' @title Internal function to create the font style of an overlay or a 'BPMN' element
 #'
 #' @name create_font
 #' @description
-#' When adding an overlay to an existing element in a diagram, it's possible to customize its font style.
-#'
-#' Refer to the \code{font} parameter in the \code{\link{create_style}} function for more information.
-#'
-#' Use this function to create the correct font structure for an overlay.
+#' - Overlay:
+#'  When adding an overlay to an existing element in a diagram, it's possible to customize its font style.
+#'  Refer to the \code{font} parameter in the \code{\link{create_overlay_style}} function for more information.
+#'  Use this function to create the correct font structure for an overlay.
 #'
 #' @param color The color of the font of the overlay
 #' @param size The size of the font of the overlay
 #'
 #' @returns The font style object of the overlay
 #'
-#' @export
+#' @noRd
 create_font <- function(color = NULL, size = NULL) {
   ret <-
     .not_null_list(
@@ -153,51 +191,49 @@ create_font <- function(color = NULL, size = NULL) {
     )
 }
 
-#' @title Create the fill style of an overlay
+#' @title Internal function to create the fill style of an overlay or a 'BPMN' element
 #'
 #' @name create_fill
 #' @description
-#' When adding an overlay to an existing element in a diagram, it's possible to customize how it is filled.
-#'
-#' Refer to the \code{fill} parameter in the \code{\link{create_style}} function for more information.
-#'
-#' Use this function to create the correct fill structure for an overlay.
+#' - Overlay:
+#'  When adding an overlay to an existing element in a diagram, it's possible to customize how it is filled.
+#'  Refer to the \code{fill} parameter in the \code{\link{create_overlay_style}} function for more information.
+#'  Use this function to create the correct fill structure for an overlay.
 #'
 #' @param color The color of the background of the overlay
 #'
 #' @returns The fill style object of the overlay
 #'
-#' @export
+#' @noRd
 create_fill <- function(color) {
   ret <-
     .not_null_list(
       color = color
     )
 }
 
-#' @title Create the stroke style of an overlay
+#' @title Internal function to create the stroke style of an overlay or a 'BPMN' element
 #'
 #' @name create_stroke
 #' @description
-#' When adding an overlay to an existing element in a diagram, it's possible to customize its stroke. style.
-#'
-#' Refer to the \code{stroke.} parameter in the \code{\link{create_style}} function for more information.
-#' 
-#' Use this function to create the correct stroke structure for an overlay.
+#' - Overlay:
+#'  When adding an overlay to an existing element in a diagram, it's possible to customize its stroke. style.
+#'  Refer to the \code{stroke.} parameter in the \code{\link{create_overlay_style}} function for more information.
+#'  Use this function to create the correct stroke structure for an overlay.
 #'
 #' @param color The color of the stroke of the overlay
 #'
 #' @returns The stroke style object of the overlay
 #'
-#' @export
+#' @noRd
 create_stroke <- function(color) {
   ret <-
     .not_null_list(
       color = color
     )
 }
 
-#' @description Internal fun to build the 'htmlwidget' content
+#' @description Internal function to build the 'htmlwidget' content
 #'
 #' @inheritParams display
 #' @returns A list

README.md

@@ -115,11 +115,13 @@ bpmnVisualizationR::display(bpmn_file, overlays)
 ### Style an overlay
 
 ```r
-font <- bpmnVisualizationR::create_font(color = 'WhiteSmoke', size = 19)
-fill <- bpmnVisualizationR::create_fill(color = 'Teal')
-stroke <- bpmnVisualizationR::create_stroke(color = 'SpringGreen')
+style <- bpmnVisualizationR::create_overlay_style(
+  font_color = 'WhiteSmoke',
+  font_size = 19,
+  fill_color = 'Teal',
+  stroke_color = 'SpringGreen'
+)
 
-style <- bpmnVisualizationR::create_style(font, fill, stroke)
 overlay <- bpmnVisualizationR::create_overlay("bpmn_element_id_1", "42", style, "middle-right")
 ```
 
@@ -143,10 +145,11 @@ library(shiny)
 
 displayBpmn <- function() {
     bpmn_file <- system.file("examples/Travel_Booking.bpmn", package = "bpmnVisualizationR")
-    style <- bpmnVisualizationR::create_style(
-      font = bpmnVisualizationR::create_font(color = 'Black', size = 25), 
-      fill = bpmnVisualizationR::create_fill(color = 'MediumSpringGreen'), 
-      stroke = bpmnVisualizationR::create_stroke(color = 'MediumSpringGreen')
+    style <- bpmnVisualizationR::create_overlay_style(
+      font_color = 'Black',
+      font_size = 25,
+      fill_color = 'MediumSpringGreen',
+      stroke_color = 'MediumSpringGreen'
     )
     overlays <- list(bpmnVisualizationR::create_overlay("_6-203", "9", style, "bottom-right"))
     bpmnVisualizationR::display(bpmn_file, overlays)