README

The Widget bundle provides the developers a way to define widgets in the user interface.

Widget Entity
Creating a Widget
Context Filter
Todo

Widget Entity

A widget consists of a title and content meant to be displayed in a template in a specific position. Essentially, it allows the developer to customise templates without directly modifying the template files. Widgets are comparable to ORO Placeholders with two additional features: the capability of adding a title and the context filter.

Note: Eventually, if possible, we will merge the concept of widgets to ORO Placeholders with our additional features.

Creating a Widget

Widgets can be created in any bundle. They are defined the same way as any other services in Symfony using the Service Container. The developer will need to tag the service with the ds.widget tag in order for the system to pick it up as a widget. Finally, the developer will need to define a position in a template file, where the widget should be displayed.

The widget class src/Gov/Bundle/BlogBundle/Widget/LatestPostsWidget.php:

<?php

namespace Gov\Bundle\BlogBundle\Widget;

use Ds\Bundle\WidgetBundle\Widget\Widget;

class LatestPostsWidget extends Widget
{
    public function getTitle()
    {
        return 'Latest Posts';
    }

    public function getContent(array $data = [])
    {
        return '<ul><li><a href="">Post 1</a></li><li><a href="">Post 2</a></li></ul>';
    }
}

The widget service src/Acme/Bundle/TestBundle/Resources/config/services.yml:

services:
    gov.blog.widget.latest_posts:
        parent: ds.widget.widget.abstract
        class: Gov\Bundle\BlogBundle\Widget\LatestPostsWidget
        tags:
            - { name: ds.widget, position: aside }

The template position:

<html>
    <body>
        <aside>
            {% for widget in ds_widgets({ position: 'aside' }) %}
                <h3>{{ widget.title }}</h3>
                {{ widget.content|raw }}
            {% endfor %}
        </aside>
    </body>
</html>

Context Filter

The context filter is an optional parameter allowing the developer to define when a Widget should be rendered.

Let's use a real world example to explain the concept:

The DigitalState-Platform introduces the concept of Government Services through the DsServiceBundle. This bundle provides, at its core, the base actions for creating, editing, and deleting Generic Services. The editing action uses of the Widget concept for displaying the core form fields for the Generic Service.

The DigitalState-Platform also introduces the concept of BPM Services through the DsServiceBpmBundle. This bundle grafts itself on top of the DsServiceBundle to provide additional BPM-related functionality for when a business user wishes to create a BPM-based Service. A BPM Service is the same as a Generic Service, with additional fields to map the BPM process definition id and other BPM specific configurations. The DsServiceBpmBundle defines an additional Widget for the additional form fields and flags the context of the widget as bpm, meaning this Widget should only be displayed the specific context of BPM.

The template position with context defined:

<html>
    <body>
        <main>
            <form>
                {% for widget in ds_widgets({ position: 'main', context: 'bpm' }) %}
                    <h3>{{ widget.title }}</h3>
                    {{ widget.content|raw }}
                {% endfor %}
            </form>
        </main>
    </body>
</html>

Todo

Introduce custom twig tag for widget positions.

Example 1:

{% position *position_name* with { variable: value } %}

Example 2:

{% position *position_name* %}
    {{ widget.title }}
    {{ widget.content|raw }}
{% endposition %}

Enable widgets to be defined as template or callbacks, instead of classes.

digitalstate / platform-widget-bundle

Maintainers

Details

README

Table of Contents

Widget Entity

Creating a Widget

Context Filter

Todo