Skip to content

Latest commit

 

History

History
257 lines (194 loc) · 9.12 KB

04_IntegrationRecipes.md

File metadata and controls

257 lines (194 loc) · 9.12 KB
< 3. Slots    |    Index    |    5. Kickstarter >

4. Integration Recipes

This article discusses various helper APIs you can use for integrating content via PresentationObject factories.

Find nodes with a filter string

PresentationObject factories provide the protected method findChildNodesByNodeTypeFilterString as a shortcut for filtering the children of a given node.

findChildNodesByNodeTypeFilterString Parameters

name type description default value
$parentNode TraversableNodeInterface The node whose children are to be filtered
$nodeTypeFilterString string A node type filter string (e.g. Neos.Neos:Document,!Neos.Neos:Shortcut)

The UriService

PresentationObject factories come with a built-in UriService that can be accessed via $this->uriService. This service covers all your need for creating URIs to nodes, assets and the like.

The following methods are available:

getNodeUri

Generates the URI for a given document node.

Parameters

name type description default value
$documentNode TraversableNodeInterface The node for which a URI is to be generated
$absolute boolean If true, an absolute URI will be generated false

getResourceUri

Generates an URI for a static resource.

Parameters

name type description default value
$packageKey string The package key for the package containing the static resource
$resourcePath string The path to the static resource within the package relative to Resources/Public

getAssetUri

Generates the URI for a given asset.

Parameters

name type description default value
$asset AssetInterface The asset for which a URI is to be generated

getDummyImageBaseUri

Provides a URI to a dummy image generated by Sitegeist.Kaleidoscope.

getControllerContext

Gives you access to a ControllerContext, which allows you to generate arbitrary internal URIs with the UriBuilder.

resolveLinkUri

Resolves URIs with the special asset:// and node:// protocols.

Parameters

name type description default value
$rawLinkUri string The string containing the URI
$subgraph ContentContext A reference content context required to resolve node:// URIs

The EnumProvider

All pseudo-enums implementing the PseudoEnumInterface can be provided to the inspector or the Fusion runtime using the PseudoEnumProvider. This makes the enum itself the single source of discrete values a node or presentation object property may have, obsoleting value adjustments in Fusion, configuration etc.

As an example, we use the following pseudo-enum:

<?php declare(strict_types=1);
namespace Acme\Site\Presentation\Block\Headline;

use Neos\Flow\Annotations as Flow;
use PackageFactory\AtomicFusion\PresentationObjects\Domain\Enum\PseudoEnumInterface;

/**
 * @Flow\Proxy(false)
 */
final class HeadlineType implements PseudoEnumInterface
{
    const TYPE_H1 = 'h1';
    const TYPE_H2 = 'h2';
    const TYPE_H3 = 'h3';

    /**
     * @var array<string,self>|self[]
     */
    private static array $instances = [];

    private string $value;

    private function __construct(string $value)
    {
        $this->value = $value;
    }

    public static function from(string $string): self
    {
        if (!isset(self::$instances[$string])) {
            if ($string !== self::TYPE_H1
                && $string !== self::TYPE_H2
                && $string !== self::TYPE_H3) {
                throw HeadlineTypeIsInvalid::becauseItMustBeOneOfTheDefinedConstants($string);
            }
            self::$instances[$string] = new self($string);
        }

        return self::$instances[$string];
    }

    public static function h1(): self
    {
        return self::from(self::TYPE_H1);
    }

    public static function h2(): self
    {
        return self::from(self::TYPE_H2);
    }

    public static function h3(): self
    {
        return self::from(self::TYPE_H3);
    }

    public function getIsH1(): bool
    {
        return $this->value === self::TYPE_H1;
    }

    public function getIsH2(): bool
    {
        return $this->value === self::TYPE_H2;
    }

    public function getIsH3(): bool
    {
        return $this->value === self::TYPE_H3;
    }

    /**
     * @return array<int,self>|self[]
     */
    public static function cases(): array
    {
        return [
            self::from(self::TYPE_H1),
            self::from(self::TYPE_H2),
            self::from(self::TYPE_H3)
        ];
    }

    public function getValue(): string
    {
        return $this->value;
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

As a node type postprocessor

Due to cacheability and thus improved performance, it is recommended to use the EnumProvider's node type postprocessor capabilities to make the enum's cases available in the Inspector.

When we now declare our NodeType property, we do this as follows:

  properties:
    headline:
      type: string
      ui:
        inspector:
          editor: Neos.Neos/Inspector/Editors/SelectBoxEditor
          editorOptions:
            values: []
  postprocessors:
    headline-types:
      postprocessor: PackageFactory\AtomicFusion\PresentationObjects\Application\PseudoEnumProvider
      postprocessorOptions:
        enumName: Acme\Site\Presentation\Block\Headline\HeadlineType
        propertyNames:
          - headline

The initial values are left empty and will be completely populated by the postprocessor. While the postprocessor is the same for all enums, there are two configuration options available:

  • enumName: The enum's fully qualified PHP class name
  • propertyNames: A list of property names to apply this enum's values to

As a data source

If for some reason the postprocessor does not suffice, there is also the possibility to use the provider as a data source. Be aware that though more flexible, data sources are called on each load of the inspector, impacting performance. The provider can be used as a data source as follows:

  properties:
    headline:
      type: string
      ui:
        inspector:
          editor: Neos.Neos/Inspector/Editors/SelectBoxEditor
          editorOptions:
            dataSourceIdentifier: packagefactory-atomicfusion-presentationobjects-enumcases
            dataSourceAdditionalData:
              enumName: Acme\Site\Presentation\Block\Headline\HeadlineType

As an EEL helper

If you need the enum's values in Fusion, you can declare the provider as an EEL helper

Neos:
  Fusion:
    defaultContext:
      Enum: PackageFactory\AtomicFusion\PresentationObjects\Application\PseudoEnumProvider

and use it in Fusion to get the cases or values.

cases = ${Enum.getCases('Acme\Site\Presentation\Block\Headline\HeadlineType')}
values = ${Enum.getValues('Acme\Site\Presentation\Block\Headline\HeadlineType')}
< 3. Slots    |    Index    |    5. Kickstarter >