fractal-typo3

fractal-typo3

TYPO3 bridge for the Fractal component library tool (http://fractal.build / @frctl)

About

This Fractal plugin lets you use the Open Source CMS TYPO3 as source of and template engine for your web component library. It is the counterpart to the TYPO3 component library extension.

Usage

Installation

To add TYPO3 support to your Fractal instance, run

npm install --save fractal-typo3

in your project root directory. Also, make sure you installed and enabled the TYPO3 component library extension in your TYPO3 instance.

Configuration

To enable TYPO3 as component source and template engine, add these settings to your fractal.js configuration:

const path = require('path');
const fractal = module.exports = require('@frctl/fractal').create();
const typo3 = require('fractal-typo3');

// Configure the absolute URL of your TYPO3 frontend
typo3.configure('web', 'http://example.com');

// Configure Fractal's component base directory
fractal.components.set('path', path.join(__dirname, 'fractal', 'components'));

// Add a "TBD" component status label
fractal.components.set('statuses', Object.assign({
    tbd: {
        label: 'TBD',
        description: 'Planned but not yet started. Go ahead! :)',
        color: '#CCCCCC'
    }
}, fractal.components.get('statuses')));

// Set the directory for static assets to your TYPO3 root directory
fractal.web.set('static.path', path.join(__dirname, 'web'));

// Configure Fractal to use TYPO3 as template engine
fractal.components.engine(typo3.engine);
fractal.components.set('ext', '.t3s');

// Register the 'update-typo3' custom command
fractal.cli.command('update-typo3', typo3.update, {
    description: 'Synchronise components with TYPO3'
});

Make sure that your server knows how to resolve the absolute URL to your TYPO3 frontend. You might need to add an entry to your hosts file for this to work under certain circumstances.

Component dependency graphs

If you have GraphViz available on your server, you can enable an additional Fractal panel that will give you a dynamically created dependency graph for each component:

To enable the Graph panel in Fractal, edit your fractal.js and pass a Fractal theme instance as third argument to the typo3.configure() method:

const path = require('path');
const fractal = module.exports = require('@frctl/fractal').create();
const typo3 = require('fractal-typo3');

// Create a custom theme and pass it to the configuration method
const typo3Theme = require('@frctl/mandelbrot')();
typo3.configure('web', 'http://example.com', typo3Theme);

/* ... */

Component update against TYPO3

Run the following command to synchronise with TYPO3 and build your component library:

fractal update-typo3

You should see a list of components that are created / updated during synchronisation:

√ Generic/Hero
√ Generic/Collapsible
√ Generic/Definition List
√ Generic/Menu/Button
√ Generic/Menu/Breadcrumb
√ Generic/Menu/Main
...

Please restart your Fractal server in case the Web UI doesn't reflect the changes automatically. After refresh, your TYPO3 components should show up in Fractal:

Instead of displaying pre-rendered results, Fractal uses TYPO3 as real-time template engine for rendering your TYPO3 components on demand, hence the short rendering delay.

Local component folder configuration

You can configure some select properties of your Fractal component folders by placing a local.json file into the corresponding directory of your component definition directory structure in TYPO3. The following options are supported:

{
    "dirsort": 1, // Used to order directories other than alphabetically
    "label": "Icons & images" // Custom folder name not attainable via real directory name, e.g. including special characters
}

Contributing

Found a bug or have a feature request? Please have a look at the known issues first and open a new issue if necessary. Please see contributing and conduct for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Joschi Kuphal
• All Contributors

License

Copyright © 2020 Joschi Kuphal / [e-mail]. Licensed under the terms of the MIT license.

Changelog

[1.1.0] - 2021-01-02

Changed

• Update dependencies
• Add User Agent header to component update call