This library add Symfony Workflow component integration within Sonata Admin.
- add a menu dropdown to your admin detail pages on which you have buttons to apply available transitions
- ship a controller to apply transition
- allow to hook into the apply transition process to show an intermediate page
- a Sonata Admin Extension : WorkflowExtension
- a Controller trait : WorkflowControllerTrait
- a Controller : WorkflowController
$ composer require yokai/sonata-workflow
Let say that you have an entity named PullRequest
that is under workflow and for which you have an admin.
# config/packages/workflow.yml
framework:
workflows:
pull_request:
type: state_machine
marking_store:
type: single_state
arguments:
- status
supports:
- App\Entity\PullRequest
places:
- opened
- pending_review
- merged
- closed
initial_place: opened
transitions:
start_review:
from: opened
to: pending_review
merge:
from: pending_review
to: merged
close:
from: pending_review
to: closed
The extension is usable for many entities and with no configuration.
You only need to create a service for it, configure the controller that will handle the transition action and configure on which admin you want it available.
For instance :
# config/packages/sonata_admin.yml
services:
admin.pull_request:
class: App\Admin\PullRequestAdmin
public: true
arguments: [~, App\Entity\PullRequest, Yokai\SonataWorkflow\Controller\WorkflowController]
tags:
- { name: 'sonata.admin', manager_type: orm, label: PullRequest }
admin.extension.workflow:
class: Yokai\SonataWorkflow\Admin\Extension\WorkflowExtension
public: true
arguments:
- '@workflow.registry'
Yokai\SonataWorkflow\Controller\WorkflowController:
autowire: true
tags: ['controller.service_arguments']
sonata_admin:
extensions:
admin.extension.workflow:
admins:
- admin.pull_request
note: You may noticed that we also registered the controller
Yokai\SonataWorkflow\Controller\WorkflowController
as a service. It is important, because it needs the workflow registry service to work.
But the extension accepts many options if you wish to customize the behavior.
For instance :
# config/packages/sonata_admin.yml
services:
admin.pull_request:
class: App\Admin\PullRequestAdmin
public: true
arguments: [~, App\Entity\PullRequest, 'Yokai\SonataWorkflow\Controller\WorkflowController']
tags:
- { name: 'sonata.admin', manager_type: orm, label: PullRequest }
admin.extension.pull_request_workflow:
class: Yokai\SonataWorkflow\Admin\Extension\WorkflowExtension
public: true
arguments:
- '@workflow.registry'
- render_actions: [show]
workflow_name: pull_request
no_transition_label: No transition for pull request
no_transition_icon: fa fa-times
dropdown_transitions_label: Pull request transitions
dropdown_transitions_icon: fa fa-archive
transitions_default_icon: fa fa-step-forward
transitions_icons:
start_review: fa fa-search
merge: fa fa-check
close: fa fa-times
Yokai\SonataWorkflow\Controller\WorkflowController:
autowire: true
tags: ['controller.service_arguments']
sonata_admin:
extensions:
admin.extension.pull_request_workflow:
admins:
- admin.pull_request
What are these options ?
render_actions
: Admin action names on which the extension should render its menu (defaults to[show, edit]
)workflow_name
: The name of the Workflow to handle (defaults tonull
)no_transition_display
: Whether or not to display a button when no transition is enabled (defaults tofalse
)no_transition_label
: The button label when no transition is enabled (defaults toworkflow_transitions_empty
)no_transition_icon
: The button icon when no transition is enabled (defaults tofa fa-code-fork
)dropdown_transitions_label
: The dropdown button label when there is transitions enabled (defaults toworkflow_transitions
)dropdown_transitions_icon
: The dropdown button icon when there is transitions enabled (defaults tofa fa-code-fork
)transitions_default_icon
: The default transition icon for all transition (defaults tonull
: no icon)transitions_icons
: A hash with transition name as key and icon as value (defaults to[]
)
Let say that when you start a review for a pull request, as a user, you will be asked to enter which users are involved in the review.
To achieve this, you will be asked to fill a dedicated form.
You only need to create a custom controller for your entity admin :
# config/packages/sonata_admin.yml
services:
admin.pull_request:
class: App\Admin\PullRequestAdmin
public: true
arguments: [~, App\Entity\PullRequest, App\Admin\Controller\PullRequestController]
tags:
- { name: 'sonata.admin', manager_type: orm, label: PullRequest }
<?php
// src/Admin/Controller/PullRequestController.php
namespace App\Admin\Controller;
use App\Entity\PullRequest;
use App\Form\PullRequest\StartReviewType;
use Sonata\AdminBundle\Controller\CRUDController;
use Yokai\SonataWorkflow\Controller\WorkflowControllerTrait;
class PullRequestController extends CRUDController
{
use WorkflowControllerTrait;
protected function preApplyTransition($object, $transition)
{
switch ($transition) {
case 'start_review':
return $this->startReview($object);
}
return null;
}
protected function startReview(PullRequest $object, $transition)
{
$form = $this->createForm(
StartReviewType::class,
[],
[
'action' => $this->admin->generateObjectUrl(
'workflow_apply_transition',
$object,
['transition' => $transition]
),
]
);
$form->handleRequest($this->getRequest());
if (!$form->isSubmitted() || !$form->isValid()) {
$formView = $form->createView();
return $this->renderWithExtraParams('admin/pull-request/start-review.html.twig', [
'action' => 'edit',
'form' => $formView,
'object' => $object,
'objectId' => $this->admin->getNormalizedIdentifier($object),
], null);
}
$data = $form->getData();
// do something with the submitted data before returning null to continue applying transition
return null;
}
}
License can be found here.
The library was originally created by Yann Eugoné. See the list of contributors.
Thank's to Prestaconcept for supporting this library.