Anthony HERVÉ

Ingénieur édudes et développement

SonataAdminBundle tellement simple et tellement pratique

12/12/2016
Image actualité

Bonjour tout le monde,

 

Aujourd'hui, j'ai fait une mise à jour de mon site. Pas grand chose de visible pour les visiteurs mais très pratique pour moi. En effet, j'ai voulu avoir une partie administration séparée de la partie front (ce qui n'était encore pas le cas).

Après m'être dit que j'allais créé moi-même un bundle d'adminsitration pour avoir quelque chose qui me convienne au mieux, je me suis tourné vers les solutions déjà existantes. Je me suis alors souvenu de SonataAdminBundle.

 

Je me souvenais d'un bundle lourd, difficile à mettre en place... Mais c'était il y a quelques années déjà. J'ai donc retenté ma chance, avec une grande réussite et un grand plaisir cette fois.

Je ne saurais que trop vous recommander d'utiliser ce bundle pour réaliser une adminsitration rapidement et efficacement.

Je vais maintenant vous expliquer mon parcours pour installer, utiliser et configurer ce bundle.

 

Documentation

Tout d'baord, je vous conseille de lire et de suivre attentivement la documentation du projet, car celle-ci est très bien faite : https://sonata-project.org/bundles/admin/2-3/doc/index.html.

Installation

Pour cette partie, pas grand chose de compliqué. Il faut juste savoir quelle version du bundle utiliser en fonction de la version de Symfony :

  • Symfony <= 2.8 : 2.3.* du bundle
  • Symfony <= 3.0 : 3.0.*, aucune version stable n'est encore sortie pour Symfony 3
  • Symfony >= 3.1 : ^3.1, aucune version stable n'est encore sortie pour Symfony 3

Ensuite, lancez la commande suivante avec la version que vous avez choisie :

composer require sonata-project/admin-bundle "dev-master"

Il faut télécharger le bundle de Sonata associé avec le type d'ORM que vous utilisez (Doctrine ORM pour ma part). Il en existe un pour DoctrineMongoDB ODM, Propel et Doctrine PHPCR ODM. La version à télécharger ets la même que pour l'admin bundle.

composer require sonata-project/doctrine-orm-admin-bundle "dev-master"

Comme d'habitude, vous devez maintenant ajouter les bundles dans le fichier AppKernel.

// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...

            // The admin requires some twig functions defined in the security
            // bundle, like is_granted. Register this bundle if it wasn't the case
            // already.
            new Symfony\Bundle\SecurityBundle\SecurityBundle(),

            // These are the other bundles the SonataAdminBundle relies on
            new Sonata\CoreBundle\SonataCoreBundle(),
            new Sonata\BlockBundle\SonataBlockBundle(),
            new Knp\Bundle\MenuBundle\KnpMenuBundle(),

            // And finally, the storage and SonataAdminBundle
            new Sonata\DoctrineORMAdminBundle\SonataDoctrineORMAdminBundle(),
            new Sonata\AdminBundle\SonataAdminBundle(),
        );

        // ...
    }

    // ...
}

Un peu de configuration qui va bien.

# app/config/config.yml
sonata_block:
    default_contexts: [cms]
    blocks:
        # enable the SonataAdminBundle block
        sonata.admin.block.admin_list:
            contexts: [admin]
        # ...

Un peu de routing...

# app/config/routing.yml
admin_area:
    resource: "@SonataAdminBundle/Resources/config/routing/sonata_admin.xml"
    prefix: /admin

Activation du service "translator"

framework:
    #esi:             ~
    translator:      { fallbacks: ["%locale%"] }
    secret:          "%secret%"

Pour finir, lancez ces deux commandes (soit avec app/console soit bin/console en fonction de la version de Symfony).

php app/console cache:clear
php app/console assets:install

Si tout se passe bien, vous avez accès à la console d'administration en allant sur http://votre-url-locale/admin.

Pour l'instant, cette console est un peu vide, mais cela va s'arranger avec la suite de cet article.

Création d'une administration pour une entité

Cela correspond au deuxième chapitre de la documentation : https://sonata-project.org/bundles/admin/2-3/doc/getting_started/creating_an_admin.html.

Je suppose que vous avez déjà une entité existante (Category) avec un attribut name.

Création d'une classe d'administration

La première action à faire est de créer une classe d'administration pour votre entité Category. Cette classe devra étendre la classe Admin de Sonata.

// src/AppBundle/Admin/CategoryAdmin.php
namespace AppBundle\Admin;

use Sonata\AdminBundle\Admin\Admin;
use Sonata\AdminBundle\Datagrid\ListMapper;
use Sonata\AdminBundle\Datagrid\DatagridMapper;
use Sonata\AdminBundle\Form\FormMapper;

class CategoryAdmin extends Admin
{
    protected function configureFormFields(FormMapper $formMapper)
    {
        $formMapper->add('name', 'text');
    }

    protected function configureDatagridFilters(DatagridMapper $datagridMapper)
    {
        $datagridMapper->add('name');
    }

    protected function configureListFields(ListMapper $listMapper)
    {
        $listMapper->addIdentifier('name');
    }
}
  • configureFormFields : il s'agit de votre formulaire d'édition et d'ajout. Vous pouvez reprendre exactement les mêmes formulaires que vous utilisez d'habitude, la syntaxe est la même, donc très facile à faire.
  • configureDatagridFilters : les champs ajoutés dans cette focntion vous pouvoir être utilisés comme filtre dans la vue liste de l'administration.
  • configureListFields : il s'agit des champs affichés dans la liste des catégories (le addIdentifier indique que le champ va être un lien pointant vers le formulaire d'édition).

Création d'un service

Maintenant, il faut enregistrer cette classe comme un service.

# app/config/services.yml

# ...
services:
    admin.category:
        class: AppBundle\Admin\CategoryAdmin
        arguments: [~, AppBundle\Entity\Category, ~]
        tags:
            - { name: sonata.admin, manager_type: orm, label: Category }

Chargement des routes

Sonata va créer des routes à la volée. Pour que cela se fasse sans souci, il faut ajouter un petit bout de code dans le fichier de routing.

# app/config/routing.yml

# ...
_sonata_admin:
    resource: .
    type: sonata_admin
    prefix: /admin

Voilà ce que vous obtenez.

NB :  en fonction de la version, il se peut que vous ayez une barre de recherche au dessus du texte "sonata project", comme ceci

Et maintenant ?

A partir de cet instant, vous avez déjà une adminsitration fonctionnelle. Vous avouerez qu'il n'a pas fallu trop de temps et que le résultat est plutôt convaincant, non ?

Maintenant, je vais vous apporter quelques astuces supplémentaires qui m'ont permis d'avoir un rendu un peu meilleur sur ma console d'admin.

Faire fonctionner la recherche

Si vous essayez de rechercher quelque chose, vous allez certainement rencontrer une erreur du type :

Pour résoudre ce problème, il faut en fait activer le block "search_result" de Sonata dans le fichier de config.

# app/config/config.yml

sonata_block:
    default_contexts: [cms]
    blocks:
        # enable the SonataAdminBundle block
        sonata.admin.block.admin_list:
            contexts: [admin]
        sonata.admin.block.search_result:
            contexts: [admin]

Et voilà le résultat.

Création de groupes

Comme vous pouvez le voir sur la capture ci-dessous (qui est ma console d'admin actuelle), les entités sont regroupées par groupe : Blog, Carousel, Projet...

Pa rdéfaut, les entités vont dans le groupe "default". Mais il est très simple de les ranger. Lors que vous définissez votre classe d'admin comme service, il y a un tag group. Grâce à ce tag, vous pouvez choisir le groupe auquel va appartenir votre enité.

Obtenir le menu à gauche

Actuellement, vous n'avez rien entre la barre de recherche et le texte "sonata project". Mais en fait, il devrait y avoir un menu (voir capture d'acran ci-dessus) avec les groupes. Pour visualiser ce menu, il faut en fait que l'utilisateur connecté ait le role ROLE_SONATA_ADMIN. Une fois ce rôle ajouté à votre utilisateur, reconnectez-vous et le menu est bien là.

Traductions

Après vous être assuré que les traductions étaient bien activées sur votre projet (framework.translator dans le fichier config.yml), rien n'est plus simple pour compléter les traductions du bundle.

Il suffit de créer deux fichiers dans le dossier Resources/translations de votre bundle :

  • messages.fr.yml
  • SonataAdminBundle.fr.yml

Certains textes sont en fait affichés avec le groupe de traduction SonataAdminBundle, d'où le fait de créer un fichier SonataAdminBundle.fr.yml. Il s'agit notamment des noms des groupes et des termes tels "Dashboard". Les autres libellés peuvent être mis dans le fichier messages.

Une fois vos fichiers complétés, pensez bien à vider le cache pour voir apparaître vos traductions.

Surcharge de templates

Sonata nous a bien aidé à ce niveau et il est possible de surcharger pratiquement n'importe quelle partie de la console (voir https://sonata-project.org/bundles/admin/master/doc/reference/templates.html pour plus de détails).

Pour mes besoins, j'ai dû surchargé deux templates :

# app/config/config.yml

sonata_admin:
    templates:
        layout: AnthonyHerveAdminBundle::layout.html.twig
        user_block: AnthonyHerveAdminBundle:Block:user_block.html.twig
  • Le layout général pour ajouter le script de TinyMCE pour mon éditeur de texte
  • Le block user qui est la liste déroulante affichée quand on clique sur l'icône tout en haut à droite. J'ai simplement ajouté un lien de déconnexion.

Une fois les surchargés définies, il faut ajouter les fichiers templates et ajouter votre code.

{# Resources/views/layout.html.twig #}

{% extends 'SonataAdminBundle::standard_layout.html.twig' %}

{% block sonata_page_content %}
    {{ parent() }}
    {{ tinymce_init() }}
{% endblock %}
{# Resources/views/Block/user_block.html.twig #}

<li>
    <a href="{{ path('fos_user_security_logout') }}">
        <i class="fa fa-power-off" ></i>{{ 'arv_admin.logout'|trans }}
    </a>
</li>



C'est tout (pour l'instant) pour les astuces que je peux vous donner. En à peine deux jours de travail (étalés dans mon temps libre), j'ai pu créer une console d'administration pour ma dizaine d'entités, faire quelques customisations. Et honnêtement, je suis très content d'avoir utilisé ce bundle qui m'a simplifié mon développement.

Je pense qu'il reste beaucoup d'éléments à voir sur ce bundle. Si jamais j'en utilise, je vous le ferai savoir dans un prochain article.

 

A bientôt.

Commentaires (1)

PELLETIER-GARNIER - 30/04/2016 à 00:28 - Répondre
SF3.0.4 l'affichage du champ de recherche dépend du rôle d'authentification de votre utilisateur (ROLE_SONATA_ADMIN)