Components must meet the following requirements for them to show up in the styleguide correctly:
- The component namespace must be registered for Fluid Components (as shown in Getting Started)
- The component folder must contain a fixture file which at least contains the
default
fixture (see below). - To load your frontend assets, you need to specify them in the FluidStyleguide.yaml configuration file (as shown in Getting Started)
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.
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.
A fixture can be created in .json
, .json5
, .yml
or .yaml
files. You should create only one fixture file per
component. The styleguide takes the first fixture file and ignores eventually existing files in other formats in the
following order:
.json
.json5
.yml
.yaml
Support for json5
only works if you install the fluid-styleguide with composer (not by TER!).
Molecule/Teaser/Teaser.fixture.json:
{
"default": {
"title": "TYPO3",
"link": "https://typo3.org"
},
"dark": {
"title": "TYPO3",
"link": "https://typo3.org",
"theme": "dark"
}
}
or Molecule/Teaser/Teaser.fixture.json5:
{
// can contain comments
"default": {
"title": "TYPO3 \
can contain multiline strings",
"link": "https://typo3.org"
},
"dark": {
"title": 'TYPO3 with single quotes',
"link": "https://typo3.org",
"theme": "dark"
}
}
or Molecule/Teaser/Teaser.fixture.yaml:
default:
title: |
TYPO3
Multiline
link: https://typo3.org
dark:
title: TYPO3
link: https://typo3.org
theme: dark
File naming scheme: {ComponentName}.fixture.[json|json5|yml|yaml]
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 (as long as the Fluid namespace is defined globally):
{
"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"
}
}
}
You can provide a label for each fixture:
"onDarkBackground": {
"styleguideFixtureLabel": "On dark background",
},
You can override the default component context for each fixture:
{
"onDarkBackground": {
"styleguideComponentContext": "<div class=\"myDarkBackground\">|</div>"
}
}
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