Skip to content

Commit

Permalink
[DOC] Improve the documentation to better match CRAN requirements (#124)
Browse files Browse the repository at this point in the history 
- Improve API documentation
- Add executable examples
  • Loading branch information
@csouchet
csouchet authored Oct 27, 2022
1 parent 06a7628 commit 116ce1f
Show file tree
Hide file tree
Showing 10 changed files with 327 additions and 61 deletions.
2 changes: 1 addition & 1 deletion DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
67 changes: 50 additions & 17 deletions R/bpmnVisualization.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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(
Expand All @@ -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,
Expand Down
16 changes: 10 additions & 6 deletions R/funs.R
View file
Original file line number Diff line number Diff line change
@@ -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) {
Expand All @@ -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(
Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ bpmn_file <- "<?xml version="1.0" encoding="UTF-8"?> ...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

Expand Down
186 changes: 186 additions & 0 deletions inst/examples/Order_Management.bpmn
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
<?xml version="1.0" encoding="UTF-8"?>
<semantic:definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
xmlns:semantic="http://www.omg.org/spec/BPMN/20100524/MODEL" targetNamespace="http://www.trisotech.com/definitions/_1275486058980">
<semantic:process id="process_1" isExecutable="false">
<semantic:startEvent id="start_event_1_1"/>
<semantic:task id="task_1_1" name="Quotation Handling" completionQuantity="1" isForCompensation="false" startQuantity="1"/>
<semantic:exclusiveGateway id="exclusive_gateway_1_1" gatewayDirection="Diverging"/>
<semantic:task id="task_1_2" name="Order Handling" completionQuantity="1" isForCompensation="false" startQuantity="1"/>
<semantic:task id="task_1_3" name="Shipping Handling" completionQuantity="1" isForCompensation="false" startQuantity="1"/>
<semantic:userTask id="user_task_1_1" name="Review Order" implementation="##unspecified" completionQuantity="1" isForCompensation="false" startQuantity="1"/>
<semantic:endEvent id="end_event_1_1"/>
<semantic:parallelGateway id="parallel_gateway_1_1" gatewayDirection="Diverging"/>
<semantic:parallelGateway id="parallel_gateway_1_2" gatewayDirection="Converging"/>
<semantic:endEvent id="end_event_1_2">
<semantic:terminateEventDefinition/>
</semantic:endEvent>
<semantic:callActivity id="call_activity_1_1" name="Approve Order" calledElement="process_2"/>
<semantic:sequenceFlow id="sequence_flow_1_1" sourceRef="start_event_1_1" targetRef="task_1_1"/>
<semantic:sequenceFlow id="sequence_flow_1_2" sourceRef="task_1_1" targetRef="call_activity_1_1"/>
<semantic:sequenceFlow id="sequence_flow_1_3" sourceRef="call_activity_1_1" targetRef="exclusive_gateway_1_1"/>
<semantic:sequenceFlow id="sequence_flow_1_4" name="Approved" sourceRef="exclusive_gateway_1_1" targetRef="parallel_gateway_1_1"/>
<semantic:sequenceFlow id="sequence_flow_1_5" sourceRef="parallel_gateway_1_1" targetRef="task_1_2"/>
<semantic:sequenceFlow id="sequence_flow_1_6" sourceRef="parallel_gateway_1_1" targetRef="task_1_3"/>
<semantic:sequenceFlow id="sequence_flow_1_7" sourceRef="task_1_2" targetRef="parallel_gateway_1_2"/>
<semantic:sequenceFlow id="sequence_flow_1_8" sourceRef="task_1_3" targetRef="parallel_gateway_1_2"/>
<semantic:sequenceFlow id="sequence_flow_1_9" sourceRef="parallel_gateway_1_2" targetRef="user_task_1_1"/>
<semantic:sequenceFlow id="sequence_flow_1_10" sourceRef="user_task_1_1" targetRef="end_event_1_1"/>
<semantic:sequenceFlow id="sequence_flow_1_11" sourceRef="exclusive_gateway_1_1" targetRef="end_event_1_2"/>
</semantic:process>
<semantic:process id="process_2" isExecutable="false">
<semantic:startEvent id="start_event_2_1"/>
<semantic:userTask id="user_task_2_1" name="Approve Customer" implementation="##unspecified" completionQuantity="1" isForCompensation="false" startQuantity="1"/>
<semantic:userTask id="user_task_2_2" name="Approve Product" implementation="##unspecified" completionQuantity="1" isForCompensation="false" startQuantity="1"/>
<semantic:endEvent id="end_event_2_1"/>
<semantic:sequenceFlow id="sequence_flow_2_1" sourceRef="start_event_2_1" targetRef="user_task_2_1"/>
<semantic:sequenceFlow id="sequence_flow_2_2" sourceRef="user_task_2_1" targetRef="user_task_2_2"/>
<semantic:sequenceFlow id="sequence_flow_2_3" sourceRef="user_task_2_2" targetRef="end_event_2_1"/>
</semantic:process>
<bpmndi:BPMNDiagram id="diagram_1" name="Order Process" resolution="96.00000267028808">
<bpmndi:BPMNPlane bpmnElement="process_1">
<bpmndi:BPMNShape id="shape_start_event_1_1" bpmnElement="start_event_1_1">
<dc:Bounds x="155" y="163" width="30" height="30"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_task_1_1" bpmnElement="task_1_1">
<dc:Bounds x="245" y="144" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_exclusive_gateway_1_1" bpmnElement="exclusive_gateway_1_1" isMarkerVisible="false">
<dc:Bounds x="529" y="157" width="42" height="42"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_task_1_2" bpmnElement="task_1_2">
<dc:Bounds x="688" y="82" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_task_1_3" bpmnElement="task_1_3">
<dc:Bounds x="688" y="212" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_user_task_1_1" bpmnElement="user_task_1_1">
<dc:Bounds x="868" y="144" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_end_event_1_1" bpmnElement="end_event_1_1">
<dc:Bounds x="1002" y="162" width="32" height="32"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_parallel_gateway_1_1" bpmnElement="parallel_gateway_1_1">
<dc:Bounds x="637" y="157" width="42" height="42"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_parallel_gateway_1_2" bpmnElement="parallel_gateway_1_2">
<dc:Bounds x="778" y="157" width="42" height="42"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_end_event_1_2" bpmnElement="end_event_1_2">
<dc:Bounds x="534" y="90" width="32" height="32"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_call_activity_1_1" bpmnElement="call_activity_1_1" isExpanded="false">
<dc:Bounds x="388" y="144" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_1" bpmnElement="sequence_flow_1_1">
<di:waypoint x="185" y="178"/>
<di:waypoint x="245" y="178"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_2" bpmnElement="sequence_flow_1_2">
<di:waypoint x="328" y="178"/>
<di:waypoint x="388" y="178"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_3" bpmnElement="sequence_flow_1_3">
<di:waypoint x="471" y="178"/>
<di:waypoint x="529" y="178"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_4" bpmnElement="sequence_flow_1_4">
<di:waypoint x="571" y="178"/>
<di:waypoint x="637" y="178"/>
<bpmndi:BPMNLabel>
<dc:Bounds x="580" y="153" width="48" height="14"/>
</bpmndi:BPMNLabel>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_5" bpmnElement="sequence_flow_1_5">
<di:waypoint x="658" y="157"/>
<di:waypoint x="658" y="116"/>
<di:waypoint x="688" y="116"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_6" bpmnElement="sequence_flow_1_6">
<di:waypoint x="658" y="199"/>
<di:waypoint x="658" y="246"/>
<di:waypoint x="688" y="246"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_7" bpmnElement="sequence_flow_1_7">
<di:waypoint x="772" y="116"/>
<di:waypoint x="799" y="116"/>
<di:waypoint x="799" y="157"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_8" bpmnElement="sequence_flow_1_8">
<di:waypoint x="772" y="246"/>
<di:waypoint x="799" y="246"/>
<di:waypoint x="799" y="199"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_9" bpmnElement="sequence_flow_1_9">
<di:waypoint x="820" y="178"/>
<di:waypoint x="868" y="178"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_10" bpmnElement="sequence_flow_1_10">
<di:waypoint x="951" y="178"/>
<di:waypoint x="1002" y="178"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_1_11" bpmnElement="sequence_flow_1_11">
<di:waypoint x="550" y="157"/>
<di:waypoint x="550" y="122"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
<bpmndi:BPMNDiagram id="diagram_2" name="Approve Order" resolution="96.00000267028808">
<bpmndi:BPMNPlane bpmnElement="process_2">
<bpmndi:BPMNShape id="shape_user_task_2_1" bpmnElement="user_task_2_1">
<dc:Bounds x="413" y="372" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_user_task_2_2" bpmnElement="user_task_2_2">
<dc:Bounds x="526" y="372" width="83" height="68"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_start_event_2_1" bpmnElement="start_event_2_1">
<dc:Bounds x="357" y="390" width="30" height="30"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="shape_end_event_2_1" bpmnElement="end_event_2_1">
<dc:Bounds x="640" y="389" width="32" height="32"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNShape>
<bpmndi:BPMNEdge id="edge_sequence_flow_2_3" bpmnElement="sequence_flow_2_3">
<di:waypoint x="609" y="406"/>
<di:waypoint x="627" y="406"/>
<di:waypoint x="640" y="406"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_2_1" bpmnElement="sequence_flow_2_1">
<di:waypoint x="388" y="406"/>
<di:waypoint x="402" y="406"/>
<di:waypoint x="413" y="406"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="edge_sequence_flow_2_2" bpmnElement="sequence_flow_2_2">
<di:waypoint x="496" y="406"/>
<di:waypoint x="526" y="406"/>
<bpmndi:BPMNLabel/>
</bpmndi:BPMNEdge>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</semantic:definitions>
22 changes: 22 additions & 0 deletions man/bpmnVisualization-shiny-output.Rd
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 22 additions & 0 deletions man/bpmnVisualization-shiny-render.Rd
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 116ce1f

Please sign in to comment.