Calculated Fields Form Blog

Blog / Third-Party Connection Module

Third-Party Connection Module

The Third-Party Connection Module allows to use from the form external APIs whose responses are usually asynchronous.

---

The "Calculated Fields Form" plugin provides a wide variety operations to face dissimilar kind of projects, however there are specific task that requires the integration with external services, for example, the integration with the exchange rate APIs to get real time rates, the integration with transportation APIs, Text management APIs, Financial APIs, etc.

The most of these APIs respond asynchronously, What this mean? Your form will call to these APIs, but they responses are not immediate, and would be required some mechanism in the equations for using the APIs responses when they be available.

To allow the integration with external asynchronous services the Third-Party Connection module includes the cffProxy operation.

The cffProxy requires at least one parameter that must be a function. The other parameters passed to the cffProxy operation would be passed as parameter to the required function (the function passed as the first parameter).

For example, in the following code:

cffProxy(my_function, 'a', 5)

The second and third parameters of the cffProxy operation (the 'a' character and the 5 number) would be passed as the first and second parameters of the my_function function.

Furthermore, the function passed as the first parameter of the cffProxy operation (my_function) should to accept a *callback* as the last parameter, that should be called from the code of the function passing to it the definitive result.

For example:

cffProxy(function(a,b, callback){callback(a+b);}, 5, 6)

If you enter the previous code as the equation associated to a calculate field, the equation's result (and value of the calculated field) would be 11

The previous code is very simple, we will create now more complex equations that reveal the real power of this operation.

Real time exchange rate

Assuming there is a currency field in the form (I'll call it fieldname1) and two DropDown fields for selecting the currencies' codes (fieldname2 and fieldname3 respectively), and you want to convert the value entered by the user to the new currency, using the Foreign exchange rates API:

The equation associated to the calculated field to get the result would be:

(function(){
        function exchangeRateProcessing(_from, _to, _callback)
        {
            jQuery.ajax({
            url: 'https://api.exchangeratesapi.io/latest?base='+_from+'&symbols='+_to,
                dataType: 'json',
                crossDomain: true,
                success: function(result) {
                    _callback(result.rates[_to]);
                }
            });
        };
        return fieldname1*cffProxy(exchangeRateProcessing, fieldname2, fieldname3);
})()

The equation's code seems complex, so, I'll try to describe it:

return fieldname1*cffProxy(exchangeRateProcessing, fieldname2, fieldname3);

This line of code takes the price entered by the user (fieldname1) and multiply it by the exchange rate between the currencies selected through the "From" (fieldname2) and "to" (fieldname3) fields.

The code that reads the exchange rate from the external function is defined in the exchangeRateProcessing function passed as the first parameter of cffProxy.

As you can see exchangeRateProcessing accepts three parameters, in this case the "from" and "to" currencies, and the callback function.

This function uses jQuery.ajax for reading the exchange rate from the https://api.exchangeratesapi.io/ website, and then, after receive the information from the external website, it call the callback function, passing to it the exchange rate as its parameter:

_callback(result.rates[_to]);

Another practical example:

Get the European VAT

In this new form there is a dropdown field (fieldname1) with the list of European countries, where the choices' texts contain the countries' names, and their values the countries' codes. For example ES for Spain, HU for Hungary, LV for Latvia, etc.

The structure of the URL for the external service are: https://taxtools.io/api/188.226.197.55/rates/country-code, where the country-code component should be replaced by the country code selected through the fieldname1 field, for example, https://taxtools.io/api/188.226.197.55/rates/ES corresponds to Spain.

The VAT field is a calculated field that will contain the standard VAT corresponding to the selected country. The equation associated to this calculated field would be:

(function(){
        function getVAT(callback)
        {
            jQuery.ajax({
                url: 'https://taxtools.io/api/188.226.197.55/rates/'+fieldname1+'?callback=?',
                dataType: 'jsonp',
                success: function(result) {
                callback(result.tax.standard);
                }
            });
        };
        return cffProxy(getVAT);
})()

Now, you can use the VAT field to increase the price of the service depending on the country of payer.

The possibilities are huge. You can use the cffProxy operation for reading the information of hundred of services, or integrate with your forms hundred of APIs.