From 709794eab73708afb836f4687e311df453f4ce7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Tue, 14 Oct 2014 22:27:08 +0200 Subject: [PATCH 1/5] doc for routing and menus --- .../development/manual/routing-and-menus.rst | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/source/development/manual/routing-and-menus.rst b/source/development/manual/routing-and-menus.rst index 6bbf3bc5c..5786f3fda 100644 --- a/source/development/manual/routing-and-menus.rst +++ b/source/development/manual/routing-and-menus.rst @@ -8,3 +8,136 @@ 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 : `
  • ...
    • ` From e9667ef8d621a61d7fca99c89f41343947bafc20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Tue, 14 Oct 2014 22:28:13 +0200 Subject: [PATCH 2/5] fix footnotes --- source/development/create-a-new-bundle.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/development/create-a-new-bundle.rst b/source/development/create-a-new-bundle.rst index b1a581bd4..7c987a70d 100644 --- a/source/development/create-a-new-bundle.rst +++ b/source/development/create-a-new-bundle.rst @@ -27,4 +27,6 @@ The easiest way to achieve this is seems to be : TODO +.. rubric:: Footnotes + .. [#f1] Be aware that we use the Affero GPL Licence, which ensure that all users must have access to derivative works done with this software. From 74f2b23b5412a8a618081248180d685770e84e77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Tue, 14 Oct 2014 22:32:51 +0200 Subject: [PATCH 3/5] typo in structure to emphasis --- source/development/manual/routing-and-menus.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/development/manual/routing-and-menus.rst b/source/development/manual/routing-and-menus.rst index 5786f3fda..c3b8b61cb 100644 --- a/source/development/manual/routing-and-menus.rst +++ b/source/development/manual/routing-and-menus.rst @@ -10,9 +10,9 @@ 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. +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. +*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. From 0e5cf6fe86cee3237267d2dd7c2d775bc510e0e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 17 Oct 2014 07:56:38 +0200 Subject: [PATCH 4/5] update project name --- source/installation/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 518acf42f..03ddd8710 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -89,7 +89,7 @@ Create your Chill project using composer: .. code-block:: bash - php composer.phar create-project champs-libres/chill-standard \ + php composer.phar create-project chill-project/standard \ path/to/your/directory --stability=dev .. note:: From b424ec49bcf9a08a44449d3c62c04761cb5b3da7 Mon Sep 17 00:00:00 2001 From: Marc Ducobu Date: Fri, 17 Oct 2014 17:29:06 +0200 Subject: [PATCH 5/5] Refactoring : champs-libres -> chill-project --- source/development/installation.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/development/installation.rst b/source/development/installation.rst index 6c5783ebb..87af17d5b 100644 --- a/source/development/installation.rst +++ b/source/development/installation.rst @@ -26,7 +26,7 @@ At first, You should add the `--prefer-source` argument when you create project. .. code-block:: bash - php composer.phar create-project champs-libres/chill-standard \ + php composer.phar create-project chill-project/standard \ path/to/your/directory --stability=dev --prefer-source Secondly, if composer ask you the following question : :: @@ -39,12 +39,12 @@ This will install a project. All downloaded modules will be stored in the `/vend .. code-block:: bash - $ cd vendor/champs-libres/chill-main/ + $ cd vendor/chill-project/main/ $ git remote -v - composer git://github.com/Champs-Libres/ChillMain.git (fetch) - composer git://github.com/Champs-Libres/ChillMain.git (push) - origin git://github.com/Champs-Libres/ChillMain.git (fetch) - origin git@github.com:Champs-Libres/ChillMain.git (push) + composer git://github.com/Chill-project/Standard.git (fetch) + composer git://github.com/Chill-project/Standard.git (push) + origin git://github.com/Chill-project/Standard.git (fetch) + origin git@github.com:Chill-project/Standard.git (push) Working with your own fork ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -100,7 +100,7 @@ The command `composer status` (`see composer documentation