Skip to content
This repository has been archived by the owner on Jul 22, 2022. It is now read-only.

Commit

Permalink
[Docs] big cleanup (#545)
Browse files Browse the repository at this point in the history
  • Loading branch information
@OskarStark @dbu
OskarStark authored and dbu committed Jan 22, 2019
1 parent b0b731d commit d513516
Show file tree
Hide file tree
Showing 5 changed files with 96 additions and 132 deletions.
11 changes: 7 additions & 4 deletions docs/reference/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,24 @@ On this bundle, you can configure templates and the document tree.

.. code-block:: yaml
# config/packages/sonata_doctrine_phpcr_admin.yaml
sonata_doctrine_phpcr_admin:
templates:
form:
# Default:
- "@SonataDoctrinePHPCRAdmin/Form/form_admin_fields.html.twig"
- '@SonataDoctrinePHPCRAdmin/Form/form_admin_fields.html.twig'
filter:
# Default:
- "@SonataDoctrinePHPCRAdmin/Form/filter_admin_fields.html.twig"
- '@SonataDoctrinePHPCRAdmin/Form/filter_admin_fields.html.twig'
types:
list:
# Prototype
name: []
show:
# Prototype
name: []
pager_results: "@SonataDoctrinePHPCRAdmin/Pager/simple_pager_results.html.twig"
pager_results: '@SonataDoctrinePHPCRAdmin/Pager/simple_pager_results.html.twig'
document_tree:
# See :doc:`document_tree`.
Expand All @@ -38,7 +40,8 @@ On this bundle, you can configure templates and the document tree.
document_tree_options:
# Depth to which to fetch tree children when rendering the initial tree
depth: 1
# Exact check if document has children. For large trees, set to false for better performance, but user might needs to click on expand to see there are no children.
# Exact check if document has children. For large trees, set to false for better
# performance, but user might needs to click on expand to see there are no children.
precise_children: true
# Whether moving a node in the tree asks for confirmation.
confirm_move: true
Expand Down
77 changes: 44 additions & 33 deletions docs/reference/document_tree.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,38 @@ Document Tree
This admin integrates with the `CmfTreeBrowserBundle`_ to provide a tree view
of the documents.

Download the Bundles
--------------------

.. code-block:: bash
composer require symfony-cmf/tree-browser-bundle
.. code-block:: bash
composer require friendsofsymfony/jsrouting-bundle
Enable the Bundles
------------------

You need to load two additional bundles to use the tree::
Then, enable the bundle by adding it to the list of registered bundles
in ``bundles.php`` file of your project::

// app/AppKernel.php
class AppKernel extends Kernel
{
public function registerBundles()
{
$bundles = [
// ...
new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
new Symfony\Cmf\Bundle\TreeBrowserBundle\CmfTreeBrowserBundle(),
];
// config/bundles.php

// ...
}
}
return [
// ...
FOS\JsRoutingBundle\FOSJsRoutingBundle::class => ['all' => true],
Symfony\Cmf\Bundle\TreeBrowserBundle\CmfTreeBrowserBundle::class => ['all' => true],
];

You also need to load the routing of those bundles:

.. configuration-block::

.. code-block:: yaml
# app/config/routing.yml
# config/routes.yaml
cmf_tree:
resource: .
Expand All @@ -41,7 +46,8 @@ You also need to load the routing of those bundles:
.. code-block:: xml
<!-- app/config/routing.xml -->
<!-- config/routes.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Expand All @@ -61,16 +67,17 @@ You also need to load the routing of those bundles:
.. code-block:: php
// app/config/routing.php
// config/routes.php
use Symfony\Component\Routing\RouteCollection;
$collection = new RouteCollection();
$collection->addCollection($loader->import('.', 'cmf_tree'));
$collection->addCollection($loader->import(
"@FOSJsRoutingBundle/Resources/config/routing/routing.xml"
));
$collection
->addCollection($loader->import('.', 'cmf_tree'))
->addCollection($loader->import(
"@FOSJsRoutingBundle/Resources/config/routing/routing.xml"
));
return $collection;
Expand All @@ -86,16 +93,19 @@ content:

.. code-block:: yaml
#app/config/config.yml
# ...
# config/packages/sonata_block.yaml
sonata_block:
blocks:
# ...
sonata_admin_doctrine_phpcr.tree_block:
settings:
id: '/cms'
contexts: [admin]
.. code-block:: yaml
# config/packages/sonata_admin.yaml
sonata_admin:
dashboard:
blocks:
Expand Down Expand Up @@ -164,7 +174,8 @@ This configuration is global for all your document trees.

.. code-block:: yaml
# app/config/config.yml
# config/packages/sonata_doctrine_phpcr_admin.yaml
sonata_doctrine_phpcr_admin:
document_tree:
routing_defaults: [locale]
Expand All @@ -177,7 +188,7 @@ This configuration is global for all your document trees.
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">
<config xmlns="http://sonata-project.org/schema/dic/doctrine_phpcr_admin" />
<config xmlns="http://sonata-project.org/schema/dic/doctrine_phpcr_admin"/>
<document-tree-default>locale</document-tree-default>
Expand Down Expand Up @@ -231,12 +242,12 @@ like this:
.. code-block:: php
echo $view['actions']->render(new ControllerReference(
'sonata.admin.doctrine_phpcr.tree_controller::treeAction',
[
'root' => $basePath . '/menu',
'selected' => $menuNodeId,
'_locale' => $app->getRequest()->getLocale(),
],
'sonata.admin.doctrine_phpcr.tree_controller::treeAction',
[
'root' => $basePath . '/menu',
'selected' => $menuNodeId,
'_locale' => $app->getRequest()->getLocale(),
],
));
.. note::
Expand Down
74 changes: 24 additions & 50 deletions docs/reference/filter_field_definition.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,20 +38,16 @@ Example

.. code-block:: php
<?php
namespace Sonata\NewsBundle\Admin;
use Sonata\AdminBundle\Admin\Admin;
use Sonata\AdminBundle\Form\FormMapper;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\DatagridMapper;
use Sonata\AdminBundle\Datagrid\ListMapper;
use Sonata\AdminBundle\Show\ShowMapper;
class PostAdmin extends Admin
final class PostAdmin extends AbstractAdmin
{
protected function configureDatagridFilters(DatagridMapper $datagrid)
protected function configureDatagridFilters(DatagridMapper $datagridMapper)
{
$datagrid
$datagridMapper
->add('title')
->add('enabled')
->add('tags', null, [], null, ['expanded' => true, 'multiple' => true])
Expand All @@ -66,25 +62,19 @@ Filtering by sub entity properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you need to filter your base entities by the value of a sub entity property,
you can simply use the dot-separated notation (note that this only makes sense
when the prefix path is made of entities, not collections):

.. code-block:: php
you can use the dot-separated notation (note that this only makes sense
when the prefix path is made of entities, not collections)::

<?php
namespace Acme\AcmeBundle\Admin;
namespace App\Admin;

use Sonata\AdminBundle\Admin\Admin;
use Sonata\AdminBundle\Form\FormMapper;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\DatagridMapper;
use Sonata\AdminBundle\Datagrid\ListMapper;
use Sonata\AdminBundle\Show\ShowMapper;

class UserAdmin extends Admin
final class UserAdmin extends AbstractAdmin
{
protected function configureDatagridFilters(DatagridMapper $datagrid)
protected function configureDatagridFilters(DatagridMapper $datagridMapper)
{
$datagrid
$datagridMapper
->add('id')
->add('firstName')
->add('lastName')
Expand All @@ -95,49 +85,36 @@ when the prefix path is made of entities, not collections):
}
}

Label
^^^^^

You can customize the label which appears on the main widget by using a ``label`` option.
You can customize the label which appears on the main widget by using a ``label`` option::

.. code-block:: php
<?php
protected function configureDatagridFilters(DatagridMapper $datagrid)
protected function configureDatagridFilters(DatagridMapper $datagridMapper)
{
$datagrid
// ..
->add('tags', null, ['label' => 'les tags'], null, ['expanded' => true, 'multiple' => true])
// ..
;
$datagridMapper
->add('tags', null, ['label' => 'les tags'], null, [
'expanded' => true, 'multiple' => true
]);
}

Callback
^^^^^^^^

To create a custom callback filter, two methods need to be implemented; one to
define the field type and one to define how to use the field's value. The
latter shall return wether the filter actually is applied to the queryBuilder
or not. In this example, ``getWithOpenCommentField`` and ``getWithOpenCommentFilter``
implement this functionality.
implement this functionality::

.. code-block:: php
<?php
namespace Sonata\NewsBundle\Admin;

use Sonata\AdminBundle\Admin\Admin;
use Sonata\AdminBundle\Form\FormMapper;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\DatagridMapper;
use Sonata\AdminBundle\Datagrid\ListMapper;
use Sonata\AdminBundle\Show\ShowMapper;

use Application\Sonata\NewsBundle\Document\Comment;

class PostAdmin extends Admin
final class PostAdmin extends AbstractAdmin
{
protected function configureDatagridFilters(DatagridMapper $datagridMapper)
{
Expand Down Expand Up @@ -185,19 +162,16 @@ Filtering Fields and Case Sensitivity

The default behaviour when filtering is to compare values in a case sensitive manner.
For example "Test" is not the same as "test". Depending on your use case, you might want case insensitive filtering.
To make the filter case insensitive, use the ``compare_case_insensitive`` option for the string filter:

.. code-block:: php
To make the filter case insensitive, use the ``compare_case_insensitive`` option for the string filter::

<?php
namespace My\AppBundle\Admin;
namespace App\Admin;

use Sonata\AdminBundle\Admin\Admin;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\DatagridMapper;

use Application\Sonata\NewsBundle\Document\Comment;

class PostAdmin extends Admin
final class PostAdmin extends AbstractAdmin
{
protected function configureDatagridFilters(DatagridMapper $datagridMapper)
{
Expand Down
20 changes: 7 additions & 13 deletions docs/reference/form_field_definition.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,22 @@ Short Object Placeholder
When using Many-to-One or One-to-One relations with Sonata Type fields, a short
object description is used to represent the target object. If no object is selected,
a 'No selection' placeholder will be used. If you want to customize this placeholder,
you can use the corresponding option in the form field definition:
you can use the corresponding option in the form field definition::

.. code-block:: php
<?php
namespace Sonata\NewsBundle\Admin;

use Sonata\AdminBundle\Admin\Admin;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Form\FormMapper;

class PostAdmin extends Admin
final class PostAdmin extends AbstractAdmin
{
protected function configureFormFields(FormMapper $formMapper)
{
$formMapper
->with('General')
->add('enabled', null, ['required' => false])
->add('author', 'sonata_type_model_list', [], [
'placeholder' => 'No author selected',
])
;
->add('enabled', null, ['required' => false])
->add('author', 'sonata_type_model_list', [], [
'placeholder' => 'No author selected',
]);
}
}

Expand Down
Loading

0 comments on commit d513516

Please sign in to comment.