TasticFieldHandler

The standard data sources in Frontastic are contained in what we call streamTypes. For example, product-list and content are both streamTypes. If a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. is defined to retrieve a data sourcedata source - The data provided from an API to display products, content, or anything from an integration or extension. A data source filter is created and can be selected for a Frontastic component that will display the data source filter on your commerce site. of a certain streamType, it'll be provided with the corresponding data automatically at the time of rendering. You can extend this mechanism with a TasticFieldHandler to provide a custom streamType to a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. in a similar way.

📘

A TasticFieldHandler has previously been known as a custom field handler or a custom stream handler, but the class has always been TasticFieldHandler. A Tastic is the short name for a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. in code.

To provide a custom streamType, you'll need to follow the steps below to register the TasticFieldHandler in the Frontastic PHP stack:

1. Provide an implementation
   In order to handle the custom streamType, you'll need to provide an implementation of Frontastic\Catwalk\FrontendBundle\Domain\TasticFieldHandlerV3 which is the generalized interface for handling all field types and contains 2 methods:

namespace Frontastic\Catwalk\FrontendBundle\Domain;

use Frontastic\Catwalk\ApiCoreBundle\Domain\Context;

abstract class TasticFieldHandlerV3
{
    /**
     * @return string
     */
    abstract public function getType(): string;

    /**
     * @param mixed $fieldValue
     * @return mixed Handled value
     */
    abstract public function handle(Context $context, Node $node, Page $page, Tastic $tastic, $fieldValue);
}

The getType() method should return the type identifier for your streamType.

You must prefix streamTypes with your project ID in the form<project-id>-<streamType>, for example, awesomeshop-stores if your project is awesomeshop and your streamType will provide information about local stores.

The 2nd method handle() performs the actual work of handling your streamType. It's called by Frontastic as soon as a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. requires a data sourcedata source - The data provided from an API to display products, content, or anything from an integration or extension. A data source filter is created and can be selected for a Frontastic component that will display the data source filter on your commerce site. of your streamType.

As parameters, it receives the current application Context, Node, Page, Tastic, and the $fieldValue which was configured in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`..

🚧

We're still working on this feature. It's not yet possible to assign values to custom data sourcedata source - The data provided from an API to display products, content, or anything from an integration or extension. A data source filter is created and can be selected for a Frontastic component that will display the data source filter on your commerce site. fields in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. But even without this possibility, a custom streamType can be useful to provide data to a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code..

The handle() method is supposed to return the value of the data source that will then be given to the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. that required it. It can be an arbitrary value type except for 1 constraint: It must be serializable to JSON (that excludes, for example, resource types). Ideally, you'll return either:

• A simple data object
• An array of scalar values of simple array objects
• Null
• A combination of the above

You might notice that this is also called TasticFieldHandlerV3. If you previously implemented the TasticFieldHandler or TasticFieldHandlerV2 and it's not using V3, you can use the TasticFieldHandlerAdapter if you don't want to update to using V3.

2. Register your TasticFieldHandler
   Now that you've implemented your TasticFieldHandler for your streamType, you need to register it in the Symfony service container and apply a tag to it so it knows what it is.

To do this, go to your services.xml in one of your project bundles (if there isn't a bundle yet, you can create one using, for example, bin/console frontastic:create:bundle MyDecorators, see the Creating a backend bundle article for more information) and then add the tag frontend.tasticFieldHandler to it in a similar way to the below:

<service id="Frontastic\Customer\StorefinderBundle\Domain\StreamHandler">
     <argument type="service" id="Frontastic\Customer\StorefinderBundle\Domain\StorefinderService" />

     <tag name="frontend.tasticFieldHandler"/>
</service>

In this example, a TasticFieldHandler is registered for implementing a store finder. The implementation itself is rather slim and dispatches all work to a service. This gives you the possibility to unleash the full power of Frontastic, Symfony, and your own microservice APIs within a TasticFieldHandler.

3. Use the streamType
   Now you need to add your TasticFieldHandler to a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. schema. You must set the type to stream and then set the streamType to the type that you created in the first step, for example:

{
    "tasticType": "awesomeshop-store-finder",
    "name": "Storefinder",
    "category": "Awesome Shop",
    "icon": "store",
    "schema": [
          {
             "name": "General",
             "fields": [
                   {
                       "label": "Stores",
                       "field": "stream",
                       "type": "stream",
                       "streamType": "awesomeshop-stores",
                       "default": null,
                       "required": false
                   }
             ]
          }
    ]
}

Configure custom data sources

You can enable custom data sourcesData sources - The data provided from an API to display products, content, or anything from an extension. A data source filter is created and can be selected for a Frontastic component that will display the data source filter on your site. to be configurable in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. if you've had this feature enabled (contact our Support team if you'd like the customStreamConfig enabled).

To do this, follow the steps below.

For this example, we'll be implementing custom streamType of frontastic/weather, so our Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. schema would look like the below:

{
    //...  
        "label": "Weather Stream",
        "field": "weather",
        "type": "stream",
        "streamType": "frontastic/weather",
        "required": true
   //...   
}

1. Open the Frontastic studio, click Developer, and then Custom data sources

2. Create a schema file for your custom data source

🚧

The field value of customStreamType must match the streamType field from the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. schema.

{
    "customStreamType": "frontastic/weather",
    "name": "Weather",
    "category": "Content",
    "icon": "wb_sunny",
    "schema": [
        {
            "name": "Location",
            "fields": [
                {
                    "label": "Default city",
                    "field": "city",
                    "type": "string",
                    "default": "",
                    "translatable": false
                },
                {
                    "label": "Default country code",
                    "field": "country",
                    "type": "string",
                    "default": "DE",
                    "translatable": false
                }
            ]
        }
    ]
}

You'll see that we've added 2 fields (Default city and Default country code), these are the fields that are configurable when a Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. is added to a page and would look like the below:

The values configured here will be passed as the $fieldValue to the TasticFieldHandler.

3. Upload the schema file to the Frontastic studio by dragging it into the Custom data source screen or clicking the blue add icon

You can adjust some settings once you've uploaded a schema by clicking on the name of the schema

Accessing the request

❗️

We generally discourage accessing the request from a service, however, until we can offer a better way to access such information it can be used as a workaround.

Since a field handler is a normal Symfony service, you can get any service injected to dispatch work to. This also holds true for the RequestStack which allows you to get your hands on the currently processed request to access URL parameters and much more:

namespace Frontastic\Customer\StorefinderBundle\Domain;

use Symfony\Component\HttpFoundation\RequestStack;

use Frontastic\Catwalk\FrontendBundle\Domain\TasticFieldHandler;
use Frontastic\Catwalk\FrontendBundle\Domain\Stream;
use Frontastic\Catwalk\ApiCoreBundle\Domain\DataRepository;
use Frontastic\Catwalk\ApiCoreBundle\Domain\Context;
use Frontastic\Common\ProductApiBundle\Domain\ProductApi\Locale;

class StoresFieldHandler 
extends TasticFieldHandlerV3
{
     private $service;

     private $requestStack;

     public function __construct(StorefinderService $service, RequestStack $requestStack)
     {
    $this->service = $service;
    $this->requestStack = $requestStack;
     }

     public function getType(): string
     {
    return 'awesomeshop-stores';
     }

     public function handle(Context $context, Node $node, Page $page, Tastic $tastic, $fieldValue)
     {
    $locationId = $this->requestStack->getCurrentRequest()->get('location', null);
    if (!$locationId) {
         return null;
    }

    $locale = Locale::createFromPosix($context->locale);
    return $this->service->getStores($locale->territory, $locationId);
     }
}

In this example, the RequestStack is asked for the current request to fetch the URL parameter location. If this isn't set, the streamType contains nothing. Otherwise, the corresponding domain service is used to determine stores for the streamType.