Skip to content
This repository has been archived by the owner on Sep 16, 2021. It is now read-only.

update menu bundle documentation for cmf 2.0 #822

Merged
merged 1 commit into from
Jun 12, 2017
Merged

update menu bundle documentation for cmf 2.0 #822

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion bundles/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ library or they introduce a complete new concept.
* :doc:`menu/menu_factory`
* :doc:`menu/menu_provider`
* :doc:`menu/voters`
* :doc:`menu/sonata_admin`
* :doc:`menu/configuration`

* :doc:`routing/index`
Expand Down
128 changes: 12 additions & 116 deletions bundles/menu/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,16 +26,11 @@ persistence configuration has the following configuration:
phpcr:
enabled: false
menu_basepath: /cms/menu
content_basepath: ~
prefetch: 10
content_basepath: /cms/content
manager_name: ~
prefetch: 10
menu_document_class: Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu
node_document_class: Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode
use_sonata_admin: ~
menu_admin_class: Symfony\Cmf\Bundle\MenuBundle\Admin\MenuAdmin
node_admin_class: Symfony\Cmf\Bundle\MenuBundle\Admin\MenuNodeAdmin
admin_recursive_breadcrumbs: true


.. code-block:: xml

Expand All @@ -47,15 +42,11 @@ persistence configuration has the following configuration:
<phpcr
enabled="false"
menu-basepath="/cms/menu"
content-basepath="null"
prefetch="10"
content-basepath="/cms/content"
manager-name="null"
menu-document-class="null"
node-document-class="null"
use-sonata-admin="auto"
menu-admin-class="null"
node-admin-class="null"
admin-recursive-breadcrumbs="true"
prefetch="10"
menu-document-class="Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu"
node-document-class="Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode"
/>
</persistence>
</config>
Expand All @@ -69,15 +60,11 @@ persistence configuration has the following configuration:
'phpcr' => [
'enabled' => false,
'menu_basepath' => '/cms/menu',
'content_basepath' => null,
'prefetch' => 10,
'content_basepath' => '/cms/content',
'manager_name' => null,
'menu_document_class' => null,
'node_document_class' => null,
'use_sonata_admin' => 'auto',
'menu_admin_class' => null,
'node_admin_class' => null,
'admin_recursive_breadcrumbs' => true,
'prefetch' => 10,
'menu_document_class' => \Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu::class,
'node_document_class' => \Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode::class,
],
],
]);
Expand Down Expand Up @@ -109,8 +96,8 @@ the value of ``%cmf_core.persistence.phpcr.basepath%/menu``
**type**: ``string`` **default**: ``/cms/content``

Specifies the path in the PHPCR-ODM document hierarchy under which the
content documents can be found. This is used by the admin class to pre-select
the content branch of the document hierarchy in forms.
content documents can be found. This is used by the sonata admin integration to
know which subtree to show when selecting content for menu nodes.

If the :doc:`CoreBundle <../core/introduction>` is registered, this will default to
the value of ``%cmf_core.persistence.phpcr.basepath%/content``
Expand Down Expand Up @@ -156,33 +143,6 @@ Specifies the document class which should represent a single menu node.

This setting is used by the admin class.

``use_sonata_admin``
""""""""""""""""""""

.. include:: ../_partials/persistence_phpcr_sonata_admin_enabled.rst.inc

``menu_admin_class``
""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\MenuBundle\Admin\MenuAdmin``

The Sonata admin class to use for the menu.

``node_admin_class``
""""""""""""""""""""

**type**: ``string`` **default**: ``Symfony\Cmf\Bundle\MenuBundle\Admin\MenuNodeAdmin``

The Sonata admin class to use for the menu node.

``admin_recursive_breadcrumbs``
"""""""""""""""""""""""""""""""

**type**: ``boolean`` **default**: ``true``

When editing a node, this setting will cause the Sonata admin breadcrumb to
include ancestors of the node being edited.

content_url_generator
~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -203,70 +163,6 @@ allow_empty_items
Whether menu nodes without URL should be hidden or rendered as text without a
link.

Admin Extensions
----------------

The ``admin_extensions`` section contains the configurations of the admin extensions that comes with the menu bundle.

``menu_options``
~~~~~~~~~~~~~~~~

You can configure the menu options extension in this sections.

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
cmf_menu:
# ...
cmf_menu:
admin_extensions:
menu_options:
enabled: auto
advanced: false

.. code-block:: xml

<!-- app/config/config.xml -->
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">
<config xmlns="http://cmf.symfony.com/schema/dic/menu">
<admin_extensions>
<menu_options
enabled="auto"
advanced="false"
/>
</admin_extensions>
</config>
</container>

.. code-block:: php

// app/config/config.php
$container->loadFromExtension('cmf_menu', [
'admin_extensions' => [
'menu_options' => [
'enabled' => 'auto',
'advanced' => false,
],
],
]);

``enabled``
"""""""""""
**type**: ``enum`` **valid values**: ``true|false|auto`` **default**: ``auto``

If ``true``, the admin extension is activated. If set to ``auto``, it will be
activated only if the SonataAdminBundle is present.

``advanced``
""""""""""""
**type**: ``boolean`` **default**: ``false``

if set to ``true`` it will expose the advanced options in the admin.
To enable this options you need ``BurgovKeyValueFormBundle``

Voter
-----

Expand Down
1 change: 0 additions & 1 deletion bundles/menu/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,4 @@ MenuBundle
menu_factory
menu_provider
voters
sonata_admin
configuration
43 changes: 20 additions & 23 deletions bundles/menu/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,15 @@ features:
* Render menus stored in the persistence layer;
* Generate menu node URLs from linked Content or Route.

Note that only the Doctrine PHPCR-ODM persistence layer is currently supported.
Note that this bundle currently only provides models for the Doctrine PHPCR-ODM
persistence layer.

.. caution::

Make sure you understand how the `KnpMenuBundle`_ works when you want to
customize the CmfMenuBundle. The CMF menu bundle is just adding
functionality on top of the Knp menu bundle and this documentation is
focused on the additional functionality.
functionality on top of KnpMenuBundle and this documentation is focused on
the additional functionality.

Installation
------------
Expand All @@ -27,7 +28,7 @@ You can install this bundle `with composer`_ using the
`symfony-cmf/menu-bundle`_ package.

As the bundle is using the `KnpMenuBundle`_, you need to instantiate that
bundles in addition to the CmfMenuBundle::
bundle in addition to the CmfMenuBundle::

// app/AppKernel.php

Expand All @@ -51,19 +52,17 @@ bundles in addition to the CmfMenuBundle::
Creating a Simple Persistent Menu
---------------------------------

A menu created using the KnpMenuBundle is made up of a hierarchy of class
instances implementing ``NodeInterface``. This is also true of a menu created
using MenuBundle documents.
For KnpMenu_, a menu is made up of a hierarchy of objects implementing
``ItemInterface``. KnpMenu provides the concept of factories to create menus
from ``NodeInterface``. This bundle contains a provider to load menu nodes from
PHPCR.

It is recommended that the root document of the menu tree is a ``Menu``
document, all descendant documents should be ``MenuNode`` instances.
The root document of each menu tree is a ``Menu`` document, all descendant
documents should be ``MenuNode`` instances. The menu roots are placed under the
``cmf_menu.persistence.phpcr.menu_basepath``, which defaults to ``/cms/menu``.

The root document should be a child of the document specified in the configuration
by the parameter ``persistence.phpcr.menu_basepath``, which defaults to ``/cms/menu``. Note
that if this document does not exist it must be created.

The example below creates a new menu with two items, "Home" and "Contact",
each of which specifies a URI::
The example below creates a new menu called "Main Menu" with two nodes, "Home"
and "Contact", each of which specifies a URI::

use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode;
use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu;
Expand Down Expand Up @@ -99,8 +98,8 @@ each of which specifies a URI::

.. note::

When the bundle is registered, it will create the ``/cms/menu`` path
when executing ``doctrine:phpcr:repository:init``. For more information,
When the bundle is registered, it will create the ``menu_basepath`` as part
of the ``doctrine:phpcr:repository:init`` command. For more information,
see :ref:`Repository Initializers <phpcr-odm-repository-initializers>`

Rendering Menus
Expand Down Expand Up @@ -136,9 +135,8 @@ will render an unordered list as follows:

.. tip::

Sometimes, the menu is not located within the ``persistence.phpcr.menu_basepath``.
In this case, you can use an absolute path (starting with a forward slash) to render
the menu:
To render a menu that is not a child of the ``menu_basepath``, you can use
an absolute path (starting with a forward slash):

.. configuration-block::

Expand All @@ -165,9 +163,9 @@ will render an unordered list as follows:
.. caution::

If you want to render the menu from Twig, make sure you have not disabled
Twig in the ``knp_menu`` configuration section.
the Twig integration in the ``knp_menu`` configuration section.

For more information see the `rendering menus`_ section of the KnpMenuBundle documentation.
For more information, see the `rendering menus`_ section of the KnpMenuBundle documentation.

Read On
-------
Expand All @@ -176,7 +174,6 @@ Read On
* :doc:`menu_factory`
* :doc:`menu_provider`
* :doc:`voters`
* :doc:`sonata_admin`
* :doc:`configuration`

.. _`KnpMenu`: https://github.com/knplabs/KnpMenu
Expand Down
9 changes: 5 additions & 4 deletions bundles/menu/menu_documents.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ the KnpMenu component documentation for more information.

.. code-block:: php

use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu;
use Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNodeBase;

// find the menu tree root
$mainMenu = $dm->find('Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu', '/cms/menu/main');
$mainMenu = $dm->find(Menu::class, '/cms/menu/main');

$node = new MenuNodeBase();
$mainMenu->addChild($node);
Expand Down Expand Up @@ -83,7 +84,7 @@ content document from which the URL can be generated::
The content document can be any document which implements the
``RouteReferrersInterface``. See :ref:`bundles-routing-dynamic-generator`.

This content document will then be passed to the ``ContentAwareFactory`` see
This content document will then be handled by the ``ContentExtension``, see
:ref:`URL Generation <bundles_menu_menu_factory_url_generation>` for more details.

Link Type Specification
Expand All @@ -101,8 +102,8 @@ more information.
Translation
~~~~~~~~~~~

The standard menu node supports translation when it is enabled, allowing the
locale to be set via. the ``setLocale`` method::
The standard menu node supports translation if enabled, allowing the
locale to be set via the ``setLocale`` method::

$menuItem = ...;
$menuItem->setLocale('fr');
Expand Down
33 changes: 17 additions & 16 deletions bundles/menu/menu_factory.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@
Menu Factory
============

The menu documents are only used for persisting the menu data, they are not
actually used when rendering a menu. Menu items are the objects that are needed
to render a menu. A menu factory creates such *menu items* from the *menu
nodes* provided by the menu provider.
The menu node documents are only used for persisting the menu data, they are
not actually used when rendering a menu. The KnpMenu rendering engine needs
menu items. KnpMenu uses a factory to create the *menu items* from the *menu
nodes* provided by the menu provider. The menu factory can be customized with
extensions for additional functionality.

.. _bundles_menu_menu_factory_url_generation:

Expand All @@ -28,7 +29,7 @@ from content objects.

The ``content`` menu node option, if specified, must contain something that the
content URL generator can work with. When using the :ref:`dynamic router
<bundles-routing-dynamic-generator>`, this needs to be a class implementing the
<bundles-routing-dynamic-generator>`, this means an instance of
``RouteReferrersInterface``.

.. tip::
Expand All @@ -40,21 +41,21 @@ content URL generator can work with. When using the :ref:`dynamic router
.. versionadded:: 1.2
The ``content_url_generator`` option was introduced in CmfMenuBundle 1.2.

How to handle Items without a URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
How to handle Items without an URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When menu nodes refer to content that has been deleted or there is another
error during route generation, a menu node is skipped by default. You can set
the ``allow_empty_items`` setting of the CmfMenuBundle to ``true`` to render
these nodes as plain text instead.
error during route generation, that menu node (and its children) are ignored.
You can set ``cmf_menu.allow_empty_items`` to ``true`` to render these nodes as
plain text instead.

.. _bundles_menu_menu_factory_link_type:

Specifying the Link Type
~~~~~~~~~~~~~~~~~~~~~~~~

The CMF provides a ``linkType`` option, which enables you to specify which URL
generation technique (URI, route or content) should be used.
The menu nodes has a ``linkType`` option, which enables you to specify which
URL generation technique (URI, route or content) should be used.

The values for this options can be one of the following:

Expand All @@ -81,7 +82,7 @@ Publish Workflow
The CmfMenuBundle provides a ``MenuContentVoter``, which checks if the
referenced content is published using the
:doc:`publish workflow checker <../core/publish_workflow>`. If the content is
not yet published, the menu item not will not be rendered.
not yet published, the menu node (and its children) are ignored.

Customizing Menus using Events
------------------------------
Expand All @@ -100,9 +101,9 @@ skipping nodes using the ``setSkipNode()`` and ``setSkipChildren()`` methods.
If you mark the ``Menu`` document (the root node of each menu) as skipped,
an empty item is still created to avoid errors when rendering a menu.

You can use the ``setItem()`` method to set the menu item to use instead of one
generated using the menu node. The child nodes are still processed like normal
and added to this new item.
You can use the ``setItem()`` method to set the menu item to use instead of the
one generated using the menu node. The child nodes are still processed like
normal and added to this new item.

.. tip::

Expand Down
Loading