Craft CMS + Fractal

This is a code repo to accompany my 2022 DotAll talk Implementing component-driven design systems with Craft + Fractal. The accompanying slides can be found at https://madebyraygun.com/projects/dotall-2022/presentation.

This is an installable Craft CMS installation, although the asset build step is not set up. We're relying on static assets that may need to be copied over to the public/dist folder.

Built with CraftCMS and Fractal. Use DDEV version 1.19.x for local CraftCMS development. Optionally use Hygen to generate Fractal components and Craft modules.

DDEV + Craft

Make sure DDEV is installed then:

1. Start CraftCMS development environment with: ddev start
2. Install Craft and dependencies with: ddev composer install -d ./craft

Additionally you can:

• Review or change the project config by using the yaml file: .ddev/config.yaml

• Login SSH and execute custom commands with: ddev ssh

• Use ddev describe to get running services such as database hostname/port.

• Stop your development evironment by using: ddev stop

• Debug your development environment (Expand to see VSCode + DDEV Instructions)

  1. Install VSCode Extension
  2. Enable DDEV with ddev xdebug enable
  3. Start a new Debuggin Session from VSCode
  4. Set breakpoints from editor and navigate the site to catch and inspect them.

Update the .env file (secret values will need to be replaced):

# The environment Craft is currently running in (dev, staging, production, etc.)
CRAFT_ENVIRONMENT=dev

# The application ID used to to uniquely store session and cache data, mutex locks, and more
CRAFT_APP_ID=CraftCMS--xxxxxxx-unique-key-xxxxxx

# The secure key Craft will use for hashing and encrypting data
CRAFT_SECURITY_KEY=xxxxxxx-unique-key-xxxxxx

# Database Configuration
# May be different depending on your Nitro configuration
DB_DRIVER=mysql
DB_SERVER=ddev-craft-fractal-db
DB_PORT=3306
DB_DATABASE=db
DB_USER=root
DB_PASSWORD=root
DB_SCHEMA=public
DB_TABLE_PREFIX=

Fractal Component Library

Use the Fractal library to develop site components without the need of backend setup just by running:

npm run fractal:start

A server will be available (typically on http://localhost:3002) and it will run the Fractal sync task. For featuring composed components you will need to use preview layouts

Additionally you can publish a static version of the library by running npm run fractal:build command. This will generate an output inside library/build with HTML, JS and CSS files ready to showcase the entire library.

Using Fractal Components inside Craft templates

To export ready state components use the following command:

npm run fractal:export

Components will be copied over to the /craft/templates/_components folder. Note: these files are not included in the git repo, this command must be run as part of your deploy process.

Each component config must be set to status ready before it can be exported into the Craft templates, wip and prototype states will be ignored.

After exporting our library components we can use them with the help of the Fractal Loader plugin by handle, example:

{% include '@alert' with { 'title': 'Custom title' } %}

or

{% include '@alert' with alert %}

depending on how your Craft CMS context is prepared. The provided context from the CMS should match the context definition inside component-name.config.js alongside each component.

For this project, all of the Craft field context is prepared by a series of modules in the /craft/modules folder, where you can find layoutcontext (globals), pageblocks (matrix) and pagecontext (entry and index pages). Each global, matrix, and page has a corresponding PHP file which prepares all of the data and injects it into the Craft template context.

Hygen

You can optionally use Hygen to scaffold new Fractal components and Craft CMS modules based on templates that have been created in the _templates directory.

Content block names should be entered in Title Case, e.g. Single Image. The component in Fractal will be named ./library/components/04-content-blocks/single-image and the module in Craft will be named ./craft/modules/pageblocks/blocks/SingleImageBlock.php

• Install Hygen globally with npm i -g hygen
• Type hygen fractal new and follow the prompt to create a new Fractal component.
• Type hygen craft new and follow the prompt to create a new CMS module..

Template

Atlas free template from Red Pixel themes.