Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

120 lines (92 sloc) 3.63 KB

Building Components with Fluid Styleguide

Components must meet the following requirements for them to show up in the styleguide correctly:

  1. The component namespace must be registered for Fluid Components (as shown in Getting Started)
  2. The component folder must contain a fixture file which at least contains the default fixture (see below).
  3. To load your frontend assets, you need to specify them in the FluidStyleguide.yaml configuration file (as shown in Getting Started)

Example Component

For illustration purposes we want to add the following component to the styleguide:

Molecule/Teaser/Teaser.html:

<fc:component>
    <fc:param name="title" type="string" />
    <fc:param name="link" type="SMS\FluidComponents\Domain\Model\Typolink" />
    <fc:param name="image" type="SMS\FluidComponents\Domain\Model\Image" optional="1" />
    <fc:param name="actions" type="string" optional="1" />
    <fc:param name="theme" type="string" optional="1" default="light" />

    <fc:renderer>
        <a href="{link}" class="teaser teaser--{theme}" target="{link.target}">
            <h3 class="teaser__title">{title}</h3>
            <f:if condition="{content}">
                <p class="teaser__content">{content}</p>
            </f:if>

            {actions -> f:format.raw()}

            <f:if condition="{image}">
                <my:atom.image image="{image}" class="teaser__image" />
            </f:if>
        </a>
    </fc:renderer>
</fc:component>

For further instructions on how to build components, please refer to the documentation of Fluid Components.

Adding fixtures to your component

Each component in the styleguide needs a fixture file which contains example values for all of the component's required arguments. A fixture file must at least contain a default fixture, but it may define additional fixtures that can then be selected in the styleguide interface.

Molecule/Teaser/Teaser.fixture.json:

{
    "default": {
        "title": "TYPO3",
        "link": "https://typo3.org"
    },
    "dark": {
        "title": "TYPO3",
        "link": "https://typo3.org",
        "theme": "dark"
    }
}

File naming scheme: {ComponentName}.fixture.json

You can define the content of a component if the component supports it:

{
    "default": {
        "content": "The professional, flexible Content Management System"
    }
}

You can use fluid in your fixture data to nest components:

{
    "default": {
        "actions": "<my:atom.button>Primary Button</my:atom.button><my:atom.button isSecondary='1'>Secondary Button</my:atom.button>"
    }
}

You can use data structures with argument converters to define placeholder images and advanced links:

{
    "default": {
        "image": {
            "height": 300,
            "width": 500,
            "alternative": "My alt text",
            "title": "My image title"
        },
        "link": {
            "uri": "https://typo3.org",
            "target": "_blank"
        }
    }
}

Adding documentation to your component

If you want to add further documentation to your component, just place a markdown file that is named like your component inside your component folder. Fluid Styleguide will pick up the documentation automatically and render it in the DOC tab.

Molecule/Teaser/Teaser.md:

## Teaser Component

This is a generic teaser components. It supports both a light and a dark styling. [...]

File naming scheme: {ComponentName}.md

You can’t perform that action at this time.