Example Predefined Logic

In this example you will develop a predefined calculation that will add two fields together. This is a simple example that can be achieved without using predefined calculations but it will help illustrate the process of developing a predefined calculation.

The formula for this calculation will be this:

[Response - QuestionOne] + [Response - QuestionTwo]

This could be also be achieved using standard mathematical calculations using the formula above.

Step 1: Create The Calculation Class

Begin by creating a new namespaced PHP class that extends AbstractCalculation. A use statement has also been included for brevity.

    namespace Jadu\Custom\XFP\Calculation;

    use Jadu\XFormsPro\Form\Calculation\AbstractCalculation;

    class AddTwoFieldsCalculation extends AbstractCalculation
    {

    }

Step 2: Add The Class Properties

Add two protect class properties, these will map to the two from questions that will be be added together. Jadu Central treats all form answers as strings and the properties are typed as such, they will be cast to numeric in the calculation logic.

    namespace Jadu\Custom\XFP\Calculation;

    use Jadu\XFormsPro\Form\Calculation\AbstractCalculation;

    class AddTwoFieldsCalculation extends AbstractCalculation
    {
        /**
         * The first field to add
         * @var string
         */
        protected $fieldOne;
        /**
         * The second field to add
         * @var string
         */
        protected $fieldTwo;
    }

Step 3: Implement Abstract Methods

The abstract class AbstractCalculation has two abstract methods that need to be implemented.

Begin by implementing the mapVariables method, this method defines which class properties will be mapped to form questions in the control centre.

Use the helper method setVariableMapping to define the mapping between class property and the option in the control centre. The first argument is the user friendly name shown to the user in the control centre and the second argument is the name of the class property.

    /**
     * Map fieldOne and fieldTwo, and give both a friendly name
     */
    public function mapVariables()
    {
        $this->setVariableMapping('First field', 'fieldOne');
        $this->setVariableMapping('Second field', 'fieldTwo');
    }

Now implement the calculate method. This method contains the logic for the calculation. In this case, cast both fields to integers, and then return the value.

    /**
     * Add fieldOne to fieldTwo
     * @return int
     */
    public function calculate()
    {
        return intval($this->fieldOne) + intval($this->fieldTwo);
    }

The final method to implement is getHelpText. This should be a short description of what the calculation does and is shown to the control centre user.

    /**
     * Returns help text describing the calculation
     * @return string
     */
    public function getHelpText()
    {
        return "This calculation returns the result of adding the integer values of <strong>First Field</strong> and <strong>Second Field</strong>";
    }

Complete Class File

Your completed class file should look like the class file below

    namespace Jadu\Custom\XFP\Calculation;

    use Jadu\XFormsPro\Form\Calculation\AbstractCalculation;

    class AddTwoFieldsCalculation extends AbstractCalculation
    {
        /**
         * The first field to add
         * @var string
         */
        protected $fieldOne;
        /**
         * The second field to add
         * @var string
         */
        protected $fieldTwo;

        /**
         * Map fieldOne and fieldTwo, and give both a friendly name
         */
        public function mapVariables()
        {
            $this->setVariableMapping('First field', 'fieldOne');
            $this->setVariableMapping('Second field', 'fieldTwo');
        }

        /**
         * Add fieldOne to fieldTwo
         * @return int
         */
        public function calculate()
        {
            return intval($this->fieldOne) + intval($this->fieldTwo);
        }

        /**
         * Returns help text describing the calculation
         * @return string
         */
        public function getHelpText()
        {
            return "This calculation returns the result of adding the integer values of <strong>First Field</strong> and <strong>Second Field</strong>";
        }
    }

To satisfy the namespace, this class should be placed inside /path/to/jadu/jadu/custom/XFP/Calculation.

Step 4: Register Calculation With Jadu Central

Finally you need to add a record to the JaduXFormsCalculations table.

Write an SQL query for the predefined calculation such as the query below:

INSERT INTO JaduXFormsCalculations(name, className, guid) VALUES ('Custom - Add Two Fields', 'Jadu\\Custom\\XFP\\Calculation\\AddTwoFieldsCalculation', '92a23888262ad5e61e844e424d45682d7ecd121c');

note

This query contains double backslashes in the namespace, as a single backslash is seen as an escape character.

The value of the guid field is calculated by doing a sha1 of the class name.

After the record is added to the database successfully, the cache for JaduXFormsCalculations should be cleared.

Update Autoloader

If this is your first custom development you may need to update the autoloader so it is aware of your new classes. Refer to updating autoloader path for instructions on updating the autoloader paths.

Finishing up

Once you have completed steps 1 - 4 you should have a new predefined calculation in the control centre that can be used by your form creators.