Extending Keel
Keel is extended with small PHP services in the project. All interfaces are autoconfigured – implement one, and Keel picks it up; no tags or configuration needed.
Overview cards – DashboardWidgetInterface
Add cards to the start page for project rules such as Tours without departures or Enquiries waiting.
use Keel\Bundle\Widget\DashboardWidgetInterface;
final class EnquiriesWaiting implements DashboardWidgetInterface
{
public function getTitle(): string
{
return 'Enquiries waiting';
}
/** "id" opens that object in the editor; tone: bad | warn | info | ok */
public function getItems(): array
{
return array_map(fn ($e) => [
'id' => $e->getId(),
'label' => $e->getName(),
'sub' => 'since ' . $e->getCreationDate(),
'tone' => 'warn',
], $this->waiting());
}
public function getEmptyText(): string
{
return 'No enquiries waiting.';
}
}
Admins can switch each card on or off in Customize → Overview.
Showing only part of the items – CountedWidgetInterface
When a card shows, say, the newest 8 of many items, also implement CountedWidgetInterface. The card's number is
then the real total, and the card says "Newest 8 of 23".
use Keel\Bundle\Widget\CountedWidgetInterface;
final class EnquiriesWaiting implements DashboardWidgetInterface, CountedWidgetInterface
{
public function getTotal(): int
{
return $this->countWaiting();
}
// …
}
The built-in Not published card works this way.
Cards that only sometimes apply – ConditionalWidgetInterface
When a card only makes sense in some setups, also implement ConditionalWidgetInterface. While isAvailable()
returns false, the card is not shown and Customize does not offer it.
use Keel\Bundle\Widget\ConditionalWidgetInterface;
final class EnquiriesWaiting implements DashboardWidgetInterface, ConditionalWidgetInterface
{
public function isAvailable(): bool
{
return $this->enquiriesEnabled();
}
// …
}
The built-in Assigned to me card works this way: it appears only when a class has assignments.
An item may also name an icon instead of the default warning sign, e.g. 'icon' => 'user'.
Page URLs – ObjectUrlProviderInterface
Tell Keel where an object's page is, for Website and the live Preview. See Page URLs & preview.
Row thumbnails – ObjectImageProviderInterface
By default a row's thumbnail is the object's first image field. When the project knows better (e.g. a main photo chosen among imported photos):
use Keel\Bundle\Url\ObjectImageProviderInterface;
use Pimcore\Model\DataObject\Concrete;
final class MainPhoto implements ObjectImageProviderInterface
{
/** Image URL (asset thumbnail path or external URL); null lets Keel decide. */
public function imageFor(Concrete $object): ?string
{
return $object instanceof \Pimcore\Model\DataObject\Property
? $object->getMainPhoto()?->getThumbnail('keel-row')->getPath()
: null;
}
}
The first non-null URL wins.
Share tags
Keel's page settings store the share image, title and description as document properties – og_image (an asset),
og_title and og_description (text). Output them once in the site's layout so networks use them; Keel's checks read
the rendered page, so the warning disappears as soon as the tags are there.
{# templates/layout.html.twig, inside <head> #}
{% set shareTitle = document.getProperty('og_title') ?: document.title %}
{% set shareDesc = document.getProperty('og_description') ?: document.description %}
{% set shareImg = document.getProperty('og_image') %}
<meta property="og:type" content="website">
<meta property="og:url" content="{{ app.request.uri|split('?')|first }}">
<meta property="og:title" content="{{ shareTitle }}">
<meta property="og:description" content="{{ shareDesc }}">
{% if shareImg %}
<meta property="og:image" content="{{ app.request.schemeAndHttpHost ~ shareImg.getThumbnail({'width': 1200, 'height': 630, 'cover': true, 'format': 'jpeg'}) }}">
{% endif %}
<meta name="twitter:card" content="summary_large_image">
Pages for data objects (a product, a property) can fill the same tags from the object – for example its first photo.