###### Routing and menus

The architecture of *Chill* allows choosing a bundle on each installation. This may lead to a huge diversity of installations, and the developper challenge is to make his code work with all those possibles installations.

*Chill* uses menus to let users access easily to the most used functionalities. For instance, when you land on a "Person" page, you may access directly to his activities, notes, documents, ... in a single click on a side menu.

For a developer, it is easy to extend this menu with his own entries.

   [Symfony documentation about routing ](http://symfony.com/doc/current/book/routing.html)
      This documentation should be read before diving into those lines

   [Routes dans Chill ](https://redmine.champs-libres.coop/issues/179) (FR)
      The issue where we discussed routes. In French.

## Create routes

   We recommend using `yaml` to define routes. We have not tested the existing other ways to create routes (annotations, ...). Help wanted.

The first step is as easy as creating a route in symfony, and add some options in his description :

```yaml
#src/CL/ChillBundle/Resources/config/routing.yml
   chill_main_dummy_0:
       pattern: /dummy/{personId}
       defaults: { _controller: CLChillMainBundle:Default:index }
       options:
           #we begin menu information here :
           menus:
               foo: #must appear in a menu named 'foo'
                   order: 500  #the order will be '500'
                   label: foolabel #the label shown on a menu. Will be translated
                   otherkey: othervalue #you may add other information, as needed by your layout
               bar: #must also appear in a menu named 'bar'
                   order: 500
                   label: barlabel
```

The mandatory parameters under the `menus` definition are :

* `name`: the menu's name, defined as a key for the following entries
* `order`. Note: if we have duplicate order's values, the order will be incremented. We recommend using big intervals within orders and publishing the orders in your documentation
* `label`: the text which will be rendered inside the `<a>[ tag. The label should be processed trough the `trans` filter (`{{ route.label|trans }}`)

You *may* also add other keys, which will be used optionally in the way the menu is rendered. See

   Although all keys will be kept from your `yaml` definition to your menu template, we recommend not using those keys, which are reserved for a future implementations of Chill :

   * `helper`, a text to help user or add more information to him
   * `access` : which will run a test with `Expression Langage ](http://symfony.com/doc/current/components/expression_language/index.html) to determine if the user has the ACL to show the menu entry ;
   * `condition`, which will test with the menu context if the entry must appear

## Show menu in twig templates

To show our previous menu in the twig template, we invoke the `chill_menu` function. This will render the `foo` menu :

   `{{ chill_menu('foo') }}`

##### Passing variables

If your routes need arguments, i.e. an entity id, you should pass the as argument to the chill_menu function. If your route's pattern is `/person/{personId}`, your code become :

   `{{ chill_menu('foo', { 'args' : { 'personId' : person.id } } ) }}`

Of course, `person` is a variable you must define in your code, which should have an `id` accessible property (i.e. : `$person->getId()`).

   Be aware that your arguments will be passed to all routes in a menu. If a route does not require `personId` in his pattern, the route will become `/pattern?personId=XYZ`. This should not cause problem in your application.

   It is a good idea to reuse the same parameter's name in your pattern, to avoid collision. Prefer `/person/{personId}` to `/person/{id}`.

   If you don't do that and another developer create a bundle with  `person/{personId}/{id}` where `{id}` is the key for something else, this will cause a lot of trouble...

##### Rendering active entry

Now, you want to render differently the *active* route of the menu [#f1]_. You should, in your controller or template, add the active route in your menu :

   `{{ chill_menu('foo', { 'activeRouteKey' : 'chill_main_dummy_0' } ) }}`

On menu creation, the route wich has the key `chill_main_dummy_0` will be rendered on a different manner.

### Define your own template

By default, the menu is rendered with the default template, which is a simple `ul` list. You may create your own templates :

```
   #MyBundle/Resources/views/Menu/MyMenu.html.twig
   <ul class="myMenu">
   {% for route in routes %}
       <li><a href="{{ path(route.key, args ) }}" class="{%- if activeRouteKey == route.key -%}active{%- endif -%}">{{ route.label|trans }}</a></li>
   {% endfor %}
   </ul>
```

Arguments available in your template :

* The `args` value are the value passed in the 'args' arguments requested by the `chill_menu` function.
* `activeRouteKey` is the key of the currently active route.
* `routes` is an array of routes. The array has this structure: `routes[order] = { 'key' : 'the_route_key', 'label' : 'the route label' }` The order is *resolved*: in case of collision (two routes from different bundles having the same order), the order will be incremented. You may find in the array your own keys (`{ 'otherkey' : 'othervalue'}` in the example above).

Then, you will call your own template with the `layout` argument :

   `{{ chill_menu('foo', { 'layout' : 'MyBundle:Menu:MyMenu.html.twig' } ) }}`

   Take care of specifying the absolute path to layout in the function.