Skip to main content
Fluid Primitives

Getting Started

Before you start, please take a look at the core documentation of Fluid Components first.

Installation

Install Fluid Primitives via Composer:

composer require jramke/fluid-primitives

Then you need to add the client-side files. Just add the fluid-primitives package to your package.json.

npm install fluid-primitives

If you aren't using a package manager or frontend build process, you can also simply use the pre-built files from EXT:fluid_primitives/Resources/Public/JavaScript/dist/ and include them in your templates.

Setup Component Collection

Create a ComponentCollection class in your sitepackage:

<?php

declare(strict_types=1);

namespace MyVendor\MyExt\Components;

use Jramke\FluidPrimitives\Component\AbstractComponentCollection;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
use TYPO3Fluid\Fluid\View\TemplatePaths;

final class ComponentCollection extends AbstractComponentCollection
{
    public function getTemplatePaths(): TemplatePaths
    {
        $templatePaths = new TemplatePaths();
        $templatePaths->setTemplateRootPaths([
            $templatePaths->setTemplateRootPaths([
                ExtensionManagementUtility::extPath('ext', 'Resources/Private/Components/ui'),
                ExtensionManagementUtility::extPath('ext', 'Resources/Private/Components'),
            ]);
        ]);
        return $templatePaths;
    }

    public function getContextNamespaces(): array
    {
        return [
            'MyVendor\MyExt\Components\Contexts',
        ];
    }
}

Make sure we use the AbstractComponentCollection class from Fluid Primitives and not from Fluid's core.

See File Structure Guide for more information about why we used two template root paths.

See Context Guide for more information about component contexts and the new getContextNamespaces method.

Register Global Namespace

Register the ui namespace for easier component usage:

// ext_localconf.php

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['ui'][] = 'MyVendor\\MyExt\\Components\\ComponentCollection';

Optional: Component Settings

Provide custom settings that are exposed as {settings} inside the component templates (merged to lib.contentElement.settings).

plugin.tx_fluidprimitives {
    settings {}
}

First Component

Create a button component at Resources/Private/Components/ui/Button/Button.html:

<ui:prop name="variant" type="string" optional="{true}" default="primary" />

<ui:cn value="button button--{variant} {class}" as="class" />

<button class="{class}" {ui:attributes()}>
    <f:slot />
</button>

And use it in your templates like this:

<ui:button variant="secondary" class="another-class" data-test="abc"> Hello World </ui:button>