9. Developer corner

Target group: Developers

Modify data sets on synchronisation

New in version 1.0.0.

The records that are synchronised with the table types Simple synchronisation or Synchronisation in custom table can be adapted to the needs of the website or rejected during synchronisation. This can be useful if only records with a date column are used where the date is relevant in the future. Another scenario would be to match the content of one column with the content of another table.

Example

A PSR-14 event listener can be used for this case. In the following example, a record is rejected under a certain condition and a static string is added to each “position” column value.

  1. Create the event listener

    <?php
       declare(strict_types=1);
    
       namespace YourVendor\YourExtension\EventListener;
    
       use Brotkrueml\JobRouterData\Event\ModifyDatasetOnSynchronisationEvent;
    
       final class AdjustJobsDataset
       {
          public function __invoke(ModifyDatasetOnSynchronisationEvent $event): void
          {
             // Only the table with the handle "jobs" should be considered
             if ($event->getTable()->getHandle() !== 'jobs') {
                return;
             }
    
             $dataset = $event->getDataset();
             if ($dataset['jrid'] === 3) {
                // For some reason we don't like jrid = 3, so we reject it
                // and it doesn't get synchronised
                $event->setRejected();
             }
    
             $dataset['POSITION'] .= ' (approved by me™)';
             $event->setDataset($dataset);
          }
       }
    
  2. Register your event listener in Configuration/Services.yaml

    services:
       YourVendor\YourExtension\EventListener\AdjustJobsDataset:
          tags:
             - name: event.listener
               identifier: 'adjustJobsDataset'
               event: Brotkrueml\JobRouterData\Event\ModifyDatasetOnSynchronisationEvent
    

Transfer data sets to a JobRouter installation

Sometimes it is necessary to transfer data sets from TYPO3 to a JobRouter® installation. An API and a transmit command are available for this use case.

Data sets are transferred asynchronously, since a JobRouter® installation may be unavailable or in maintenance mode and to avoid long page loads. Let’s take a look at the flow:

Transferring data sets

Transferring data sets

As you can see from the diagram, you can prepare multiple data sets. The different data sets can be transmitted to different JobRouter® installations – depending on the configuration of the table link in the Data module.

Preparing the data sets

If you want to transfer data sets programmatically to a JobRouter® installation, you can use the Preparer class within TYPO3, e.g. in an Extbase controller:

<?php
declare(strict_types=1);

namespace Vendor\Extension\Controller;

use Brotkrueml\JobRouterData\Exception\PrepareException;
use Brotkrueml\JobRouterData\Transfer\Preparer;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

final class MyController extends ActionController
{
   private Preparer $preparer;

   // It's important to use dependency injection to inject all necessary
   // dependencies into the preparer
   public function __construct(Preparer $preparer)
   {
      $this->preparer = $preparer;
   }

   public function myAction()
   {
      // ... some other code

      try {
         $this-preparer->store(
             // The table link uid
            42,
            // Some descriptive identifier for the source of the dataset
            'some identifier',
            // Your JSON encoded data set
            '{"your": "data", "to": "transfer"}'
         );
      } catch (PrepareException $e) {
         // In some rare cases an exception can be thrown
         var_dump($e->getMessage());
      }
   }

The transmit command must be activated with a cron job to periodically transmit the data sets to the JobRouter® installation(s).

Important

It is not advised to insert the data sets directly into the transfer table, as the table schema can be changed in future versions. Use the API described above.

Using the JobDataRepository

The JobDataRepository provides methods to access the JobData REST API in TYPO3, e.g. in a command or a controller.

The following methods are available:

add(array $dataset): array

Adds a dataset to a JobData table and returns the stored dataset.

remove(int ...$jrid): void

Removes one or more datasets from a JobData table.

update(int $jrid, array $dataset): array

Updates the dataset with the given jrid for a JobData table and returns the stored dataset.

findAll(): array

Returns all datasets of the JobData table;

findByJrId(int $jrid): array

Returns the dataset for the given jrid of a JobData table.

Example

Configure in Configuration/Services.yaml an alias for the JobDataRepository and add it to the command configuration:

services:
   jobDataRepository.yourTableHandle:
      class: 'Brotkrueml\JobRouterData\Domain\Repository\JobRouter\JobDataRepository'
      arguments:
         $tableHandle: 'yourTableHandle'

   Vendor\Extension\Command\YourCommand:
      tags:
         - name: 'console.command'
           command: 'vendor:yourcommand'
      arguments:
         $jobDataRepository: '@jobDataRepository.yourTableHandle'

Then inject the JobDataRepository into the command and use the appropriate method:

<?php
declare(strict_types=1);

namespace Vendor\Extension\Command;

final class YourCommand extends Command
{
   private $jobDataRepository;

   public function __construct(JobDataRepository $jobDataRepository)
   {
     $this->jobDataRepository = $jobDataRepository;

     parent::__construct();
   }

   protected function execute(InputInterface $input, OutputInterface $output): int
   {
      $datasets = $this->jobDataRepository->findAll();

      // ... your logic

      return 0;
   }
}

Customising the formatting of a table column in the content element

New in version 1.0.0.

The extension comes with four formatters that are used when rendering the column content in the content element:

  • DateFormatter

  • DateTimeFormatter

  • DecimalFormatter

  • IntegerFormatter

These are implemented as PSR-14 event listeners and are located in the Classes/EventListener folder of this extension. They receive a Brotkrueml\JobRouterData\Event\ModifyColumnContentEvent event with the following methods:

getTable()

The table model.

Return value

The domain model of a table (Brotkrueml\JobRouterData\Domain\Model\Table).

getColumn()

The column model.

Return value

The domain model of a column (Brotkrueml\JobRouterData\Domain\Model\Column).

getContent()

The content of a table cell.

Return value

The value of the content (types: float, int, string).

setContent($content)

Set a content for a table cell.

Parameter
float|int|string $content

The formatted content of a table cell.

getLocale()

The locale of the website page.

Return value

The locale (for example, “de_DE.utf8” or “en_US”) is retrieved from the configured site language field locale.

Custom formatters

As a PSR-14 event is dispatched for formatting a cell content, a custom event listener can be used. Have a look into the existing formatter event listeners.

Note

Only the first suitable formatter is used. When the content is adjusted with the setContent() method of the event the propagation of other events is stopped. So be sure to add your custom event listener before existing ones.