Catalog

This tutorial will introduce you to the catalog export. We will develop a small plugin that exports variations to a fictional marketplace. You will learn how to create and work with a catalog to allow your users to map their data to a predefined format. If you are just getting started developing plugins for plentymarkets it is recommended to start with establishing your IDE and creating your first plugin

Tutorial content

• What is a catalog?
• Using catalogs in a plugin

Tutorial result

At the end of this tutorial you will have developed a plugin that exports variations in the format of a fictional marketplace. In the UI the result will look like this

The complete source code for this tutorial is available here.

Creating the folders

                BasicCatalogExport/
                    ├── src/
                    │   ├── Controllers/
                    │   │   └── VariationExportController.php
                    │   │
                    │   ├── DataProviders/
                    │   │   ├── FirstBaseDataProvider.php
                    │   │   ├── FirstKeyDataProvider.php
                    │   │   └── FirstNestedKeyDataProvider.php
                    │   │
                    │   ├── Providers/
                    │   │    ├── BasicCatalogExportServiceProvider.php
                    │   │    ├── BasicCatalogExportRouteServiceProvider.php
                    │   │    ├── BasicCatalogExportTemplateProvider.php
                    │   │    └── CatalogBootServiceProvider.php
                    │   │
                    │   └── Services/
                    │       └── VariationExportService.php
                    │
                    └── plugin.json // plugin information
            

What is a catalog?

Before we can start to develop a plugin that uses the catalog, we first need to clarify what a catalog actually is and of which components it consists of. A catalog describes the relation between source data in plentymarkets and a specific export format. The format is predefined by a template. This template is created by the plugin developer and can be used to create a new catalog in the plentymarkets backend. The actual data can then be mapped individually by the user of the plugin. A plugin needs to define the following components to work with a catalog:

• Data providers
• Templates

The structure of a catalog roughly looks like this:

Data providers

Templates

Using catalogs in a plugin

To make the concept of a catalog a bit more comprehensible we will develop the plugin with a simplified data format for a fictional marketplace. The marketplace expects the following format for its articles:

{
    “name”: string
    “description”: string,
    “sku”: string
    “price”: float,
    “stockNet”: int,
    “brand”: enum(brand1, brand2, brand3),
    “categories”: array(int)
}

The fields name, price, stock, sku and categories are required. The categories field expects ids. The full list of categories of the marketplace looks like the following:

[
    {
        "id": 1,
        "label": "Men"
        "parentId": null
        "children": [
            3
        ]
    },
    {
        "id": 2,
        "label": "Women"
        "parentId": null
        "children": [
            4
        ]
    },
    {
        "id": 3,
        "label": "Shoes"
        "parentId": 1
        "children": []
    },
    {
        "id": 4,
        "label": "Shoes"
        "parentId": 2
        "children": []
    }
]

Since the target format is known now we can start to design the data providers. To use the catalog correctly it is important to understand when to use which data provider. Currently there are 3 different types:

• The BaseDataProvider, which is used for simple mappings
• The KeyDataProvider, which is used for mappings with non encapsulated data (e.g. brands)
• The NestedKeyDataProvider, which is used for mappings with encapsulated data (e.g. categories)

Data providers

Base data provider

<?php

use Plenty\Modules\Catalog\DataProviders\BaseDataProvider;

class FirstBaseDataProvider extends BaseDataProvider
{
    /**
    * @return array
    */
    public function getRows(): array
    {
        // TODO: Implement getRows() method.
    }
}

[
    'key' => 'price',
    'label' => 'Price', //In your plugin it would make sense to add translations for this field, since it will be displayed in the UI
    'required' => true
]

/**
* @return array
*/
public function getRows(): array
{
    return [
        [
            'key' => 'name',
            'label' => 'Name',
            'required' => true
        ],
        [
            'key' => 'description',
            'label' => 'Description',
            'required' => false
        ],
        [
            'key' => 'sku',
            'label' => 'SKU',
            'required' => true
        ],
        [
            'key' => 'price',
            'label' => 'Price',
            'required' => true
        ],
        [
            'key' => 'stockNet',
            'label' => 'Stock',
            'required' => true
        ]
    ];
}

Key data provider

<?php

namespace BasicCatalogExport\DataProviders;

use Plenty\Modules\Catalog\DataProviders\KeyDataProvider;

/**
 * Defines fields for a mapping
 *
 * Class FirstKeyDataProvider
 * @package BasicCatalogExport\DataProviders
 */
class FirstKeyDataProvider extends KeyDataProvider
{
    /**
     * @return array
     */
    public function getRows(): array
    {
        // TODO: Implement getRows() method.
    }

    /**
     * @return string
     */
    public function getKey(): string
    {
        // TODO: Implement getKey() method.
    }
}

/**
* @return string
*/
public function getKey(): string
{
    return 'brand';
}

/**
* @return array
*/
public function getRows(): array
{
    return [
        [
            'value' => 'brand1',
            'label' => 'A brand'
        ],
        [
            'value' => 'brand2',
            'label' => 'Another brand'
        ],
        [
            'value' => 'brand3',
            'label' => 'The third brand'
        ],
    ];
}

Nested key data provider

<?php

namespace BasicCatalogExport\DataProviders;

use Plenty\Modules\Catalog\DataProviders\NestedKeyDataProvider;

/**
 * Define fields for a mapping that will be displayed as a tree in the UI
 *
 * Class FirstNestedKeyDataProvider
 * @package BasicCatalogExport\DataProviders
 */
class FirstNestedKeyDataProvider extends NestedKeyDataProvider
{

    /**
     * @return array
     */
    public function getRows(): array
    {
        // TODO: Implement getRows() method.
    }

    /**
     * @param string $id
     * @return array
     */
    public function getDataByValue(string $id): array
    {
        // TODO: Implement getDataByValue() method.
    }

    /**
     * @return string
     */
    public function getKey(): string
    {
        // TODO: Implement getKey() method.
    }

    /**
     * @return array
     */
    public function getNestedRows($parentId): array
    {
        // TODO: Implement getNestedRows() method.
    }
}

The NestedKeyDataProvider behaves a lot like the KeyDataProvider, but it enables the catalog UI to work with encapsulated data. The getKey() method is identical to the method in the KeyDataProvider, so in our case it just returns "categories", however since we may sell our articles in multiple categories (e.g. unisex shoes will be sold in Men >> Shoes and Women >> Shoes) we can define the key as an array (this behavior is identical with keys in all types of data providers). To do that we just have to add [] at the end of the key. So we return "categories[]"

A NestedKeyDataProvider needs to be able to do 3 things. It has to be able to show all values on the highest level, which in our case means it has to return all values that have no parentId, it has to be able to load all child values of a given parent and it has to be able to load values by the ID.

Let's take a look at the code for our example:

<?php

namespace BasicCatalogExport\DataProviders;

use Plenty\Modules\Catalog\DataProviders\NestedKeyDataProvider;

/**
 * Define fields for a mapping that will be displayed as a tree in the UI
 *
 * Class FirstNestedKeyDataProvider
 * @package BasicCatalogExport\DataProviders
 */
class FirstNestedKeyDataProvider extends NestedKeyDataProvider
{
    protected $categories = [
        1 => [
            'id' => 1,
            'label' => 'Men',
            'hasChildren' => true,
            'level' => 0,
            'children' => [3]
        ],
        2 => [
            'id' => 2,
            'label' => 'Women',
            'hasChildren' => true,
            'level' => 0,
            'children' => [4]
        ],
        3 => [
            'id' => 3,
            'label' => 'Shoes',
            'level' => 1,
            'hasChildren' => false
        ],
        4 => [
            'id' => 4,
            'label' => 'Shoes',
            'level' => 1,
            'hasChildren' => false
        ],
    ];

    /**
     * @return array
     */
    public function getRows(): array
    {
        $rows = [];
        foreach ($this->categories as $row) {
            if (isset($row['level']) && $row['level'] == 0) {
                $rows[] = [
                    'label' => $row['label'],
                    'value' => $row['id'],
                    'hasChildren' => $row['hasChildren']
                ];
            }
        }

        return $rows;
    }

    /**
     * @param string $id
     * @return array
     */
    public function getDataByValue(string $id): array
    {
        if (!isset($this->categories[$id])) {
            return [];
        }

        $category = [
            'label' => $this->categories[$id]['label'],
            'value' => $this->categories[$id]['id'],
            'hasChildren' => $this->categories[$id]['hasChildren'],
        ];

        return $category;
    }

    /**
     * @return string
     */
    public function getKey(): string
    {
        return 'categories[]';
    }

    /**
     * @param $parentId
     * @return array
     */
    public function getNestedRows($parentId): array
    {
        $rows = [];

        if (isset($this->categories[$parentId]) && isset($this->categories[$parentId]['children'])){
            foreach ($this->categories[$parentId]['children'] as $categoryId) {
                $rows[] = [
                    'label' => $this->categories[$categoryId]['label'],
                    'value' => $this->categories[$categoryId]['id'],
                    'hasChildren' => $this->categories[$categoryId]['hasChildren']
                ];
            }
        }

        return $rows;
    }
}

As you can see this one is certainly a bit more complex than the others, so let's look at all the methods independently to clarify what this class is doing. In this example we created a protected property that contains all categories hardcoded in an array. This works fine in this example but should be exchanged for better solutions if bigger amounts of data are provided (e.g. a database table).

Let's go through in order. The first method is getRows(). This method is supposed to provide all entries that are found on the highest level of the nested data. In our case all categories the marketplace provided that have no parentId have to be returned. To do that a "level" key was added to the array so all necessary categories are easily identifiable.

The next method is getDataByValue() and is responsible for loading already mapped values in the UI. This method expects an identifier (in most cases this will be an ID) and has to return the data entry that matches this identifier. In the example that is pretty easy to accomplish since the array key is always matching the ID.

The getKey() method is serving the exact same purpose as in the KeyDataProvider and therefore just returns the key under which the mapped values will be exported.

The last method we need to cover is the getNestedRows() method. It is used by the UI to load nested data in the tree by providing the parentId. So this method needs to return the children of that parent. In our example that is done by iterating over the "children" property of the parent entry.

That covers all the basics of data providers and therefore we are now ready to link them to a template.

Registering a template

<?php

namespace BasicCatalogExport\Providers;

use BasicCatalogExport\DataProviders\FirstBaseDataProvider;
use BasicCatalogExport\DataProviders\FirstKeyDataProvider;
use BasicCatalogExport\DataProviders\FirstNestedKeyDataProvider;
use Plenty\Modules\Catalog\Templates\BaseTemplateProvider;

/**
 * Class BasicCatalogExportTemplateProvider
 * @package BasicCatalogExport\Providers
 */
class BasicCatalogExportTemplateProvider extends BaseTemplateProvider
{
    /**
     * @return array
     */
    public function getMappings(): array
    {
        return [
            [
                'identifier' => 'simpleMapping',
                'label' => 'Base data',
                'isMapping' => false, // simple mapping
                'provider' => FirstBaseDataProvider::class,
            ],
            [
                'identifier' => 'complexMapping',
                'label' => 'Key data',
                'isMapping' => true, // complex mapping
                'provider' => FirstKeyDataProvider::class,
            ],
            [
                'identifier' => 'complexNestedMapping',
                'label' => 'Nested key data',
                'isMapping' => true, // complex mapping
                'provider' => FirstNestedKeyDataProvider::class,
            ]
        ];
    }

    /**
     * @return array
     */
    public function getFilter(): array
    {
        return [];
    }

    /**
     * @return callable[]
     */
    public function getPreMutators(): array
    {
        return [];
    }

    /**
     * @return callable[]
     */
    public function getPostMutators(): array
    {
        return [];
    }

    /**
     * @return callable
     */
    public function getSkuCallback(): callable
    {
        return function ($value, $item) {
            return $value;
        };
    }

    /**
     * @return array
     */
    public function getSettings(): array
    {
        return [];
    }

    /**
     * @return array
     */
    public function getMetaInfo(): array
    {
        return [];
    }
}

<?php

namespace BasicCatalogExport\Providers;

use Plenty\Modules\Catalog\Contracts\TemplateContainerContract;
use Plenty\Plugin\ServiceProvider;

class CatalogBootServiceProvider extends ServiceProvider
{
    /**
     * @param TemplateContainerContract $container
     */
    public function boot(TemplateContainerContract $container) {
        // Creating a new template, The provider class is responsible for the booting process
        $container->register(BasicCatalogExportServiceProvider::PLUGIN_NAME, 'exampleType', BasicCatalogExportTemplateProvider::class);
    }
}

Exporting variations through a catalog

    public function export(
        CatalogRepositoryContract $catalogRepository,
        CatalogExportRepositoryContract $catalogExportRepository,
        TemplateContainerContract $templateContainer
    )
    {
        $catalogs = $catalogRepository->all();

        foreach ($catalogs->getResult() as $catalog) {
            $template = $templateContainer->getTemplate($catalog['template']);

            if ($template->getName() != BasicCatalogExportServiceProvider::PLUGIN_NAME) {
                continue;
            }

            $exportService = $catalogExportRepository->exportById($catalog['id']);
            // Here you can define filters etc. if needed
            $result = $exportService->getResult();
            foreach ($result as $page) {
                //$page now contains the data of the export
                return $page;
            }
        }
        return null;
    }