chill-bundles/docs/source/development/menus.md

Menus

This document explains how to use and create menus in Chill.

Add a menu in a template

In your twig template, use the chill_menu function:

{{ chill_menu('person', {
    'layout': '@ChillPerson/menu.html.twig',
    'args' : {'person_id': person.id, 'person': person },
    'activeRouteKey': activeRouteKey
}) }}

The available arguments are:

• layout: a custom layout for KNP Menu.
• args: an array of parameters that will be passed to the MenuBuilder.
• activeRouteKey: the route key name that should be marked as active.

Building a menu

To build a menu, you must create a class that implements \Chill\MainBundle\Routing\LocalMenuBuilderInterface.

The getMenuIds method

This static method returns an array of menu keys that this builder supports. For example, if you want to add items to the "person" menu:

public static function getMenuIds(): array
{
    return ['person'];
}

The buildMenu method

The buildMenu method is called when a menu with one of the supported keys is rendered.

public function buildMenu($menuId, MenuItem $menu, array $parameters): void
{
    // ...
}

• $menuId: the key of the menu being built (e.g., 'person').
• $menu: the KNP Menu item representing the parent menu.
• $parameters: the arguments passed from the chill_menu call in the template (the args key).

Example

public function buildMenu($menuId, MenuItem $menu, array $parameters): void
{
    /** @var \Chill\PersonBundle\Entity\Person $person */
    $person = $parameters['person'];

    $menu->addChild('My Menu Entry', [
        'route' => 'my_route_name',
        'routeParameters' => [
            'id' => $person->getId(),
        ],
    ])
    ->setExtras([
        'order' => 100,
    ]);
}

Ordering items

You can order menu items using the order extra. In case of duplicate orders, the entry is kept, but the order between items with the same weight is random.

$menu->addChild('Ordered Item', [/* ... */])
    ->setExtras(['order' => 50]);

Adding a counter

You can add a counter to a menu item by setting the counter extra:

$menu->addChild('Tickets', [/* ... */])
    ->setExtras([
        'counter' => $this->ticketRepository->countOpenedByPerson($person),
        'order' => 150
    ]);

Adding an icon

You can add an icon to a menu item by setting the icon extra. The icon name corresponds to a Fork Awesome icon name (without the fa- prefix).

$menu->addChild('My tasks', [
    'route' => 'chill_task_singletask_my_tasks',
])
->setExtras([
    'order' => -10,
    'icon' => 'tasks',
]);

Currently, icons are extracted from Fork Awesome, but this might change in the future.

Existing Menus

Here are some common menus used in Chill and the parameters they receive:

• person: Parameter person (instance of Chill\PersonBundle\Entity\Person). Used in the person file.
• accompanyingCourse: Parameter accompanyingCourse (instance of Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriod). Used in the accompanying course file.
• admin: The main administration menu.
• section: The "sections" menu (top navigation).
• user: The "my menu" (user profile/actions).
• household: Parameter household (instance of Chill\PersonBundle\Entity\Household\Household). Used in the household file.

Good Examples

For more complex implementations, you can refer to:

• src/Bundle/ChillTicketBundle/src/Menu/PersonMenuBuilder.php
• src/Bundle/ChillTicketBundle/src/Menu/SectionMenuBuilder.php
• src/Bundle/ChillDocGeneratorBundle/Menu/AdminMenuBuilder.php
• src/Bundle/ChillDocStoreBundle/Menu/MenuBuilder.php
• src/Bundle/ChillPersonBundle/Menu/UserMenuBuilder.php
• src/Bundle/ChillPersonBundle/Menu/HouseholdMenuBuilder.php