Translating Values from APIs

When integrating with a third party system, it is sometimes useful to transform values from this system into customer-friendly values for displaying on a form.

Jadu Central provides a Dictionary interface where administrators can configure these transformations. When developing integrations, you will need to complete the following steps to use the strings configured within the Dictionary.

Step One: Register your system with the Dictionary

First, create a new class to specify information for about system:

namespace Jadu\Custom\CustomXFormsProBundle\SystemDefinition;

use Jadu\XFormsPro\Bundle\DictionaryBundle\SystemDefinition\DictionarySystemDefinitionInterface;

class TestSystemDefinition implements DictionarySystemDefinitionInterface
{
    /**
     * The display name of this system.
     *
     * @return string
     */
    public function getFriendlyName()
    {
        return 'Test System';
    }
}

Next, add the following to your CustomXFormsProBundle/Resources/config/services.yml file:

services:
    custom_xformspro.testsystem.system_definition:
        class: Jadu\Custom\CustomXFormsProBundle\SystemDefinition\TestSystemDefinition
        tags:
            -  { name: xfp_dictionary.system_definition }

This registers your new system definition with the Dictionary.

note

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

Finally, you will need to clear the Symfony cache.

You should now see your "Test System" as a System option when adding a new entry to the Dictionary.

Step Two: Translate strings within your code

Once your system is registered with the Dictionary, and matches have been set up, your code will need to use those matches to translate API response values.

You can use the Dictionary repository (Jadu\XFormsPro\Bundle\DictionaryBundle\Repository\DictionaryEntryRepository) to find matches for values.

First, inject the service xfp_dictionary.repository.dictionary_entry into your class:

my_service:
   class: ...
   arguments:
       - ...
       - "@xfp_dictionary.repository.dictionary_entry"

use Jadu\XFormsPro\Bundle\DictionaryBundle\Repository\DictionaryEntryRepository;

class MyServiceClass
{
    /* ... */

    /**
     * @var DictionaryEntryRepository
     */
    private $dictionaryRepository;

    public function __construct(
        /* ... */
        DictionaryEntryRepository $dictionaryRepository
    ) {
        /* ... */
        $this->dictionaryRepository = $dictionaryRepository;
    }

    /* ... */
}

The DictionaryEntryRepository class provides the findMatch() method to lookup values in the Dictionary.

$apiValue = $myApi->getValue();

$dictionaryEntry = $this->dictionary->findMatch(
    'TestSystem',
    $apiValue
);

// Fallback to the response from the API if a match is not found
$value = $apiValue;

if ($dictionaryEntry instanceof DictionaryEntry) {
    // A match is in the dictionary
    $label = $dictionaryEntry->getLabel();
    $value = $label;

    if (!empty($dictionaryEntry->getValue())) {
        $value = $dictionaryEntry->getValue();
    }
}