Usage
=====

ZenUmlDiagram allows the creation of `ZenUML <https://zenuml.com>`__ sequence diagrams.

ZenUML Elements
---------------

Loops
+++++

There are a number of different loop types that can be used to express the system.

Forr
....

Forr represents a `for` loop; the condition should be similar to a PHP *for* loop condition.

Foreachh
........

Foreachh represents a `foreach` loop; the condition should be similar to a PHP *foreach* loop condition.

Loop
....

Loop represents a loop where none of the other loop types are appropriate, e.g. `Loop('Every minute')`.

Whilee
......

Whilee represents a `while` loop; the condition should be similar to a PHP *while* loop condition.

Messages
++++++++

Async
.....

Async messages are non-blocking.

Sync
....

Sync messages are similar to blocking methods. Sync messages can contain other messages.

Creation
........

A creation message allows creation of a new object in the system diagram

Return
......

A return message allows a Participant to return a value; the value can also be typed.

Participants
++++++++++++

Participants are objects - people, entities, sub-systems, etc. - that pass messages from one to another.

ZenUML allows customisation of Participants using Annotations and Stereotypes.

Try/Catch
+++++++++

Try/Catch accepts two or three objects:

* Tryy - the Try clause (required)
* Catchh - the Catch clause (required)
* Finallyy - a Finally clause (optional)

Example
-------

PHP
+++

.. code-block:: php

    $backend = new Participant('BackEnd');
    $customer = new Participant('Customer', annotation: Annotation::Actor);
    $deliverySystem = new Participant('DeliverySystem');
    $paymentGateway = new Participant('PaymentGateway');
    $website = new Participant('Website');

    echo Mermaid::create(ZenUmlDiagram::class)
        ->withTitle('Online shopping')
        ->withParticipant($customer)
        ->withItem(
            (new SyncMessage('browse', $website, $customer))
                ->withItem(new SyncMessage('loadProducts', $backend))
            ,
            (new SyncMessage('addToCart', $website, $customer))
                ->withParameter('p1', 'p2')
                ->withItem(new SyncMessage('updateCart', $backend))
            ,
            (new SyncMessage('submitOrder', $website, $customer))
                ->withParameter('p1', 'p2')
                ->withItem(new SyncMessage('createOrder', $backend))
            ,
            (new SyncMessage('checkout', $website, $customer))
                ->withParameter('paymentInfo')
                ->withItem(
                    (new SyncMessage('checkout', $backend))
                        ->withParameter('paymentInfo')
                        ->withItem(
                            (new SyncMessage('processPaymentInfo', $paymentGateway))
                                ->withReturn('result')
                            ,
                            (new SyncMessage('updateOrder', $customer))
                                ->withParameter('result')
                            ,
                            (new Iff('result == success'))
                                ->withItem(
                                    new SyncMessage('register', $deliverySystem),
                                    new AsyncMessage('Deliver the order', $customer, $deliverySystem)
                                )
                                ->withElse(
                                    (new Elsee())
                                        ->withItem(
                                            new ReturnMessage('rejected'),
                                            new ReturnMessage(new AsyncMessage('rejected', $customer, $website))
                                        )
                                )
                        )
                )
        )
        ->render()
    ;

Generated Mermaid
+++++++++++++++++

.. code-block:: html

    <pre class="mermaid">
    zenuml
      title Online shopping
      @Actor Customer
      Customer->Website.browse() {
        BackEnd.loadProducts()
      }
      Customer->Website.addToCart(p1, p2) {
        BackEnd.updateCart()
      }
      Customer->Website.submitOrder(p1, p2) {
        BackEnd.createOrder()
      }
      Customer->Website.checkout(paymentInfo) {
        BackEnd.checkout(paymentInfo) {
          result = PaymentGateway.processPaymentInfo()
          Customer.updateOrder(result)
          if (result == success) {
            DeliverySystem.register()
            DeliverySystem->Customer: Deliver the order
          } else {
            return rejected
            @return Website->Customer: rejected
          }
        }
      }
    </pre>

Mermaid Diagram
+++++++++++++++

.. warning:: Mermaid JS ZenUML Rendering Error

    Mermaid JS v11.12.1 and v11.12.2 error when rendering ZenUML diagrams;
    the `Mermaid JS ZenUML page <https://mermaid.js.org/syntax/zenuml>`__ uses v11.12.2 and has errors;
    this page uses v11.12.1 and also errors. Later Mermaid JS versions have not yet been tested.

    The generated example code above renders correctly with:

    *  Mermaid JS v11.12.0 (used by `the Mermaid Live Editor <https://mermaid.live/edit>`__ (remove the `<pre>` tag) at the time of writing)
    * `the ZenUML Web App <https://app.zenuml.com>`__ (remove the `<pre>` tag and the `zenuml` line)

.. mermaid::

    zenuml
      @Actor Customer
      Customer->Website.browse() {
        BackEnd.loadProducts()
      }
      Customer->Website.addToCart(p1, p2) {
        BackEnd.updateCart()
      }
      Customer->Website.submitOrder(p1, p2) {
        BackEnd.createOrder()
      }
      Customer->Website.checkout(paymentInfo) {
        BackEnd.checkout(paymentInfo) {
          result = PaymentGateway.processPaymentInfo()
          Customer.updateOrder(result)
          if (result == success) {
            DeliverySystem.register()
            DeliverySystem->Customer: Deliver the order
          } else {
            return rejected
            @return Website->Customer: rejected
          }
        }
      }