Skip to content

Commit f84afca

Browse files
csouchetcsouchet
authored
feat(overlay): allow to set the overlay style (#207)
- Add new functions to style an overlay: `create_fill`, `create_font`, `create_stroke` & `create_style` - Add new parameter on `display` function: `enableDefaultOverlayStyle`. If no style is set on an overlay, and this parameter is set to `TRUE`, the default style will be applied to the overlay. - Update the documentation - Update the generated documentation - Add tests
1 parent 4fd68fb commit f84afca

File tree

12 files changed

+612
-80
lines changed

12 files changed

+612
-80
lines changed

‎NAMESPACE‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
# Generated by roxygen2: do not edit by hand
22

33
export(bpmnVisualizationROutput)
4+
export(create_fill)
5+
export(create_font)
46
export(create_overlay)
7+
export(create_stroke)
8+
export(create_style)
59
export(display)
610
export(renderBpmnVisualizationR)
711
import(htmlwidgets)

‎R/bpmnVisualizationR.R‎

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,19 @@
1919
#'
2020
#' @param bpmnXML A file name or 'XML' document or string in 'BPMN' 'XML' format
2121
#' @param overlays An element or a list of elements to be added to the diagram's existing elements.
22-
#' Use overlay function to create an overlay object with content and relative position.
23-
#' @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.
24-
#' @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.
25-
#' @param elementId The id of the 'HTML' element to enclose the widget.
26-
#' Use an explicit element ID for the widget (rather than an automatically
27-
#' generated one). Useful if you have other 'JavaScript' that needs to explicitly
22+
#' Use the \code{create_overlay} function to create an overlay object with content and a relative position.
23+
#' @param enableDefaultOverlayStyle If no style is set on an overlay, and this parameter is set to \code{TRUE}, the default style will be applied to the overlay.
24+
#' By default, \code{enableDefaultOverlayStyle} is set to \code{TRUE}.
25+
#' @param width A fixed width for the widget (in CSS units).
26+
#' The default value is \code{NULL}, which results in intelligent automatic sizing based on the widget's container.
27+
#' @param height A fixed height for the widget (in CSS units).
28+
#' The default value is \code{NULL}, which results in intelligent automatic sizing based on the widget's container.
29+
#' @param elementId The ID of the 'HTML' element to enclose the widget.
30+
#' Use an explicit element ID for the widget (rather than an automatically generated one).
31+
#' This is useful if you have other 'JavaScript' that needs to explicitly
2832
#' discover and interact with a specific widget instance.
2933
#'
30-
#' @returns A \code{bpmnVisualizationR} Widget that will intelligently print itself into 'HTML' in a variety of contexts
34+
#' @returns A \code{bpmnVisualizationR} widget that will intelligently print itself into 'HTML' in a variety of contexts
3135
#' including the 'R' console, within 'R Markdown' documents, and within 'Shiny' output bindings.
3236
#'
3337
#' @examples
@@ -37,14 +41,41 @@
3741
#' # Display the BPMN diagram
3842
#' bpmnVisualizationR::display(bpmn_file, width='auto', height='auto')
3943
#'
40-
#' # Display the BPMN diagram with overlays
44+
#' # Display the BPMN diagram featuring overlays and their default style
45+
#' taskStyle <- bpmnVisualizationR::create_style(
46+
#' font = bpmnVisualizationR::create_font(color = 'DarkSlateGray', size = 23),
47+
#' fill = bpmnVisualizationR::create_fill(color = 'MistyRose'),
48+
#' stroke = bpmnVisualizationR::create_stroke(color = 'Red')
49+
#' )
50+
#'
51+
#' flowStyle <- bpmnVisualizationR::create_style(
52+
#' font = bpmnVisualizationR::create_font(color = 'WhiteSmoke', size = 19),
53+
#' fill = bpmnVisualizationR::create_fill(color = 'Teal'),
54+
#' stroke = bpmnVisualizationR::create_stroke(color = 'SpringGreen')
55+
#' )
56+
#'
4157
#' overlays <- list(
4258
#' bpmnVisualizationR::create_overlay("start_event_1_1", "42"),
43-
#' bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42"),
44-
#' bpmnVisualizationR::create_overlay("task_1_1", "9")
59+
#' bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42", flowStyle),
60+
#' bpmnVisualizationR::create_overlay("task_1_1", "9", taskStyle)
4561
#' )
4662
#' bpmnVisualizationR::display(bpmn_file, overlays, width='auto', height='auto')
4763
#'
64+
#' # Display the BPMN diagram featuring overlays, but exclude their default style
65+
#' overlays <- list(
66+
#' bpmnVisualizationR::create_overlay("start_event_1_1", "42"),
67+
#' bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42", flowStyle),
68+
#' bpmnVisualizationR::create_overlay("task_1_1", "9", taskStyle)
69+
#' )
70+
#' bpmnVisualizationR::display(
71+
#' bpmn_file,
72+
#' overlays,
73+
#' enableDefaultOverlayStyle=FALSE,
74+
#' width='auto',
75+
#' height='auto'
76+
#' )
77+
#'
78+
#'
4879
#' @seealso \code{\link{create_overlay}} to create an overlay
4980
#'
5081
#' @import htmlwidgets
@@ -54,13 +85,15 @@
5485
display <- function(
5586
bpmnXML,
5687
overlays = NULL,
88+
enableDefaultOverlayStyle = TRUE,
5789
width = NULL,
5890
height = NULL,
5991
elementId = NULL
6092
) {
6193
x <- build_bpmnContent(
6294
bpmnXML,
63-
overlays = overlays
95+
overlays = overlays,
96+
enableDefaultOverlayStyle = enableDefaultOverlayStyle
6497
)
6598
# create widget
6699
htmlwidgets::createWidget(

‎R/funs.R‎

Lines changed: 108 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,121 @@
44
#' @description
55
#' An overlay can be added to existing elements in the diagram.
66
#'
7-
#' See \code{overlays} argument in the \code{\link{display}} function.
7+
#' See the \code{overlays} argument in the \code{\link{display}} function.
88
#'
9-
#' Use this structure to create correct overlay structure.
9+
#' Use this function to create the correct overlay structure.
1010
#'
1111
#' @param elementId The bpmn element id to which the overlay will be attached
1212
#' @param label 'HTML' element to use as an overlay
13+
#' @param style The style of the overlay.
14+
#' 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.
1315
#'
1416
#' @returns An overlay object
1517
#'
1618
#' @export
17-
create_overlay <- function(elementId, label) {
19+
create_overlay <- function(elementId, label, style = NULL) {
1820
ret <-
1921
.not_null_list(
2022
elementId = elementId,
21-
label = label
23+
label = label,
24+
style = style
25+
)
26+
}
27+
28+
#' @title Create the style of an overlay
29+
#'
30+
#' @name create_style
31+
#' @description
32+
#' When adding an overlay to an existing element in a diagram, it's possible to customize its style.
33+
#'
34+
#' Refer to the \code{style} parameter in the \code{\link{create_overlay}} function for more information.
35+
#'
36+
#' Use this function to create the correct style structure for an overlay.
37+
#'
38+
#' @param font The font style of the overlay
39+
#' Use \code{\link{create_font}} function to create the font style object for the overlay.
40+
#' @param fill The fill style of the overlay
41+
#' Use \code{\link{create_fill}} function to create the fill style object for the overlay.
42+
#' @param stroke The stroke style of the overlay
43+
#' Use \code{\link{create_stroke}} function to create the stroke style object for the overlay.
44+
#'
45+
#' @returns The style object of the overlay
46+
#'
47+
#' @export
48+
create_style <- function(font = NULL, fill = NULL, stroke = NULL) {
49+
ret <-
50+
.not_null_list(
51+
font = font,
52+
fill = fill,
53+
stroke = stroke
54+
)
55+
}
56+
57+
#' @title Create the font style of an overlay
58+
#'
59+
#' @name create_font
60+
#' @description
61+
#' When adding an overlay to an existing element in a diagram, it's possible to customize its font style.
62+
#'
63+
#' Refer to the \code{font} parameter in the \code{\link{create_style}} function for more information.
64+
#'
65+
#' Use this function to create the correct font structure for an overlay.
66+
#'
67+
#' @param color The color of the font of the overlay
68+
#' @param size The size of the font of the overlay
69+
#'
70+
#' @returns The font style object of the overlay
71+
#'
72+
#' @export
73+
create_font <- function(color = NULL, size = NULL) {
74+
ret <-
75+
.not_null_list(
76+
color = color,
77+
size = size
78+
)
79+
}
80+
81+
#' @title Create the fill style of an overlay
82+
#'
83+
#' @name create_fill
84+
#' @description
85+
#' When adding an overlay to an existing element in a diagram, it's possible to customize how it is filled.
86+
#'
87+
#' Refer to the \code{fill} parameter in the \code{\link{create_style}} function for more information.
88+
#'
89+
#' Use this function to create the correct fill structure for an overlay.
90+
#'
91+
#' @param color The color of the background of the overlay
92+
#'
93+
#' @returns The fill style object of the overlay
94+
#'
95+
#' @export
96+
create_fill <- function(color) {
97+
ret <-
98+
.not_null_list(
99+
color = color
100+
)
101+
}
102+
103+
#' @title Create the stroke style of an overlay
104+
#'
105+
#' @name create_stroke
106+
#' @description
107+
#' When adding an overlay to an existing element in a diagram, it's possible to customize its stroke. style.
108+
#'
109+
#' Refer to the \code{stroke.} parameter in the \code{\link{create_style}} function for more information.
110+
#'
111+
#' Use this function to create the correct stroke structure for an overlay.
112+
#'
113+
#' @param color The color of the stroke of the overlay
114+
#'
115+
#' @returns The stroke style object of the overlay
116+
#'
117+
#' @export
118+
create_stroke <- function(color) {
119+
ret <-
120+
.not_null_list(
121+
color = color
22122
)
23123
}
24124

@@ -30,7 +130,8 @@ create_overlay <- function(elementId, label) {
30130
#' @noRd
31131
build_bpmnContent <- function(
32132
bpmnXML,
33-
overlays = NULL
133+
overlays = NULL,
134+
enableDefaultOverlayStyle
34135
) {
35136
# load bpmn content
36137
if (inherits(
@@ -60,7 +161,8 @@ build_bpmnContent <- function(
60161
stop("bpmnXML must be a absolute path of BPMN file or the string of the BPMN content !!")
61162
}
62163
x <- list(
63-
bpmnContent = bpmnContent
164+
bpmnContent = bpmnContent,
165+
enableDefaultOverlayStyle = enableDefaultOverlayStyle
64166
)
65167

66168
if (length(overlays)) {

‎README.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,22 @@ overlays <- list(bpmnVisualizationR::create_overlay("bpmn_element_id_1", "42"),
112112
bpmnVisualizationR::display(bpmn_file, overlays)
113113
```
114114

115+
### Style an overlay
116+
117+
```r
118+
font <- bpmnVisualizationR::create_font(color = 'WhiteSmoke', size = 19)
119+
fill <- bpmnVisualizationR::create_fill(color = 'Teal')
120+
stroke <- bpmnVisualizationR::create_stroke(color = 'SpringGreen')
121+
122+
style <- bpmnVisualizationR::create_style(font, fill, stroke)
123+
overlay <- bpmnVisualizationR::create_overlay("bpmn_element_id_1", "42", style)
124+
```
125+
126+
### Disable the default styles of the overlays
127+
128+
```r
129+
bpmnVisualizationR::display(bpmn_file, overlays, enableDefaultOverlayStyle=FALSE)
130+
```
115131

116132
### Integrate in Shiny Applications
117133

@@ -125,7 +141,12 @@ library(shiny)
125141

126142
displayBpmn <- function() {
127143
bpmn_file <- system.file("examples/Travel_Booking.bpmn", package = "bpmnVisualizationR")
128-
overlays <- list(bpmnVisualizationR::create_overlay("_6-203", "9"))
144+
style <- bpmnVisualizationR::create_style(
145+
font = bpmnVisualizationR::create_font(color = 'Black', size = 25),
146+
fill = bpmnVisualizationR::create_fill(color = 'MediumSpringGreen'),
147+
stroke = bpmnVisualizationR::create_stroke(color = 'MediumSpringGreen')
148+
)
149+
overlays <- list(bpmnVisualizationR::create_overlay("_6-203", "9", style))
129150
bpmnVisualizationR::display(bpmn_file, overlays)
130151
}
131152

‎inst/htmlwidgets/bpmnVisualizationR.js‎

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -21,45 +21,48 @@ HTMLWidgets.widget({
2121
factory: function(containerElt, width, height) {
2222
const bpmnVisualization = new bpmnvisu.BpmnVisualization({ container: containerElt, navigation: { enabled: true } });
2323

24+
function buildDefaultOverlayStyle(isShape) {
25+
if(isShape) {
26+
return {
27+
font: {
28+
color: 'White',
29+
size: 14,
30+
},
31+
fill: {
32+
color: 'rgba(54,160,54)',
33+
},
34+
stroke: {
35+
color: 'rgba(54,160,54)',
36+
}
37+
};
38+
}
39+
40+
return {
41+
font: {
42+
color: 'White',
43+
size: 18,
44+
},
45+
fill: {
46+
color: 'rgba(170,107,209)',
47+
},
48+
stroke: {
49+
color: 'rgba(170,107,209)',
50+
}
51+
};
52+
}
53+
2454
return {
2555
renderValue: function(x) {
2656
bpmnVisualization.load(x.bpmnContent, { fit: {type: bpmnvisu.FitType.Center, margin: 30} });
27-
2857
// Add overlays
29-
x.overlays && x.overlays.map(overlay => {
58+
x.overlays?.map(overlay => {
3059
const elementsByIds = bpmnVisualization.bpmnElementsRegistry.getElementsByIds(overlay.elementId);
3160

3261
if (elementsByIds.length) {
33-
const overlayConfig = elementsByIds[0].bpmnSemantic.isShape ? {
34-
position: 'top-center',
35-
label: overlay.label,
36-
style: {
37-
font: {
38-
color: 'White',
39-
size: 14,
40-
},
41-
fill: {
42-
color: 'rgba(54,160,54)',
43-
},
44-
stroke: {
45-
color: 'rgba(54,160,54)',
46-
}
47-
}
48-
} : {
49-
position: 'middle',
62+
const overlayConfig = {
5063
label: overlay.label,
51-
style: {
52-
font: {
53-
color: 'White',
54-
size: 18,
55-
},
56-
fill: {
57-
color: 'rgba(170,107,209)',
58-
},
59-
stroke: {
60-
color: 'rgba(170,107,209)',
61-
}
62-
}
64+
style: overlay.style ?? (x.enableDefaultOverlayStyle && buildDefaultOverlayStyle(elementsByIds[0].bpmnSemantic.isShape)),
65+
position: elementsByIds[0].bpmnSemantic.isShape ? 'top-center' : 'middle',
6366
};
6467

6568
bpmnVisualization.bpmnElementsRegistry.addOverlays(overlay.elementId, overlayConfig);

‎man/create_fill.Rd‎

Lines changed: 21 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)