Blocks (Pro)

Blocks are provided by a block provider, each provider can define several blocks. This plugin comes with two providers : System and Forms.

Registering a new provider

Listen to the EVENT_REGISTER_BLOCK_PROVIDERS event of the BlockProvidersService class :

Event::on(
    BlockProvidersService::class,
    BlockProvidersService::EVENT_REGISTER_BLOCK_PROVIDERS,
    function (RegisterBlockProvidersEvent $event) {
        $event->add(new SystemBlockProvider);
});

Your block provider class must implements BlockProviderInterface. Blocks defined by the providers are defined in their $_definedBlocks attribute.

An exception will be thrown if you register a provider which handle is already registered.

Modifying a provider's blocks

You can modify blocks provided by a provider by responding to an event :

Event::on(
    SystemBlockProvider::class,
    BlockProviderInterface::EVENT_REGISTER_BLOCKS,
    function (RegisterBlockProviderBlocks $event) {
        $event->blocks[] = MyBlock::class;
});

An exception will be thrown if you register 2 blocks with the same handle within a provider.

Defining new blocks

New block classes must implements BlockInterface, the model Block should be used to extend from.

You can override the getOptionsModel method to define more options.

Validating your options and saving them will be handled automatically, as long as you have defined rules in your block options class.

Blocks use configurable options.

Blocks handles can only contain letters, numbers and hyphens.

Creating/Deleting blocks programmatically

Example :

$defaultLayout = Themes::$plugin->layouts->getDefault('theme-handle');
$block = Themes::$plugin->blocks->createBlock([
    'provider' => 'system',
    'handle' => 'content'
]);
$defaultLayout->addBlock($block, 'region-handle');
Themes::$plugin->layouts->save($defaultLayout);

//This works too :

$defaultLayout = Themes::$plugin->layouts->getDefault('theme-handle');
$block = Themes::$plugin->blocks->createBlock([
    'provider' => 'system',
    'handle' => 'content',
    'region' => 'region-handle',
    'layout' => $defaultLayout
]);
Themes::$plugin->blocks->save($block);