README

Tagged blocks for Krystal Symfony UX Projects: declare UI blocks anywhere in your bundles, render them by location, subject and context.

Installation

composer require krystal-sf/ux-blocks

Enable the bundle in config/bundles.php:

return [
    // ...
    Ksf\Core\Blocks\KsfUxBlocksBundle::class => ['all' => true],
];

Declaring Blocks

A block is a plain Twig Component registered on one or more locations with the #[AsBlock] attribute (repeatable):

use Ksf\Core\Blocks\Attribute\AsBlock;
use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;

#[AsTwigComponent(name: 'Acme:MyBlock', template: '@AcmeBundle/blocks/my-block.html.twig')]
#[AsBlock(location: BlockTags::TOP)]
#[AsBlock(location: "orders-sidebar", subject: Order::class, context: ActionContext::EDIT)]
class MyBlock
{
    public array $options = array();
}

AsBlock options: location (required), subject (code or class), context, roles, priority, options (static options merged at render).

Live Components work the same way — public props matching AsBlock::DI_PROPERTIES (location, subject, context, options, presets) are injected at mount.

Rendering Blocks

Render every block registered on a location with the Ksf:Block component:

<twig:Ksf:Block :location="ux.blocks.TOP" />
<twig:Ksf:Block location="orders-sidebar" :subject="order" :context="ux.context.EDIT" />

Standard locations are exposed to Twig as ux.blocks.* (see BlockTags). The Ksf:Block:Local component scopes subject & context for its children.

Blocks from Configuration

Static template blocks can be declared without any PHP class:

ksf_ux_blocks:
    templates:
        -
            template:   "@AcmeBundle/blocks/promo.html.twig"
            location:   "ksf-ux-block-top-main"
            subjects:   ["my-context"]
            options:
                presets: ["alert-sm", "alert-info"]

Each entry is rendered through the internal Ksf:Block:Template component.

Overriding the Renderer

The block wrapper template can be overridden by the host application:

templates/bundles/KsfUxBlocksBundle/Component/block.html.twig

Testing

make up          # boot the docker stack
make phpunit     # run the test suite
make quality     # lint + style + phpstan

License

MIT — see LICENSE.

krystal-sf / ux-blocks

Maintainers

Package info

Statistics

Security