\Block\EventBlockHook

Block rendering dispatcher.

Each block has a handler property which identifies the plugin that created that Block, by default all blocks created using backend's administration page defines Block has their handler.

An external plugin may register a custom block by inserting its information directly in the "blocks" table and set an appropriate handler name.

For example, Taxonomy plugin may create a new Categories block by inserting its information in the "blocks" table, this new block will have Taxonomy as its handler name.

Block's handler property is used to compose event's name that is triggered when block is being rendered (or edited). Event's name follows the pattern described below:

Block.<handler>.<display|settings|...>

So all blocks with Block as handler will trigger the event below when being rendered:

Block.Block.display

The event described above is handled by this class. In the other hand, for the Taxonomy example described above the following event will be triggered when rendering the Categories block:

Block.Taxonomy.display

Taxonomy plugin should catch this event and return a STRING.


NOTES:

  • Event's subject is always the View instance being used.
  • Plugins are allowed to define any handler name when registering blocks in the "blocks" table, the only constraint is that it must be unique in the entire "blocks" table. Use plugin's name itself is always a good practice as it's already unique in the whole system. Anyway, handler names such as random-letters, or i-like-trains are valid as well.

Summary

Methods
Properties
Constants
implementedEvents()
renderBlock()
trigger()
eventDispatcher()
triggered()
cache()
dropCache()
No public properties found
No constants found
No protected methods found
$_cache
N/A
No private methods found
No private properties found
N/A

Properties

$_cache

$_cache : array

Used internally.

Type

array

Methods

implementedEvents()

implementedEvents() : void

Returns a list of hooks this Hook Listener is implementing. When the class is registered in an event manager, each individual method will be associated with the respective event.

renderBlock()

renderBlock(\Cake\Event\Event $event, \Block\Model\Entity\Block $block, array $options) : string

Block rendering dispatcher, renders the given block.

This method will delegate the rendering task to block's handler by triggering the Block.<handler>.display event, or the event Block.<handler>.display<CamelizedDelta>, where "CamelizedDelta" is delta's CamelizedName, e.g.: Block.<handler>.displayMyDeltaName (for block's delta my-delta-name).

If such event does not exists it will look for certain view elements when rendering each block, if one of this elements is not present it'll look the next one, and so on. These view elements should be defined by Themes by placing them in <MyTheme>/Template/Element.

Render block based on theme's region & view-mode

render_block_[region-name]_[view-mode].ctp

Renders the given block based on theme's region-name and view-mode, for example:

  • render_block_left-sidebar_full.ctp: Render for blocks in left-sidebar region when view-mode is full

  • render_block_left-sidebar_search-result.ctp: Render for blocks in left-sidebar region when view-mode is search-result.

  • render_block_footer_search-result.ctp: Render for blocks in footer region when view-mode is search-result.

Render block based on theme's region

render_block_[region-name].ctp

Similar as before, but based on theme's region-name (and any view-mode), for example:

  • render_block_right-sidebar.ctp: Render for blocks in right-sidebar region.

  • render_block_left-sidebar.ctp: Render for blocks in left-sidebar region.

Default

render_block.ctp

This is the global render, if none of the above renders is found we try to use this last. Themes can overwrite this view element by creating a new one at ExampleTheme/Template/Element/render_block.ctp.


NOTE: Please note the difference between "_" and "-"

Parameters

\Cake\Event\Event $event

The event that was triggered

\Block\Model\Entity\Block $block

Block entity to be rendered

array $options

Additional options, will be passed to the template element being rendered

Returns

string —

The rendered block

trigger()

trigger(array|string $eventName) : \Cake\Event\Event

Triggers the given event name. This method provides a shortcut for:

$this->trigger('EventName', $arg1, $arg2, ..., $argn);

You can provide a subject to use by passing an array as first arguments where the first element is the event name and the second one is the subject, if no subject is given $this will be used by default:

$this->trigger(['GetTime', new MySubject()], $arg_0, $arg_1, ..., $arg_n);

You can also indicate an EventDispatcher instance to use by prefixing the event name with <InstanceName>::, for instance:

$this->trigger('Blog::EventName', $arg1, $arg2, ..., $argn);

This will use the EventDispacher instance named Blog and will trigger the event EventName within that instance.

Parameters

array|string $eventName

The event name to trigger

Returns

\Cake\Event\Event —

The event object that was fired

eventDispatcher()

eventDispatcher(string $name) : \QuickApps\Event\EventDispatcher

Gets an instance of the given Event Dispatcher name.

Usage:

$this->eventDispatcher('myDispatcher')
    ->trigger('MyEventName', $argument)
    ->result;

Parameters

string $name

Name of the dispatcher to get, defaults to 'default'

Returns

\QuickApps\Event\EventDispatcher

triggered()

triggered(string|null $eventName) : integer|array

Retrieves the number of times an event was triggered, or the complete list of events that were triggered.

Parameters

string|null $eventName

The name of the event, if null returns the entire list of event that were fired

Returns

integer|array

cache()

cache(null|string $key, mixed $value) : mixed

Reads, writes or search internal class's cache.

Usages:

  • When reading if no cache key is found NULL will be returned. e.g. $null = static::cache('invalid-key');
  • When writing, this method return the value that was written. e.g. $value = static::cache('key', 'value');
  • Set both arguments to NULL to read the whole cache content at the moment. e.g. $allCache = static::cache()
  • Set key to null and value to anything to find the first key holding the given value. e.g. $key = static::cache(null, 'search key for this value'), if no key for the given value is found NULL will be returned.

Examples:

Writing cache:

static::cache('user_name', 'John');
// returns 'John'

static::cache('user_last', 'Locke');
// returns 'Locke'

Reading cache:

static::cache('user_name');
// returns: John

static::cache('unexisting_key');
// returns: null

static::cache();
// Reads the entire cache
// returns: ['user_name' => 'John', 'user_last' => 'Locke']

Searching keys:

static::cache(null, 'Locke');
// returns: user_last

static::cache(null, 'Unexisting Value');
// returns: null

Parameters

null|string $key

Cache key to read or write, set both $key and $value to get the whole cache information

mixed $value

Values to write into the given $key, or null indicates reading from cache

Returns

mixed

dropCache()

dropCache(string|null $key) : void

Drops the entire cache or a specific key.

Usage:

static::dropCache('user_cache'); // removes "user_cache" only
static::dropCache(); // removes every key

Parameters

string|null $key

Cache key to clear, if NULL the entire cache will be erased.