Skip to main content
Keel Docs Showcase

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.

php
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".

php
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.

php
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):

php
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.

twig
{# 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.