diff --git a/source/development/flashbags.rst b/source/development/flashbags.rst new file mode 100644 index 000000000..d6334a7a3 --- /dev/null +++ b/source/development/flashbags.rst @@ -0,0 +1,35 @@ +.. 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". + +.. _flashbags : + +Flashbags: message to users +**************************** + +The four following levels are defined : + ++-----------+----------------------------------------------------------------------------------------------+ +|Key |Intent | ++===========+==============================================================================================+ +|alert |A message not linked with the user action, but which should require an action or a | +| |correction. | ++-----------+----------------------------------------------------------------------------------------------+ +|success |The user action succeeds. | ++-----------+----------------------------------------------------------------------------------------------+ +|notice |A simple message to give information to the user. The message may be linked or not linked with| +| |the user action. | ++-----------+----------------------------------------------------------------------------------------------+ +|warning |A message linked with an action, the user should correct. | ++-----------+----------------------------------------------------------------------------------------------+ +|error |The user's action failed: he must correct something to process the action. | ++-----------+----------------------------------------------------------------------------------------------+ + +.. seealso:: + + `Flash Messages on Symfony documentation `_ + Learn how to use flash messages in controller. diff --git a/source/development/index.rst b/source/development/index.rst index c06ca6db5..6eef8cdd5 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -16,6 +16,8 @@ As Chill rely on the `symfony `_ framework, reading the fram Install Chill for development Instructions to create a new bundle + Menus + Message to users Testing manual/index.rst Official bundle's documentation diff --git a/source/development/menus.rst b/source/development/menus.rst new file mode 100644 index 000000000..5e6cda3ea --- /dev/null +++ b/source/development/menus.rst @@ -0,0 +1,123 @@ +.. 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". + +.. _menus : + +Menus +***** + +Chill has created his own menu system + +.. seealso:: + + `Routes dans Chill [specification] `_ + The issue wich discussed the implementation of routes. + +Concepts +======== + +.. warning:: + + to be written + + + +Add a menu in a template +======================== + +In your twig template, use the `chill_menu` function : + +.. code-block:: html+jinja + + {{ chill_menu('person', { + 'layout': 'ChillPersonBundle::menu.html.twig', + 'args' : {'id': person.id }, + 'activeRouteKey': 'chill_person_view' + }) }} + +The available arguments are: + +* `layout` : a custom layout. Default to `ChillMainBundle:Menu:defaultMenu.html.twig` +* `args` : those arguments will be passed through the url generator. +* `activeRouteKey` must be the route key name. + +.. note:: + + The argument `activeRouteKey` may be a twig variable, defined elsewhere in your template, even in child templates. + + + +Create an entry in an existing menu +=================================== + +If a route belongs to a menu, you simply add this to his definition in routing.yml : + +.. code-block:: yaml + + chill_person_history_list: + pattern: /person/{person_id}/history + defaults: { _controller: ChillPersonBundle:History:list } + options: + #declare menus + menus: + # the route should be in 'person' menu : + person: + #and have those arguments : + order: 100 + label: menu.person.history + +* `order` (mandatory) : the order in the menu. It is preferrable to increment by far more than 1. +* `label` (mandatory) : a translatable string. +* `helper` (optional) : a text to help people to understand what does the menu do. Not used in default implementation. +* `condition` (optional) : an `Expression Language `_ which will make the menu appears or not. Typically, it may be used to say "show this menu only if the person concerned is more than 18". **Not implemented yet**. +* `access` (optional) : an Expression Language to evalute the possibility, for the user, to show this menu according to Access Control Model. **Not implemented yet.** + +You may add additional keys, but should not use the keys described above. + +You may add the same route to multiple menus : + +.. code-block:: yaml + + chill_person_history_list: + pattern: /person/{person_id}/history + defaults: { _controller: ChillPersonBundle:History:list } + options: + menus: + menu1: + order: 100 + label: menu.person.history + menu2: + order: 100 + label: another.label + + + +Customize menu rendering +======================== + +You may customize menu rendering by using the `layout` option. + +.. warning :: + + TODO : this part should be written. + + + + + + +.. _caveats : + +Caveats +======= + +Currently, you may pass arguments globally to each menu, and they will be all passed to route url. This means that : + +* the argument name in the route entry must match the argument key in menu declaration in twig template +* if an argument is missing to generate an url, the url generator will throw an error +* if the argument name is not declared in route entry, it will be added to the url, (example: `/my/route?additional=foo`)