Skip to content

Commit 5d561ad

Browse files
garakgarak
committed
update docs
1 parent ce65f8e commit 5d561ad

8 files changed

+71
-95
lines changed

Diff for: ‎docs/custom_provider.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Create first your Provider class, in the Provider directory of your bundle:
99

1010
.. code-block:: php
1111
12-
namespace AppBundle\Provider;
12+
namespace App\Provider;
1313
1414
use Knp\Menu\FactoryInterface;
1515
use Knp\Menu\Provider\MenuProviderInterface;
@@ -77,10 +77,10 @@ Then, configure the services linked to this new provider.
7777

7878
.. code-block:: yaml
7979
80-
# app/config/services.yml
80+
# config/services.yaml or app/config/services.yml
8181
services:
82-
app.menu_provider:
83-
class: AppBundle\Provider\CustomMenuProvider
82+
app.menu_provider:
83+
class: App\Provider\CustomMenuProvider
8484
arguments:
8585
- '@knp_menu.factory'
8686
tags:

Diff for: ‎docs/custom_renderer.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ of creating a service tagged with ``knp_menu.renderer``:
66

77
.. code-block:: yaml
88
9-
# app/config/services.yml
9+
# config/services.yaml
1010
services:
1111
app.menu_renderer:
1212
# The class implements Knp\Menu\Renderer\RendererInterface
13-
class: AppBundle\Menu\CustomRenderer
13+
class: App\Menu\CustomRenderer
1414
arguments: ["%kernel.charset%"] # set your own dependencies here
1515
tags:
1616
# The alias is what is used to retrieve the menu
@@ -23,11 +23,11 @@ The configuration is then the following:
2323

2424
.. code-block:: yaml
2525
26-
# app/config/services.yml
26+
# config/services.yaml
2727
services:
2828
app.menu_renderer:
2929
# The class implements Knp\Menu\Renderer\RendererInterface
30-
class: AppBundle\Menu\CustomRenderer
30+
class: App\Menu\CustomRenderer
3131
arguments:
3232
- '@knp_menu.matcher'
3333
- '%knp_menu.renderer.list.options%'

Diff for: ‎docs/disabling_providers.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ configuration:
1010

1111
.. code-block:: yaml
1212
13-
#app/config/config.yml
13+
# config/packages/knp_menu.yaml
1414
knp_menu:
1515
providers:
1616
builder_alias: false # disable the builder-alias-based provider

Diff for: ‎docs/events.rst

+10-23
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ to allow other parts of your application to add more stuff to it.
1313

1414
.. code-block:: php
1515
16-
// src/AppBundle/Menu/MainBuilder.php
16+
// src/Menu/MainBuilder.php
1717
18-
namespace AppBundle\Menu;
18+
namespace App\Menu;
1919
20-
use AppBundle\Event\ConfigureMenuEvent;
20+
use App\Event\ConfigureMenuEvent;
2121
use Knp\Menu\FactoryInterface;
2222
use Symfony\Component\DependencyInjection\ContainerAwareInterface;
2323
use Symfony\Component\DependencyInjection\ContainerAwareTrait;
@@ -44,7 +44,7 @@ to allow other parts of your application to add more stuff to it.
4444
.. note::
4545

4646
This implementation assumes you use the ``BuilderAliasProvider`` (getting
47-
your menu as ``AppBundle:MainBuilder:build``) but you could also define
47+
your menu as ``App:MainBuilder:build``) but you could also define
4848
it as a service and inject the ``event_dispatcher`` service as a dependency.
4949

5050
Create the Event object
@@ -55,9 +55,9 @@ it will hold the menu being created and the factory.
5555

5656
.. code-block:: php
5757
58-
// src/AppBundle/Event/ConfigureMenuEvent.php
58+
// src/Event/ConfigureMenuEvent.php
5959
60-
namespace AppBundle\Event;
60+
namespace App\Event;
6161
6262
use Knp\Menu\FactoryInterface;
6363
use Knp\Menu\ItemInterface;
@@ -70,10 +70,6 @@ it will hold the menu being created and the factory.
7070
private $factory;
7171
private $menu;
7272
73-
/**
74-
* @param \Knp\Menu\FactoryInterface $factory
75-
* @param \Knp\Menu\ItemInterface $menu
76-
*/
7773
public function __construct(FactoryInterface $factory, ItemInterface $menu)
7874
{
7975
$this->factory = $factory;
@@ -97,11 +93,6 @@ it will hold the menu being created and the factory.
9793
}
9894
}
9995
100-
.. note::
101-
102-
Following the Symfony best practices, the first segment of the event name will
103-
be the alias of the bundle, which allows avoiding conflicts.
104-
10596
That's it. Your builder now provides a hook. Let's see how you can use it!
10697

10798
Create a listener
@@ -115,14 +106,11 @@ You can register as many listeners as you want for the event. Let's add one.
115106
116107
namespace Acme\AdminBundle\EventListener;
117108
118-
use AppBundle\Event\ConfigureMenuEvent;
109+
use App\Event\ConfigureMenuEvent;
119110
120111
class ConfigureMenuListener
121112
{
122-
/**
123-
* @param \AppBundle\Event\ConfigureMenuEvent $event
124-
*/
125-
public function onMenuConfigure(ConfigureMenuEvent $event)
113+
public function __invoke(ConfigureMenuEvent $event)
126114
{
127115
$menu = $event->getMenu();
128116
@@ -135,12 +123,11 @@ You can now register the listener.
135123

136124
.. code-block:: yaml
137125
138-
# app/config/services.yml
126+
# config/services.yaml
139127
services:
140128
app.admin_configure_menu_listener:
141129
class: Acme\AdminBundle\EventListener\ConfigureMenuListener
142-
tags:
143-
- { name: kernel.event_listener, event: app.menu_configure, method: onMenuConfigure }
130+
tags: [kernel.event_listener]
144131
145132
146133
You could also create your listener as a subscriber and use the ``kernel.event_subscriber``

Diff for: ‎docs/i18n.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ The items "Home" and "Login" can now be translated in the message domain:
1515

1616
.. code-block:: yaml
1717
18-
# app/Resources/translations/messages.fr.yml
18+
# translations/messages.fr.yaml
1919
Home: Accueil
2020
Login: Connexion
2121
2222
.. code-block:: xml
2323
24-
<!-- app/Resources/translations/messages.fr.xlf -->
24+
<!-- translations/messages.fr.xliff -->
2525
<?xml version="1.0"?>
2626
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
2727
<file source-language="en" datatype="plaintext" original="file.ext">
@@ -41,7 +41,7 @@ The items "Home" and "Login" can now be translated in the message domain:
4141
4242
.. code-block:: php
4343
44-
// app/Resources/translations/messages.fr.php
44+
// translations/messages.fr.php
4545
return [
4646
'Home' => 'Accueil',
4747
'Login' => 'Connexion',

Diff for: ‎docs/index.rst

+32-32
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,22 @@ following command to download the latest stable version of this bundle:
1414

1515
.. code-block:: bash
1616
17-
$ composer require knplabs/knp-menu-bundle "^2.0"
17+
$ composer require knplabs/knp-menu-bundle
1818
1919
This command requires you to have Composer installed globally, as explained
2020
in the `installation chapter`_ of the Composer documentation.
2121

2222
Step 2: Enable the Bundle
2323
~~~~~~~~~~~~~~~~~~~~~~~~~
2424

25-
Then, enable the bundle by adding the following line in the ``app/AppKernel.php``
26-
file of your project:
25+
KnpMenuBundle should be automatically enabled and configured, thanks to `Flex`_.
26+
27+
If you don't use Flex, you can manually enable it, by adding the following line in
28+
your project's Kernel:
2729

2830
.. code-block:: php
2931
30-
// app/AppKernel.php
32+
// e.g. app/AppKernel.php
3133
3234
// ...
3335
class AppKernel extends Kernel
@@ -56,7 +58,7 @@ You can define these options if you need to change them:
5658

5759
.. code-block:: yaml
5860
59-
# app/config/config.yml
61+
# config/packages/knp_menu.yaml
6062
knp_menu:
6163
# use "twig: false" to disable the Twig extension and the TwigRenderer
6264
twig:
@@ -68,7 +70,7 @@ You can define these options if you need to change them:
6870
6971
.. code-block:: xml
7072
71-
<!-- app/config/config.xml -->
73+
<!-- config/packages/knp_menu.xml -->
7274
<?xml version="1.0" charset="UTF-8" ?>
7375
<container xmlns="http://symfony.com/schema/dic/services"
7476
xmlns:knp-menu="http://knplabs.com/schema/dic/menu">
@@ -88,7 +90,7 @@ You can define these options if you need to change them:
8890
8991
.. code-block:: php
9092
91-
// app/config/config.php
93+
// config/packages/knp_menu.php
9294
$container->loadFromExtension('knp_menu', [
9395
// use 'twig' => false to disable the Twig extension and the TwigRenderer
9496
'twig' => [
@@ -100,11 +102,6 @@ You can define these options if you need to change them:
100102
'default_renderer' => 'twig',
101103
]);
102104
103-
.. versionadded::2.1.2
104-
105-
The template used to be ``knp_menu.html.twig`` which did not translate menu entries.
106-
Version 2.1.2 adds the template that translates menu entries.
107-
108105
.. note::
109106

110107
Take care to change the default renderer if you disable the Twig support.
@@ -126,18 +123,20 @@ An example builder class would look like this:
126123

127124
.. code-block:: php
128125
129-
// src/AppBundle/Menu/Builder.php
130-
namespace AppBundle\Menu;
126+
// src/Menu/Builder.php
127+
namespace App\Menu;
131128
129+
use App\Entity\Blog;
132130
use Knp\Menu\FactoryInterface;
131+
use Knp\Menu\ItemInterface;
133132
use Symfony\Component\DependencyInjection\ContainerAwareInterface;
134133
use Symfony\Component\DependencyInjection\ContainerAwareTrait;
135134
136-
class Builder implements ContainerAwareInterface
135+
final class Builder implements ContainerAwareInterface
137136
{
138137
use ContainerAwareTrait;
139138
140-
public function mainMenu(FactoryInterface $factory, array $options)
139+
public function mainMenu(FactoryInterface $factory, array $options): ItemInterface
141140
{
142141
$menu = $factory->createItem('root');
143142
@@ -146,7 +145,7 @@ An example builder class would look like this:
146145
// access services from the container!
147146
$em = $this->container->get('doctrine')->getManager();
148147
// findMostRecent and Blog are just imaginary examples
149-
$blog = $em->getRepository('AppBundle:Blog')->findMostRecent();
148+
$blog = $em->getRepository(Blog::class)->findMostRecent();
150149
151150
$menu->addChild('Latest Blog Post', [
152151
'route' => 'blog_show',
@@ -199,18 +198,18 @@ To actually render the menu, just do the following from anywhere in any template
199198

200199
.. code-block:: html+jinja
201200

202-
{{ knp_menu_render('AppBundle:Builder:mainMenu') }}
201+
{{ knp_menu_render('App:Builder:mainMenu') }}
203202

204203
.. code-block:: html+php
205204

206-
<?php echo $view['knp_menu']->render('AppBundle:Builder:mainMenu') ?>
205+
<?php echo $view['knp_menu']->render('App:Builder:mainMenu') ?>
207206

208207
With this method, you refer to the menu using a three-part string:
209208
**bundle**:**class**:**method**.
210209

211210
If you needed to create a second menu, you'd simply add another method to
212211
the ``Builder`` class (e.g. ``sidebarMenu``), build and return the new menu,
213-
then render it via ``AppBundle:Builder:sidebarMenu``.
212+
then render it via ``App:Builder:sidebarMenu``.
214213

215214
That's it! The menu is *very* configurable. For more details, see the
216215
`KnpMenu documentation`_.
@@ -242,23 +241,23 @@ way, then do the following:
242241

243242
.. code-block:: html+jinja
244243

245-
{{ knp_menu_render('AppBundle:Builder:mainMenu') }}
244+
{{ knp_menu_render('App:Builder:mainMenu') }}
246245

247246
.. code-block:: html+php
248247

249-
<?php echo $view['knp_menu']->render('AppBundle:Builder:mainMenu') ?>
248+
<?php echo $view['knp_menu']->render('App:Builder:mainMenu') ?>
250249

251250
Additionally, you can pass some options to the renderer:
252251

253252
.. configuration-block::
254253

255254
.. code-block:: html+jinja
256255

257-
{{ knp_menu_render('AppBundle:Builder:mainMenu', {'depth': 2, 'currentAsLink': false}) }}
256+
{{ knp_menu_render('App:Builder:mainMenu', {'depth': 2, 'currentAsLink': false}) }}
258257

259258
.. code-block:: html+php
260259

261-
<?php echo $view['knp_menu']->render('AppBundle:Builder:mainMenu', [
260+
<?php echo $view['knp_menu']->render('App:Builder:mainMenu', [
262261
'depth' => 2,
263262
'currentAsLink' => false,
264263
]) ?>
@@ -272,12 +271,12 @@ You can also "get" a menu, which you can use to render later:
272271

273272
.. code-block:: html+jinja
274273

275-
{% set menuItem = knp_menu_get('AppBundle:Builder:mainMenu') %}
274+
{% set menuItem = knp_menu_get('App:Builder:mainMenu') %}
276275
{{ knp_menu_render(menuItem) }}
277276

278277
.. code-block:: html+php
279278

280-
<?php $menuItem = $view['knp_menu']->get('AppBundle:Builder:mainMenu') ?>
279+
<?php $menuItem = $view['knp_menu']->get('App:Builder:mainMenu') ?>
281280
<?php echo $view['knp_menu']->render($menuItem) ?>
282281

283282
If you want to only retrieve a certain branch of the menu, you can do the
@@ -288,13 +287,13 @@ beneath it.
288287

289288
.. code-block:: html+jinja
290289

291-
{% set menuItem = knp_menu_get('AppBundle:Builder:mainMenu', ['Contact']) %}
292-
{{ knp_menu_render(['AppBundle:Builder:mainMenu', 'Contact']) }}
290+
{% set menuItem = knp_menu_get('App:Builder:mainMenu', ['Contact']) %}
291+
{{ knp_menu_render(['App:Builder:mainMenu', 'Contact']) }}
293292

294293
.. code-block:: html+php
295294

296-
<?php $menuItem = $view['knp_menu']->get('AppBundle:Builder:mainMenu', ['Contact']) ?>
297-
<?php echo $view['knp_menu']->render(['AppBundle:Builder:mainMenu', 'Contact']) ?>
295+
<?php $menuItem = $view['knp_menu']->get('App:Builder:mainMenu', ['Contact']) ?>
296+
<?php echo $view['knp_menu']->render(['App:Builder:mainMenu', 'Contact']) ?>
298297

299298
If you want to pass some options to the builder, you can use the third parameter
300299
of the ``knp_menu_get`` function:
@@ -303,12 +302,12 @@ of the ``knp_menu_get`` function:
303302

304303
.. code-block:: html+jinja
305304

306-
{% set menuItem = knp_menu_get('AppBundle:Builder:mainMenu', [], {'some_option': 'my_value'}) %}
305+
{% set menuItem = knp_menu_get('App:Builder:mainMenu', [], {'some_option': 'my_value'}) %}
307306
{{ knp_menu_render(menuItem) }}
308307

309308
.. code-block:: html+php
310309

311-
<?php $menuItem = $view['knp_menu']->get('AppBundle:Builder:mainMenu', [], [
310+
<?php $menuItem = $view['knp_menu']->get('App:Builder:mainMenu', [], [
312311
'some_option' => 'my_value'
313312
]) ?>
314313
<?php echo $view['knp_menu']->render($menuItem) ?>
@@ -328,4 +327,5 @@ More Advanced Stuff
328327
disabling_providers
329328

330329
.. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
330+
.. _`Flex`: https://flex.symfony.com
331331
.. _`KnpMenu documentation`: https://github.com/KnpLabs/KnpMenu/blob/master/doc/01-Basic-Menus.md

0 commit comments

Comments
 (0)