Change all content from rst format to markdown and correct spelling/grammar

docs/source/development/manual/routing-and-menus.md

@@ -0,0 +1,103 @@
+###### 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.