.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". Routing and menus ***************** The *Chill*'s architecture allows to choose bundle on each installation. This may lead to a huge diversity of installations, and a the developper challenge is to make his code working 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. .. seealso:: `Symfony documentation about routing `_ This documentation should be read before diving into those lines `Routes dans Chill `_ (FR) The issue where we discussed routes. In French. Create routes ============== .. note:: We recommand 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 create a route in symfony, and add some options in his description : .. code-block:: yaml chill_main_dummy_0: pattern: /dummy/{personId} defaults: { _controller: CLChillMainBundle:Default:index } options: #we begin menu information here : menus: foo: #must appears in menu named 'foo' order: 500 #the order will be '500' label: foolabel #the label shown on menu. Will be translated otherkey: othervalue #you may add other informations, as needed by your layout bar: #must also appears in menu named 'bar' order: 500 label: barlabel The mandatory parameters under the `menus` definition are : * `name`: the menu's name, defined as an key for the following entries * `order`. Note: if we have duplicate order's values, the order will be incremented. We recommand using big intervals within orders and publishing the orders in your documentation * `label`: the text which will be rendered inside the `` 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 .. warning:: 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 informations to him * `access` : which will run a test with `Expression Langage `_ 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 appears 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 : .. code-block:: jinja {{ 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 : .. code-block:: jinja {{ 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()`). .. note:: 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. .. warning:: 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 : .. code-block:: jinja {{ 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 : .. code-block:: html+jinja #MyBundle/Resources/views/Menu/MyMenu.html.twig 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 : .. code-block:: jinja {{ chill_menu('foo', { 'layout' : 'MyBundle:Menu:MyMenu.html.twig' } ) }} .. note:: Take care of specifying the absolute path to layout in the function. .. rubric:: Footnotes .. [#f1] In the default template, the currently active entry will be rendered with an "active" class : `
  • ...
    • `