Writing a Received Forms Plugin

When building a custom integration in Form Builder, it is sometimes useful to display information relating to it in the Received Forms interface. For example, the system being integrated with may return a reference, which is useful to show customer service staff. Equally, it may be helpful to link the Received Form to another URL, to quickly access related information in the other system/

It is possible to display references and add links in Received Forms by creating a plugin. This is essentially a class, which tells Jadu Central where to get the necessary information to display from.

Taking the above example, imagine we have a form which submits data to a third party system, called ReceiptingSystem. This returns a reference, e.g. REF001. We know we can view data in that system, by visiting https://receiptingsystem.com/REF001.

To display this information in Received Forms, add a class file to your custom bundle, at CustomXFormsProBundle/IntegrationPlugins/ReceiptingSystemPlugin.php:

namespace Jadu\Custom\CustomXFormsProBundle\IntegrationPlugins;

use Jadu\XFormsPro\UserForm\IntegrationPlugin\AbstractIntegrationPlugin;

class ReceiptingSystemPlugin extends AbstractIntegrationPlugin
{
}

The class must extend AbstractIntegrationPlugin. To satisfy this abstract, we need to define the following methods:

    /**
     * Specifies all possible AbstractActionsMenuEntry objects for this plugin.
     *
     * No logic is needed here about which to display for a user form
     * AbstractActionsMenuEntry->show() handles this
     *
     * @param  UserForm $userForm
     *
     * @return AbstractActionsMenuEntry[]
     */
    public function loadActionMenuEntries($userForm)
    {
        return [new ReceiptingSystemActionMenuEntry($this->getReference($userForm))];
    }

    /**
     * Specifies all possible AbstractRibbonEntry objects for this plugin.
     *
     * No logic is needed here about which to display for a user form
     * AbstractRibbonEntry->show() handles this
     *
     * @return AbstractRibbonEntry[]
     */
    public function loadRibbonEntries()
    {
        return [new ReceiptingSystemRibbonEntry($this->reference)];
    }

loadActionMenuEntries stores the links from our Received Form; these will be placed under the Actions dropdown. loadRibbonEntries determines additional information that should be displayed on the ribbon. loadActionMenuEntries is called first, and is therefore responsible for getting the reference from the third party system. It does this by calling getReference:

    /**
     * @var string
     */
    protected $reference;

    /**
     * @var EntityManager
     */
    protected $entityManager;    

    /**
     * @param EntityManager $entityManager
     */
    public function __construct(
        EntityManager entityManager
    ) {
        $this->entityManager = $entityManager;
    }

    /**
     * @param  UserForm $userForm   
     * @return string
     */
    public function getReference(
        UserForm $userForm
    ) {
        $logRepo = $this->entityManager->getRepository('Jadu\XFormsPro\Form\Builder\UserFormActionLog');
        $logs = $logRepo->findBy([
            'userForm' => $userForm->getId(),
            'system' => 'ReceiptingSystem',
            'actionName' => 'Submit Data',
        ]);

        foreach ($logs as $log) {
            if (!is_null($log->getResult())) {
                $this->reference = $log->getResult();
                break;
            }
        }

        return $this->reference;
    }

This method will get all logs relating to 'ReceiptingSystem', and return the reference of the first one with a result. These logs would usually be written by a custom action.

That completes the plugin class. We now need to define ReceiptingSystemActionMenuEntry and ReceiptingSystemRibbonEntry.

Adding Action Menu Entries

Add another class to your custom bundle, at CustomXFormsProBundle/IntegrationPlugins/ReceiptingSystemActionMenuEntry.php:

namespace Jadu\Custom\CustomXFormsProBundle\IntegrationPlugins;

use Jadu\XFormsPro\UserForm\IntegrationPlugin\AbstractActionsMenuEntry;

class ReceiptingSystemActionMenuEntry extends AbstractActionsMenuEntry
{
    /**
     * Stores the reference returned from ReceiptingSystem
     * @var string
     */
    protected $reference;

    /**
     * @param  string $reference      
     */
    public function __construct($reference)
    {
        $this->reference = $reference;
    }

    /**
     * The label of the action menu item.
     *
     * @return string
     */
    public function getLabel()
    {
        return 'View Receipt';
    }

    /**
     * The URL the action menu item goes to.
     *
     * @param  UserForm $userForm
     *
     * @return string
     */
    public function getURL($userForm)
    {
        return 'https://receiptingsystem.com/'.$this->reference;
    }

    /**
     * Whether to show the menu entry.
     *
     * @param  UserForm $userForm
     *
     * @return bool
     */
    public function show($userForm)
    {
        return !empty($this->reference);
    }
}

The class must extend AbstractActionsMenuEntry. To satisfy this abstract, we need to define the following methods:

• getLabel (what is displayed in Actions)
• getURL (the URL the link goes to)
• show (whether to show the link, based on the submission)

We can optionally override the following:

• getIcon (the icon to show next to the link)

Adding Ribbon Entries

Add another class to your custom bundle, at CustomXFormsProBundle/IntegrationPlugins/ReceiptingSystemRibbonEntry.php:

namespace Jadu\Custom\CustomXFormsProBundle\IntegrationPlugins;

use Jadu\XFormsPro\UserForm\IntegrationPlugin\AbstractRibbonEntry;

class ReceiptingSystemRibbonEntry extends AbstractRibbonEntry
{
    /**
     * Stores the reference returned from ReceiptingSystem
     * @var string
     */
    protected $reference;

    /**
     * @param  string $reference      
     */
    public function __construct($reference)
    {
        $this->reference = $reference;
    }

    /**
     * The label of the action menu item.
     *
     * @return string
     */
    public function getLabel()
    {
        return 'Receipt';
    }

    /**
     * The content of the ribbon entry. Can contain HTML.
     *
     * @param  UserForm $userForm
     *
     * @return string
     */
    public function getContent($userForm)
    {
        return !empty($this->reference) ? $this->reference : '-';
    }

    /**
     * Whether to show the ribbon entry.
     *
     * @param  UserForm $userForm
     *
     * @return bool
     */
    public function show($userForm)
    {
        return !empty($this->reference);
    }
}

The class must extend AbstractActionsMenuEntry. To satisfy this abstract, we need to define the following methods:

• getLabel (what is displayed on the ribbon)
• getContent (the content in the ribbon entry)
• show (whether to show the ribbon entry, based on the submission)

Registering the Plugin

We then need to register it with Jadu Central as a Received Forms plugin. To do this, add the following at CustomXFormsProBundle/Resources/config/services.yml:

services:
    custom_xfp.integration_plugin.receipting_system:
        class: Jadu\Custom\CustomXFormsProBundle\IntegrationPlugin\ReceiptingSystemPlugin
        arguments:
            - "@doctrine.orm.entity_manager"
        tags:
            -  { name: xfp.integration_plugin }

note

The services: line is only needed once, at the beginning of the services.yml file.

The use of the tag is what tells Jadu Central that this class can be used to load data into Received Forms. Clear the Symfony cache of your development environment.