area17 / twill-transformers
Transformers for Twill apps
Installs: 6 841
Dependents: 0
Suggesters: 0
Security: 0
Stars: 11
Watchers: 5
Forks: 7
Open Issues: 1
Requires
- php: >=7.2
Requires (Dev)
- phpunit/phpunit: >=8.0
- squizlabs/php_codesniffer: ^3.0
- dev-unstable
- v1.2.1
- v1.2.0
- v1.1.9
- v1.1.8
- v1.1.7
- v1.1.6
- v1.1.5
- v1.1.4
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.41
- v1.0.40
- v1.0.39
- v1.0.38
- v1.0.37
- v1.0.36
- v1.0.35
- v1.0.34
- v1.0.33
- v1.0.32
- v1.0.31
- v1.0.30
- v1.0.29
- v1.0.28
- 1.0.27
- 1.0.26
- 1.0.25
- 1.0.24
- 1.0.23
- v1.0.22
- v1.0.21
- v1.0.20
- v1.0.19
- v1.0.18
- v1.0.17
- v1.0.16
- v1.0.15
- v1.0.14
- v1.0.13
- v1.0.12
- v1.0.11
- v1.0.10
- v1.0.9
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
This package is auto-updated.
Last update: 2024-10-13 16:50:28 UTC
README
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
composer require area17/twill-transformers
Publish the config file
php artisan vendor:publish --provider="A17\TwillTransformers\ServiceProvider"
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.
namespace App\Transformers; use A17\TwillTransformers\Transformer as TwillTransformer; abstract class Transformer extends TwillTransformer { /** * @return array|null */ public function transform() { return $this->sanitize([ 'template_name' => $this->makeTemplateName(), 'header' => $this->transformHeader($this->data), $this->makePageKey() => $this->transformData($this->data), 'seo' => $this->transformSeo($this->data), 'footer' => $this->transformFooter($this->data), ]); } }
Use required traits
Add and use this one on your base controller:
use A17\TwillTransformers\ControllerTrait;
And this one on your base repository:
use A17\TwillTransformers\RepositoryTrait;
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.
namespace App\Transformers; class LandingPage extends Transformer { public function transform() { return [ 'hero' => [ 'title' => $this->title, 'text' => $this->text, 'image' => $this->transformMedia(), ], 'blocks' => $this->transformBlocks(), 'related' => $this->transformRelatedArticles(), ]; } }
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:
namespace App\Transformers\Block; use App\Transformers\Block; class ArtistPortrait extends Block { public function transform() { return [ 'component' => 'portrait', 'data' => [ 'name' => $this->name, 'text' => $this->main_info, 'button' => [ 'more_label' => ___('Lire plus'), 'less_label' => ___('Lire moins'), ], 'extra_text' => $this->additional_info, 'image' => $this->transformMedia(), ], ]; } }
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:
public function transformArtistPortraits($portraits) { return collect($portraits)->map(function ($portrait) { return $this->transformBlockArtistPortrait($portrait); }); }
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:
namespace App\Transformers\Block; use App\Transformers\Block; class ArtistPortrait extends Block { public function transform() { return [ 'component' => 'portrait', 'data' => [ 'name' => $this->name, 'text' => $this->main_info, 'button' => [ 'more_label' => ___('Lire plus'), 'less_label' => ___('Lire moins'), ], 'extra_text' => $this->additional_info, 'image' => $this->transformMedia(), ], ]; } }
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:
$this->transformBlockArtistPortrait($portrait);
Inside the transformer, we can render images just by doing:
$this->transformMedia()
Or get the name of a portrait person this way:
$this->name
Rendering the front-end
This is all you have to do to send JSON data to your front-end:
@extends('front.layouts.app') @section('contents') @include("templates.{$template_name}") @endsection
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:
'views_path' => 'admin._site.front',
And create this Blade template to your render previews for everything:
@extends('front.layouts.app') @php $data = _transform($item); @endphp @section('contents') @include("templates.{$data['template_name']}", $data) @endsection
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:
@php $transformed = _transform($block); $type = Str::kebab(Str::camel($transformed['type'])); @endphp @include("components.block.{$type}.block-{$type}", $transformed)
Blade Transformers
You can define the transformer directly inside a Blade template:
@extends('layouts.app') @transformer(\App\Transformers\Post) ...
On your base Transformer add a blade()
static radmethod to handle the data transformation:
public static function blade($transformer, $data): array { if (app()->bound(BladeTransformer::class)) { return app(BladeTransformer::class)->transform($transformer, $data); } return []; }
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.
<?php namespace App\Transformers; class Posts extends Transformer { public function transform(): array { return [ 'title' => $this->title, ]; } public function transformStorybookData(): array { return [ 'title' => 'Fake Title to Be Displayed Inside Storybook Only', ]; } }
If you are building a Storybook story using Blast, your story should extend the application layout
@extends('layouts.app') @transformer(\App\Transformers\Post) @storybook([ 'layout' => 'fullscreen', 'status' => 'dev', 'args' => [] ]) @section('content') <div class="container"> ... </div> @endsection
And your layout should check if it's running in Blast and only render the story component:
@if (runningInBlast(get_defined_vars())) @yield('content') @else <!DOCTYPE html> <html lang="{{ str_replace('_', '-', app()->getLocale()) }}" data-active-nav="@yield('active_nav')"> <head> ... </head> <body> ... </body> </html> @endif
Changelog
Please see CHANGELOG for more information on what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security-related issues, please email antonio@area17.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.