###### 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:

```twig
{{ 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:

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

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

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

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

### Adding a counter

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

```php
$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](https://forkaweso.me/Fork-Awesome/icons/) icon name (without the `fa-` prefix).

```php
$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`