Creating a Predefined Logic

Jadu Central allows developers to create predefined calculations as an alternative to manually entering a formula when setting up a Logic on a form. There are two main benefits of creating predefined calculations:

• Easy to reuse - custom predefined calculations will be available on every form. They can also take in multiple arguments (such as answers provided, or static text), so the same calculation can be configured to behave in different ways.

• Powerful - a predefined calculation is essentially a PHP class, so it has the ability to do anything you can do in PHP. This makes predefined calculations really useful for pulling back data from an API, and surfacing it in your form.

note

Developing predefined calculations requires knowledge of PHP, as well as access to the server and database in order to install the finished calculation.

Writing a custom predefined calculation

All custom predefined calculations must take the form of a namespaced class. This class must extend Jadu\XFormsPro\Form\Calculation\AbstractCalculation.

AbstractCalculation is an abstract class that contains 10 methods (7 Concrete / 3 Abstract).

Scope	Method	Description
public	__construct($data = array())	Constructor
public	getVariableMappings	This method returns an array of mappings between form variables and subclass properties
protected	setVariableMapping($friendlyName, $variableName)	This method updates the internal array of form variable mappings to subclass properties
public	execute	This method is called from within the form logic and executes the calculation, this method is final and cannot be overwritten in your subclass.
public	mapVariables	This is an abstract method and needs to be implemented in your subclass.
public	calculate	This is an abstract method and needs to be implemented in your subclass.
public	getHelpText	This is an abstract method and needs to be implemented in your subclass.
public	getMappingOptions	This method defaults to an empty array, and can be overridden your subclass.
public	getMultipleChoiceFields	This method defaults to an empty array, and can be overridden your subclass.
public	supportsLegacy	This method defaults to true. If your logic should not be available in legacy forms, override this in your subclass to return false.

The mapVariables function

When writing a mathematical calculation formula, we can use form variables such as '[Response - Question]' to get the user response for a specific question. Predefined calculations are reusable across different forms, pages and questions therefore it is not possible to use a specific question's placeholder in the formula. Instead, predefined calculations provide the ability to map a question or enter a static value to a class variable, which can then be used during the evaluation of the calculation formula.

mapVariables is used to determine which class variables require a mapping, and to provide friendly names for these mappings when adding the calculation to a form. This method should contain one or more calls similar to:

$this->setVariableMapping('Question', 'question');

The setVariableMapping function is a method in AbstractCalculation. The above code when used in a custom predefined calculation on a form will instruct the application to ask the user creating the form to map form questions to the calculation. The value we map will be stored in $this->question (from the second argument). Our calculation will need to contain a class variable called $question, which should have protected visibility.

If your calculation does not require any mappings, this function can be left empty.

The getMappingOptions function

When specifying inputs that your predefined calculation will accept, sometimes it is desirable to specify the possible options for an input. This could be useful if we want to load our options from an API, or if we want to restrict the possible inputs, e.g. 1-5.

In the example below, the getMappingOptions() function returns an array, with one index, fieldA. This is one of the inputs specified in mapVariables. At this index, there is an array of key/value pairs.

When configuring a Logic using this formula, the application will now display the input for fieldA as a dropdown containing 'One', 'Two' and 'Three', which will have values '1', '2' and '3' respectively.

    public function getMappingOptions()
    {
        return [
        	'fieldA' => [
        		'1' => 'One',
        		'2' => 'Two',
        		'3' => 'Three'
        	]
        ];
    }

note

If you choose not to override this function in your class, all inputs will offer core selection dropdowns, which allow the user to choose from questions on the form, form variables or static text entry.

The getMultipleChoiceFields function

When specifying inputs that your predefined calculation will accept, sometimes an input may need to contain multiple values. This may be specifying a range of valid values to check a field against.

To do this, implement getMultipleChoiceFields(), to return an array containing the name of the input field(s) which should allow multiple values. These fields will be rendered as a select2, so staff members can type in as many values as necessary.

    public function getMultipleChoiceFields()
    {
        return [
            'fieldA'
        ];
    }

note

Any input fields that are defined in both getMultipleChoiceFields() and getMappingOptions() will render as select2s. The options provided for these in getMappingOptions() will be ignored.

The calculate function

This is the function responsible for evaluating and returning a value for the calculation. When this function begins execution, the mapped class variables have their correct values, and can be used to help obtain the result. The result of the calculation should be returned from this function.

note

This function can contain the logic of the calculation in its entirety, or can be used as a starting point for more complex logic, involving multiple different objects. However this function must always return the result.

The getHelpText function

This is the simplest of the three abstract functions, and is used to provide help text for administrators when they attempt to set up the calculation on a form.

The help text should describe:

• what the calculation does
• how any mapped fields will be used in the calculation
• the possible returned values from the calculation

This function should return a string, but this may contain html, such as bold tags or line breaks.

Adding the calculation to the database

Once the calculation class is complete, a corresponding record must be added to the database table JaduXFormsCalculations, in order to register the calculation with Jadu Central.

The table below describes the fields the record will need to provide, and their purpose.

| Field | Data type | Purpose | |-:-|-:-|-:-| | id | integer | This is an auto-incremented number, and will be populated by the database when the record is inserted. | | name | string | The name of the calculation, as it should appear in the Control Center. Spaces can be used. | | className | string | The path to the class file of the calculation. This should match the namespace of the class. | | guid | string | A SHA1 hash of the className field. |

note

Jadu strongly recommend that all database alterations are performed using Doctrine Database Migrations, as this maintains compatibility with Meteor, Jadu's patching tool.

Once added correctly, your new calculation should be visible when choosing a Predefined Logic in Form Builder.