add doc for menus and flashbag

This commit is contained in:
Julien Fastré 2014-11-07 15:57:07 +01:00
parent 91ca709cf9
commit 515b8a0762
3 changed files with 160 additions and 0 deletions

View File

@ -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 <http://symfony.com/doc/current/book/controller.html#flash-messages>`_
Learn how to use flash messages in controller.

View File

@ -16,6 +16,8 @@ As Chill rely on the `symfony <http://symfony.com>`_ framework, reading the fram
Install Chill for development <installation.rst>
Instructions to create a new bundle <create-a-new-bundle.rst>
Menus <menus.rst>
Message to users <flashbags.rst>
Testing <make-test-working.rst>
manual/index.rst
Official bundle's documentation <bundles/index.rst>

View File

@ -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] <https://redmine.champs-libres.coop/issues/179>`_
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 <http://symfony.com/doc/current/components/expression_language/index.html> `_ 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`)