Download the PHP package area17/twill-transformers without Composer

Twill Transformers

This package allows you to create transformers to generate view data for your Twill app. It contains a base Transformer class and a series of traits, allowing you not only to transform model data, but also generate all blocks, from Twill's block editor and preview data.

Reasoning

The main class of this package was extracted from the work we did for a client where we decided to use Storybook and Twig templates to build the front end. The idea is to free the back end developer from writing front-end code. For this to happen, the whole data generation is automated, starting from the controller view() call.

Install

Via Composer

Publish the config file

Usage

For those using the same approach (Storybook + Twig), this is what you have to do to make it all happen:

Create your base Transformer

Extend the class Transformer and create your basic page structure. All JSON generated by the transformer will have this structure.

Use required traits

Add and use this one on your base controller:

And this one on your base repository:

Create your first Transformer

Note that data to be transformed is self-contained inside the transformer object. So $this holds everything it's responsible for transforming, and as it's usually a Laravel Model descendent, it also has access to everything we usually do with models, accessors, mutators, relationships, presenters, everything.

Create block transformers

Note that this is only required if your blocks are not compatible with the FE data needs. In order to reuse Twill blocks, BE and FE must agree on the structure and naming of all blocks. But, if you still have data transformation to be done on a block, you can create blocks as this:

Reuse blocks as components

If you have a block transformer and needs to reuse it to generate data on your App transformers, or even other block transformers, you can basically call them this way:

If the transform method call starts with Block, like in transformBlockArtistPortrait(), it basically will try to instantiate the named block transformer class to be used.

This is the code for the block being called above:

Note that the data (a model, an array, an object) passed to your transformer (block or app transformer) can be accessed using $this from inside your block:

So, when we call a transformer like this:

Inside the transformer, we can render images just by doing:

Or get the name of a portrait person this way:

Rendering the front-end

This is all you have to do to send JSON data to your front-end:

And if you need to take a look at the generated data, you just have to add ?output=json the URL.

Rendering previews on Twill

Previews are included, they are basically a side effect of this new approach, so you just have to configure your preview path on twill.php file:

And create this Blade template to your render previews for everything:

Twill's block editor

First, you need to have a block component for every block you render, even if it's only extending a base component from your app.

Then you just need to create this view, that will handle and render all blocks in the editor:

Blade Transformers

You can define the transformer directly inside a Blade template:

On your base Transformer add a blade() static radmethod to handle the data transformation:

Then on each Transformer called from Blade, you can define a transformStorybookData() method to render fake data in case there is no data to be transformed available. This can be used, for instance, when rendering Storybook stories via Blast.

If you are building a Storybook story using Blast, your story should extend the application layout

And your layout should check if it's running in Blast and only render the story component:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Testing

Contributing

Please see CODE_OF_CONDUCT for details.

Security

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

Credits

• AREA 17
• Antonio Ribeiro
• All Contributors

License

The MIT License (MIT). Please see License File for more information.