Authoring Components

Components reside in src/components directory. Each should be self-contained within its own folder with all the related files. The files should be named after the component and will typically be:

• component.twig - markup (required)
• component.scss - styles (required)
• configuration (optional), in one of the three formats:
  • component.config.js - JavaScript module file (preferred)
  • component.config.yml - YAML file
  • component.config.json - JSON file

There is no need to import CSS files for each component into the main CSS file. They will be automatically picked up and made available for usage in your page templates as well as included in the Components section of this styleguide.

Status

Each component is assigned status. There are three possible statuses:

• prototype - the component is not ready to be used yet
• wip - work in progress, use with caution
• ready

Statutes are indicated by the dots placed by components name in the navigation.

If you don’t specify the status it will be set to ready. See configuration file section below to find out how to set it otherwise.

The markup file

For the markup, the styleguide uses Twig, a popular template engine that, apart from variables, lets you use control and looping structures. None of these features are required and pure HTML is a valid option, unless you want to pass data to the template. One use case would be populating the component with mock content fetched from a third-party service.

The style file

You should also include Sass (.scss) file. In the file, specify a class for the component using PascalCase naming convention and create rules as required. For CSS guidelines, see Coding Styleguide.

.Component {
    &__title {
        
    }
}

The configuration file

Configuration file is optional and lets you specify several properties determining the way component is presented and used throughout the styleguide. One of the most common property will be status (prototype, wip or ready with the latter being a default), explained above. For full list of available properties see Fractal’s documentation.

Passing variables to the component markup

To make variables available in the markup, specify them as properties of context object. For example, if your configuration file is in YAML format, you add the variables in the following way:

status: ready
context:
  heading: "This is a heading"

Having heading variable defined, you can refer to it in your component markup by enclosing it in double braces:

<div class="Card">
    <div class="Card__heading">{{ heading }}</div>
</div>

Configuration file formats

As mentioned above, there are three formats available for configuration: JavaScript module (preferred), JSON and YAML.

JavaScript module example (preferred)

let data = getData(); // get data from a third-party service

module.exports = {
    status: "ready",
    context: {
        "data": data // pass fetched data to the markup
    }
}

JSON example

{
  "status": "ready",
  "context": {
    "heading": "This is a heading"
  }
}

YAML example

status: ready
handle: big-card
context:
  heading: "This is a heading"