How to work with result converters

This how-to guide will introduce you to the usage of result converters in your catalogue.

What are result converters?

Result converters are classes you can register in your template, which the catalogue will use in order to convert the export result according to your specifications. That way, the customer will be provided with a readable and ready-to-import file.

You can also use these converters to send the data to the marketplace, combining the conversion of the download data and the marketplace data in a single converter.

Creating result converters

To create a result converter from scratch, all you need to do is to extend the BaseResultConverter class and to define your own:

  • method: convertToDownload

  • method: convertToMarketplace

  • method: getKey

  • method: getLabel

  • const: CHUNK_SIZE, defaults to 50

  • const: MIME_TYPE, defaults to text/plain

  • const: FILE_EXTENSION, defaults to txt

Example:
We will partially use the default CSV converter as an example.

result-converters.php
```
<?php

namespace Your\Namespace\Here;

use Plenty\Modules\Catalog\Services\Collections\CatalogLazyCollection;
use Plenty\Modules\Catalog\Services\Converter\ResultConverters\BaseResultConverter;
use Plenty\Modules\Catalog\Services\FileHandlers\ResourceHandler;

/**
* Class CSVResultConverter
*/
class CSVResultConverter extends BaseResultConverter
{
   const CHUNK_SIZE = 50;
   const MIME_TYPE = 'text/csv';
   const FILE_EXTENSION = 'csv';

   /**
    * Converts to the user's download file
    *
    * @param CatalogLazyCollection $collection
    * @param ResourceHandler $resourceHandler
    */
   protected function convertToDownload(CatalogLazyCollection $collection, ResourceHandler $resourceHandler)
   {
       // Add each row
       $collection->each(function ($chunk) use ($resourceHandler) {
           foreach ($chunk as $row) {
               $resourceHandler->writeCSV($row, ',', '"');
           }
       });

   }


   /**
    * Converts to the marketplace export
    *
    * @param CatalogLazyCollection $collection
    * @return mixed
    */
   protected function convertToMarketplace(CatalogLazyCollection $collection)
   {
       $collection->each(function ($chunk) {
           // Send each chunk to the marketplace
       });

       return true;
   }

   /**
     * Will be used to identify the requested converter. Therefore it has to be unique in a specific template.
     *
     * @return string
     */
    public function getKey(): string
    {
        return 'csv';
    }

    /**
     * The string that will be visible to the user.
     *
     * @return string
     */
    public function getLabel(): string
    {
        return 'CSV';
    }
}
```

Using defaults

We provide defaults for some formats that you can extend, where you will only need to define your own convertToMarketplace method. If you need to customise the defaults you can override the convertToDownload method.

namespace Plenty\Modules\Catalog\Services\Converter\ResultConverters\Defaults

Using result converters

We set up the converter in order to store the export for the customer or to send it to the marketplace. However, we also need to provide it with the information which data we need to export.

To do that you can feed the converter with any of the following source types:

  • CatalogExportResult: returned by CatalogExportService’s getResult method

  • JSONL resource: returned by a cached result

  • Collection

You can get your result converter directly from the template.

Example:
.source-types.php

```
$exportRepository = pluginApp(CatalogExportRepositoryContract::class);
$converter = $template->getResultConverterContainer()->getResultConverter(YourResultConverter::KEY);

$result = $exportRepository->exportById($id)->getResult($id);

$converter->fromCatalogExportResult($result)
          ->toMarketplace();
```

If, for some reason you can’t access your template from the current scope, just instantiate your converter manually.

Example:
.source-types-without-template.php

```
$exportRepository = pluginApp(CatalogExportRepositoryContract::class);
$converter = pluginApp(YourResultConverter::class);

$result = $exportRepository->exportById($id)->getResult($id);

$converter->fromCatalogExportResult($result)
          ->toMarketplace();
```

If your converter requires any settings, you can pass them as an array to the setSettings method as shown below:

converter-settings.php
```
$converter->fromCatalogExportResult($result)
          ->setSettings(['key' => 'value'])
          ->toMarketplace();
```

You can also use a cached result to feed data to your converter:

cached-result.php
```
$exportRepository = pluginApp(CatalogExportRepositoryContract::class);
$converter = pluginApp(YourResultConverter::class);

$collection = $exportRepository->getDevCachedResult($id);

$converter->fromCatalogLazyCollection($collection)
          ->toMarketplace();
```

Registering your result converters in your template

In your template, you can register result converters as shown below. Note that you can exchange ResultConverterContainer for DefaultResultConverterContainer to enable all predefined converters in your template.

register-converter.php
```
use Plenty\Modules\Catalog\Services\Converter\Containers\ResultConverterContainer;
use Plenty\Modules\Catalog\Services\Converter\ResultConverters\Defaults\CSVResultConverter;

class MarketplaceTemplateDataProvider extends AbstractGroupedTemplateProvider
{
    ...

    /**
     * @return ResultConverterContainer
     */
    public function getResultConverterContainer(): ResultConverterContainer
    {
        /** @var ResultConverterContainer $container */
        $container = pluginApp(ResultConverterContainer::class);
        /** @var CSVResultConverter $csvConverter */
        $csvConverter = pluginApp(CSVResultConverter::class);
        $container->addResultConverter($csvConverter);

        return $container;
    }
}

Once you have registered your result converters, the user can select them in the Format drop-down list in the catalogue settings and the catalogue module will be able to build the file for the user using your specifications in the convertToDownload method.