Examples for integrations missing in the guide

[jfroehlich]

Hi, we really like fractal since it is speeding up our processes considerably. But we ran into a major issue that blocks us in the flow: When we handover our our designs to devs, they really struggle integrating the components into the projects and therefore updates to the library do not get propagated into the projects or they are not integrated at all.

The reasons are that the integration section in the guide lacks examples and devs struggle with the @handle in the templates. The devevelopers and us have the same opinion that the @handle for components is a great concept but in order to integrate the components into the sites they would have to do one of:

• re-write all the component so use path includes (e.g. for nunjucks)
• re-implement the adapter to be injectable as standalone extension to nunjucks
• load a full fractal instance and fetch the components somehow so that the nunjucks on the cms side can use it.
• get the adapters somehow to work with the cms

Most of the sites use nunjucks, twick or handlebars and have a tight integration into the CMS in one way or the other. It would be really great if you could describe in the guide how the components could be integrated into an existing site e.g. by using the nunjucks engine of the adapters, or injecting the adapters into a nunjucks instance using e.g. eleventy, or another way how the components could be made available to the production sites.

[mihkeleidast]

Yeah, I think this is necessary, though we should agree on what specific circumstances we should document. For example, integrating a Twig component library into a WordPress (or any PHP) project can differ a lot compared to some Node-based CMS-es.

I think in the past the easiest way to do a semi-direct integration is to export a handle/filePath map from Fractal and then integrate that into the CMS template loading stack.

[jfroehlich]

Oh, this is a great idea! A map like {<handle>: {<filePath>, <context>}} would be great starting point to build the render tag for various template systems, I guess. The implementation of the tag is certainly very similar for nunjucks, twig, handlebars, django, jinja2, liquid, ... and an official reference implementation for nunjucks or handlebars could bootstrap the implementation of these plugins very quickly.

A way to export this map is already (kind of) documented. I slapped a little proof of concept function together which runs fine in my fractal skeleton, but does not yet write files:

fractal.cli.command('list-components', function (args, done) {
    const app = this.fractal;
    const sourcemap = {};
    for (let item of app.components.flatten()) {
        sourcemap[item.handle] = {path: item.path, ctx: item.context}
    }
    this.log(JSON.stringify(sourcemap));
    done();
}, {description: "List components"});

Is that the right way to do it? Is there an API endpoint to write the file?

The file could be updated on the fly with the updated event. Correct?

Do you by chance already have a simple nunjucks or handlebars tag that processes this file? If not I'd try a bit on the weekend.

[mihkeleidast]

Yes, exactly! Fractal does not offer an API to write files, but you should be able to use the Node-native fs API for that.

I don't have an example on how to use the map in another Nunjucks/Handlebars environment, I've only ever made it work with Twig PHP (for WordPress through Timber) myself.

[jfroehlich]

Ok, I put together a little sample project: https://github.com/jfroehlich/nunjucks-fractal-example
It works fine in that little lab project, but I didn't try it in production yet.