From 88503381970841dfa4d2f0296215ed9c28f4923e Mon Sep 17 00:00:00 2001 From: WouterJ Date: Thu, 23 Feb 2017 11:34:24 +0100 Subject: [PATCH] Start with TreeBrowser 2.0 docs --- bundles/tree_browser/configuration.rst | 83 +++++------ bundles/tree_browser/forms.rst | 5 + bundles/tree_browser/index.rst | 3 + bundles/tree_browser/introduction.rst | 197 ++++--------------------- bundles/tree_browser/tree.rst | 65 ++++++++ 5 files changed, 137 insertions(+), 216 deletions(-) create mode 100644 bundles/tree_browser/forms.rst create mode 100644 bundles/tree_browser/tree.rst diff --git a/bundles/tree_browser/configuration.rst b/bundles/tree_browser/configuration.rst index 8bf47022..e3264590 100644 --- a/bundles/tree_browser/configuration.rst +++ b/bundles/tree_browser/configuration.rst @@ -5,73 +5,64 @@ The TreeBrowserBundle can be configured under the ``cmf_tree_browser`` key in your application configuration. When using XML, you can use the ``http://cmf.symfony.com/schema/dic/treebrowser`` namespace. -.. note:: - - To use this bundle with the tree provided by SonataDoctrinePHPCRAdminBundle_, - you do not need to provide any configuration here. - Configuration ------------- -.. _config-tree_browser-persistence: +.. _config-tree_browser-icons: + +``icons`` +~~~~~~~~~ -``persistence`` -~~~~~~~~~~~~~~~ +**prototype**: ``scalar`` -``phpcr`` -......... +A mapping of interfaces/classes to icons. These icons will be shown in the tree +whenever an instance of this interface/class is shown. -This defines the persistence driver. The default configuration of persistence -is the following configuration: +The icon can be either a CSS class (e.g. to use an icon font) or a URI to an +image. The value is considered to be an URI when it contains a ``.`` or ``/`` +character. .. configuration-block:: .. code-block:: yaml cmf_tree_browser: - persistence: - phpcr: - enabled: false - session_name: default + icons: + # URI to an image + Symfony\Cmf\Component\Routing\RouteObjectInterface: '/img/route-icon.png' + + # CSS classes + Symfony\Cmf\Bundle\SeoBundle\Model\SeoMetadata: 'fa fa-search' .. code-block:: xml - - + + - - - - - + + + + /img/route-icon.png + + fa fa-search + .. code-block:: php - $container->loadFromExtension('cmf_tree_browser', array( - 'persistence' => array( - 'phpcr' => array( - 'enabled' => false, - 'session_name' => 'default', - ), - ), - )); - - -``enabled`` -""""""""""" - -.. include:: ../_partials/persistence_phpcr_enabled.rst.inc - -``session_name`` -"""""""""""""""" - -**type**: ``string`` **default**: ``default`` + $container->loadFromExtension('cmf_tree_browser', [ + 'icons' => [ + // URI to an image + 'Symfony\Cmf\Component\Routing\RouteObjectInterface' => '/img/route-icon.png', -The name of the PHPCR connection to use. + // CSS classes + 'Symfony\Cmf\Bundle\SeoBundle\Model\SeoMetadata' => 'fa fa-search', + ], + ]); .. _SonataDoctrinePHPCRAdminBundle: http://sonata-project.org/bundles/doctrine-phpcr-admin/master/doc/index.html diff --git a/bundles/tree_browser/forms.rst b/bundles/tree_browser/forms.rst new file mode 100644 index 00000000..42fe8b98 --- /dev/null +++ b/bundles/tree_browser/forms.rst @@ -0,0 +1,5 @@ +.. index:: + single: Forms; TreeBrowserBundle + +How to Use the Tree as a Form Type +================================== diff --git a/bundles/tree_browser/index.rst b/bundles/tree_browser/index.rst index 41dd48a9..d1e3bdb1 100644 --- a/bundles/tree_browser/index.rst +++ b/bundles/tree_browser/index.rst @@ -5,4 +5,7 @@ TreeBrowserBundle :maxdepth: 2 introduction + forms + tree configuration + context_menu diff --git a/bundles/tree_browser/introduction.rst b/bundles/tree_browser/introduction.rst index 5c3c894d..68e75ec3 100644 --- a/bundles/tree_browser/introduction.rst +++ b/bundles/tree_browser/introduction.rst @@ -5,14 +5,9 @@ TreeBrowserBundle ================= - The TreeBrowserBundle provides a tree navigation on top of a PHPCR - repository. The front-end implementation is based on the jQuery plugin - `jsTree`_. - -This bundle consists of two parts: - -* Generic Tree Browser with a ``TreeInterface`` -* PHPCR tree implementation and GUI for a PHPCR browser + The TreeBrowserBundle provides a tree view to visualize the backend and + make it easy to manage the backend. It uses the ResourceRestBundle to get + the nodes. Installation ------------ @@ -20,38 +15,39 @@ Installation You can install this bundle `with composer`_ using the ``symfony-cmf/tree-browser-bundle`` package on `Packagist`_. -Both the CmfTreeBrowserBundle and FOSJsRoutingBundle_ must be registered in the -``AppKernel``:: +The CmfTreeBrowserBundle, ResourceRestBundle and ResourceBundle must be +registered in the ``AppKernel``:: // app/appKernel.php + // ... public function registerBundles() { $bundles = array( // ... - new FOS\JsRoutingBundle\FOSJsRoutingBundle(), + new Symfony\Cmf\Bundle\ResourceBundle\CmfResourceBundle(), + new Symfony\Cmf\Bundle\ResourceRestBundle\CmfResourceRestBundle(), new Symfony\Cmf\Bundle\TreeBrowserBundle\CmfTreeBrowserBundle(), ); + // ... return $bundles; } Routing -------- +~~~~~~~ -The bundle will create routes for each tree implementation found. In order to -make those routes available you need to include the following in your routing -configuration: +The ResourceRestBundle provides a REST interface using Symfony routes. In order +to make this work, you have to import the routes in your routing configuration: .. configuration-block:: .. code-block:: yaml # app/config/routing.yml - cmf_tree: - resource: . - type: 'cmf_tree' + cmf_resource_rest: + resource: "@CmfResourceRest/Resources/config/routing.xml" .. code-block:: xml @@ -62,7 +58,7 @@ configuration: xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + @@ -72,173 +68,34 @@ configuration: use Symfony\Component\Routing\RouteCollection; $collection = new RouteCollection(); - $collection->addCollection($loader->import('.', 'cmf_tree')); + $collection->addCollection($loader->import( + '@CmfResourceRestBundle/Resources/config/routing.xml' + )); return $collection; Usage ----- -The TreeBrowserBundle provides the ``select_tree.js`` and ``admin_tree.js`` -files, which are wrappers to build a jQuery tree. Use them with -``SelectTree.initTree`` resp. ``AdminTree.initTree``. - -* ``SelectTree`` in ``select_tree.js`` is a tree to select a target tree node, - e.g. in a form. The id of the target is put into a text field; -* ``AdminTree`` in ``admin_tree.js`` is a tree to create, move and edit nodes. - -Both have the following options when creating: - -* **config.selector**: jQuery selector where to hook in the js tree; -* **config.rootNode**: id to the root node of the tree, defaults to ``/``; -* **config.selected**: id of the selected node; -* **config.ajax.children_url**: URL to the controller that provides the - children of a node; -* **config.routing_defaults**: array for route parameters (e.g. ``_locale``); -* **config.path.expanded**: tree path where the tree should be expanded to at - the moment; -* **config.path.preloaded**: tree path what node should be preloaded for - faster user experience. - -select_tree.js only -~~~~~~~~~~~~~~~~~~~ - -* **config.output**: where to write the id of the selected node. - -admin_tree.js only -~~~~~~~~~~~~~~~~~~ - -* **config.labels**: array containing the translations for the labels of the - context menu (keys ``createItem`` and ``deleteItem``); -* **config.ajax.move_url**: Url to the controller for moving a child (i.e. - giving it a new parent node); -* **config.ajax.reorder_url**: Url to the controller for reordering siblings; -* **config.types**: array indexed with the node types containing information - about valid_children, icons and available routes, used for the creation of - context menus and checking during move operations. - -Examples --------- - -Look at the templates in the SonataDoctrinePHPCRAdminBundle_ for examples how -you could build a tree: - -* `admin_tree.js`_ -* `select_tree.js`_ (look for ``doctrine_phpcr_type_tree_model_widget``) - -In the same bundle, the `PhpcrOdmTree`_ implements the tree interface and -provides an example how to implement the methods. - -Customizing the Tree Behavior ------------------------------ - -The TreeBrowserBundle is based on `jsTree`_. jsTree works with events, -dispatched every time the user does an action. A simple way to customize the -tree behavior is to bind your actions to those events. - -If you have a look at ``admin_tree.js`` and ``select_tree.js``, you will -notice that actions are already bound to some of the tree events. If the -default behavior is *not* what you need, jQuery provide the ``unbind`` method -to remove the default events. Here is a simple way to remove the context menu -from the admin tree: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% render 'sonata.admin.doctrine_phpcr.tree_controller:treeAction' with { - 'root': sitePath ~ "/menu", - 'selected': menuNodeId - } %} - - - .. code-block:: html+php - - render('sonata.admin.doctrine_phpcr.tree_controller:treeAction', array( - 'root' => $sitePath . '/menu', - 'selected' => $menuNodeId, - ))?> - - -.. note:: - - This example assumes you have the SonataDoctrinePHPCRAdminBundle_ - available, to have a tree implementation. - -By default, the item selection opens the edit route of the admin class of the -element. This action is bind to the ``select_node.jstree``. If you want to -remove it, you just need to call the unbind function on this event: - -.. code-block:: javascript - - $(document).ready(function() { - $('#tree').unbind('select_node.jstree'); - }); - -Then you can bind it on another action. - -For example, if your want to open a custom action: - -.. configuration-block:: - - .. code-block:: jinja - - $('#tree').bind("select_node.jstree", function (event, data) { - if ((data.rslt.obj.attr("rel") == 'Symfony_Cmf_Bundle_MenuBundle_Doctrine_Phpcr_MenuNode' - && data.rslt.obj.attr("id") != '{{ menuNodeId }}' - ) { - var routing_defaults = {'locale': '{{ locale }}', '_locale': '{{ _locale }}'}; - routing_defaults["id"] = data.rslt.obj.attr("url_safe_id"); - window.location = Routing.generate('presta_cms_page_edit', routing_defaults); - } - }); - - .. code-block:: php - - $('#tree').bind("select_node.jstree", function (event, data) { - if ((data.rslt.obj.attr("rel") == 'Symfony_Cmf_Bundle_MenuBundle_Doctrine_Phpcr_MenuNode' - && data.rslt.obj.attr("id") != '' - ) { - var routing_defaults = {'locale': '', '_locale': ''}; - routing_defaults["id"] = data.rslt.obj.attr("url_safe_id"); - window.location = Routing.generate('presta_cms_page_edit', routing_defaults); - } - }); +The TreeBrowserBundle provides a two jQuery plugins, ready for you to use: -.. note:: +* :doc:`$(elem).cmfTree() ` +* :doc:`$(elem).cmfContextMenu() ` - This bundle automatically exposes routes with the FOSJsRoutingBundle_ - to allow the tree to work. +The bundle also ships a ``TreeSelectType`` form type. Using this form type, +users can select nodes from the tree instead of typing the path in a text +field. Read more about this form type in :doc:`it's own section `. Read On ------- +* :doc:`forms` +* :doc:`tree` * :doc:`configuration` +* :doc:`context_menu` .. _`Packagist`: https://packagist.org/packages/symfony-cmf/tree-browser-bundle .. _`with composer`: http://getcomposer.org -.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle .. _`admin_tree.js`: https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/blob/master/Resources/views/Tree/tree.html.twig .. _`select_tree.js`: https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/blob/master/Resources/views/Form/form_admin_fields.html.twig .. _`PhpcrOdmTree`: https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/blob/master/Tree/PhpcrOdmTree.php diff --git a/bundles/tree_browser/tree.rst b/bundles/tree_browser/tree.rst new file mode 100644 index 00000000..382a78b2 --- /dev/null +++ b/bundles/tree_browser/tree.rst @@ -0,0 +1,65 @@ +.. index:: + single: Tree; TreeBrowserBundle + +Displaying Nodes inside the Tree +================================ + +The TreeBrowserBundle provides a ``cmfTree`` jQuery plugin. This plugin is an +abstraction on top of Fancytree_. It also allows to integrate other JavaScript +tree implementations. + +The plugin is based on the API provided by the CmfResourceRestBundle. + +Usage +----- + +The plugin requires one option: ``request.load``. This option should contain a +callable that returns `an AJAX settings object`_ as supported by Fancytree: + +.. code-block:: twig+html + + {# the Tree will be displayed here #} +
+ + {# include required CSS and JS files #} + {{ include('@CmfTreeBrowser/Base/tree.html.twig') }} + + + +Using this code, a tree will be shown in the ``
`` tag. The +``/api/default/`` URI will be used to request for nodes. Note that this +happends lazily, so after opening a node with no children loaded yet, the URL +will again be requested for the children (e.g. ``/api/default/cms/content`` +when opening the ``/cms/content`` node). + +Options +------- + +* adapter +* request + * load + * move +* actions +* path_output + +(fancytree) +* root_node +* use_cache +* dnd + * enabled + * isNodeDraggable + * nodeAcceptsDraggable + +.. _Fancytree: https://github.com/mar10/fancytree +.. _an AJAX settings object: https://github.com/mar10/fancytree/wiki/TutorialLoadData#load-the-data-via-ajax