Adding a Form Variable

A form variable is a placeholder for a specific piece of information about a form submission, which can be used in instructions text or integrations. Wherever the variable is used, it is replaced with the proper value for the current submission.

Form Builder provides lots of form variables, such as:

Form Title
User's Full Name
Form Channel
Payment Reference

It is possible to add in your own variables, to allow access to other useful pieces of information about the form submission.

Example: Accessing a Custom Integration's Reference

Imagine we have a form which sends data to a third party system called ReceiptingSystem, and receives a reference in return. We can provide a custom variable to access the reference, so we can send it to the back office in an email.

First, add a class file to your custom bundle, at CustomXFormsProBundle/VariableDefinitions/ReceiptingSystemReferenceDefinition.php.

All custom clause types must extend the AbstractVariableDefinition.

namespace Jadu\Custom\CustomXFormsProBundle\VariableDefinitions;

use Jadu\XFormsPro\Form\Builder\Variable\AbstractVariableDefinition;

class ReceiptingSystemReferenceDefinition extends AbstractVariableDefinition
{
}

To satisfy the abstract, we should implement the following method in our class:

    /**
     * @param UserForm the current UserForm object
     *
     * @return string the value of this variable
     */
    protected function evaluate($userForm)
    {
        // $entityManager is set on the Abstract
        $logRepo = $this->entityManager->getRepository('Jadu\XFormsPro\Form\Builder\UserFormActionLog');

        $logs = $logRepo->findBy([
            'userForm' => $userForm->getId(),
            'system' => 'ReceiptingSystem',
            'actionName' => 'Submit Data',
        ], ['id' => 'ASC']);

        foreach ($logs as $log) {
            if (!empty($log->getResult())) {
                return $log->getResult();
            }
        }

        return null;
    }

The evaluate method gets the reference using the user form. In this case, we 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.

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

services:
    custom_xfp.variables.receipting_system_reference:
        class: Jadu\Custom\CustomXFormsProBundle\VariableDefinitions\ReceiptingSystemReferenceDefinition
        arguments:
            - "@doctrine.orm.entity_manager"
        tags:
            -  { name: xfp.form_variable_definition, label: 'Custom - ReceiptingSystemReference' }

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 as a form variable, and what the variable is called. Clear the Symfony cache of your development environment.

Example: Accessing a Custom Integration's Reference​

Example: Accessing a Custom Integration's Reference