Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] Improve the documentation to better match CRAN requirements #124

Merged
merged 16 commits into from
Oct 27, 2022
Merged

[DOC] Improve the documentation to better match CRAN requirements #124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
10a7d76
Update the documentation
csouchet Oct 26, 2022
61108ee
Update the documentation
csouchet Oct 26, 2022
b0ce3e6
@seealso link in display function works in html page, but not in stud…
csouchet Oct 26, 2022
31492f4
Add new bpmn file
csouchet Oct 26, 2022
4f8c9b3
Replace the BPMN file used in the doc example and add overlays
csouchet Oct 26, 2022
672813a
Fix ids
csouchet Oct 26, 2022
3041a4a
Update coordinates
csouchet Oct 26, 2022
6ed32fb
Auto size the widget in the doc
csouchet Oct 26, 2022
98fe5a6
Increase the size of the sequence flows
csouchet Oct 26, 2022
98b22e0
Improve the documentation by returning to the line in the example
csouchet Oct 26, 2022
9b22a57
improve api doc for the 'display' function
tbouffard Oct 26, 2022
7bebdd3
Merge branch 'main' into update_doc
csouchet Oct 27, 2022
6be62af
Merge branch 'main' into update_doc
csouchet Oct 27, 2022
484d922
improve api
tbouffard Oct 27, 2022
89cd9fe
improve wording in docs
tbouffard Oct 27, 2022
6ca2916
Generate the new doc
csouchet Oct 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion DESCRIPTION
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop

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
Open in desktop

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

Loading