Adding new design customization options

[javiereguiluz]

Let's start with a quick recap of the short-term roadmap of this bundle:

• Add custom actions support (done in Added support for custom actions and full action customization #202)
• Add lots of design customization options (this PR)
• Add/improve support for Doctrine associations (see Add support for all kinds of Doctrine associations #124 meta-issue)

---

Regarding the customization of the backend visual design, there are two types of customizations:

• Basic options to change the appearance of the backend.
• Extreme customization (change templates and layouts, use themes)

In this PR we're discussing about the first type of customizations. The other type will be discussed later.

These are the options that I plan to introduce:

easy_admin:
    # new global option called 'design'
    design:
        # dummy option because there will be only one theme called 'default'
        # but this allows us to be prepared for the future
        theme: 'default'

        # this is the exact same 'assets' options which currently is a global
        # option. We'll transparently deprecate it in favor of this one
        assets:
            css: [...]
            js:  [...]

        # 'dark' is the usual style for backend, but we'll also provide a light' variant
        color_scheme: 'dark' (default) or 'light'

        # this is the only color you can change for the quick visual customization
        brand_color: '#D47843' (default)

        # this option will work exactly as 'form_themes' from Symfony, allowing
        # to pass an array of custom form themes
        form_theme: 'horizontal' (default), 'vertical' or a custom Symfony form theme

        # this option overrides the default menu built with your entity configuration
        menu:
            # default menu item: just provide the entity name
            - 'Customer'

            # expanded configuration: 'label' overrides the entity label
            - { entity: 'Customer', label: 'Customers', icon: 'users' }

            # menu item linked to a specific entity view
            - { entity: 'Customer', view: 'new', label: 'Add customer', icon: 'new' }

            # special menu item not tied to an entity
            - { route: 'admin_user_stats', label: 'User stats' }

            # special empty item used to display menu section titles
            - { label: 'Users', icon: 'user' }

            # menus will support two-level nesting
            - { entity: 'Customer', icon: 'user', children: [
                { ... same configuration format as parent items ... },
                { ... same configuration format as parent items ... },
                { ... same configuration format as parent items ... },
                ...
            ] }

Opinions? Thoughts? Thanks.

[Pierstoval]

I'm totally in favor of the menu part, especially because it allows nesting the menu in a theoretical infinite number of levels (as long as you use the children attribute) and the form_theme is also great 👍

I don't like the main theme and color_scheme , because it would "force" (or at least "propose") the contributors to create custom themes, so multiple themes would be proposed and only one would be used at a time in the back-end, and I don't agree with it because a great part of the code would be unused in all backends. What would be better for this is to add a new component to EasyAdmin, something like a "theme generator", and the output of this generator would be a simple template override to save into the app/Resources/EasyAdminBundle/ directory. It would be much simpler.
But in the end I don't know if this feature would be used.

That said, a big twig refactoring would have to be made in order to still allow users to override the default layout without breaking the design configuration

[Pierstoval]

Ah, also, would the first menu item be the homepage of the back-end ?

[guillermogfer]

Great to see you are working in the customization of the visual design of the backend!
I am starting a project with a strong and relatively complex backend and testing some Symfony2 admin generators. EasyAdminBundle is the cleanest and quickiest bundle by far, but lacks some customizations we need (we are currently migrating projects from Symfon 1.4 built with the great admin generator).
Now we've received great news with your release of custom actions and full action customization, it's simply awesome!
I'm looking forward to testing this visual customization you are working on and throw away Sonata hehe.
Great job!

[javiereguiluz]

@guillermogfer thanks for your comments! However, if your backend is very complex, you probably shouldn't use this bundle because it's a very recent project and we lack some important features (although we are working tirelessly to add them soon).

Instead of "throwing aray" Sonata, you should probably use it to build your complex backend (in fact, in our documentation we recommend to use Sonata for very complex backends).

[guillermogfer]

Sorry, I haven't express myself very well. We are very focused on building backends, some of them are complex but not all, we are working on a wide range of complexity. But what I wanted to say, it's that your recent custom actions incorporation solved almost the whole thing in an incoming project we have in hands, so we'll definitely use EasyAdmin to build it.
There are some others that I think with a bit of customization in the visual part we could make with this too. And of course there are more complex backends that have to use Sonata because is tremendously powerful but also a nightmare of configurations.
Don't want to divert this discussion, just want to provide feedback from people using this cool stuff in real backend projects.
You are doing really great! (and saving our lifes hehe)

[Pierstoval]

I'd like to propose the use of a new design layout option.

I'm facing a problem: if I want to override the layout, there is not many solutions... In fact, I cannot "really" override the layout without copying the entire layout itself in my own file.

What I'm asking is a layout configuration option in order to easily override the layout this way:

• Create my own layout in whatever directory I want.

• Set up the option:

  easy_admin:
      design:
          layout: "@App/admin_layout.html.twig" # or anything else

• Inside my layout, extend the original layout:

  {% extends '@EasyAdmin/layout.html.twig' %}

• Override whatever blocks I want, so I don't have to force the recreation of the whole layout in my app, which may entirely break the back-end whenever I make an EasyAdmin update.

In technical terms, it's nothing more than what I've set up in Orbitale/CmsBundle:

• An option in the Configuration class (not the Configurator), which default value is @EasyAdmin/layout.html.twig
• A listener to set it up automatically in each request attributes
• An automatic load in each view with {% extends app.request.attributes.get('_easyadmin_layout') %} in each EasyAdmin view.

[javiereguiluz]

@Pierstoval I like the idea, but I want to implement it in a more flexible and broad way. Instead of customizing the layout template, I want to allow to customize every template. I'm going to think about this in the coming days and I'll come back with a proposal.

[Pierstoval]

For this, we can use the exact same system of what I proposed but with every template, where would be the problem for this ?
We can replace the listener I proposed with a simple twig extension, like {% extends easyadmin_layout('edit') %} , as the layouts will be set in the configuration.
We can also configure a directory where to find the views, but it might be too dangerous if the template does not exist.

The most important goal is to be able to extend EasyAdmin's view, in order to keep the natural behavior when extending the view without writing anything but "extends ...".
Once this is done, we'll be able to create a bunch of other twig blocks to allow the user to extend them the most naturally possible, so it does not break the entire back-end.

What do you think?

[Flushdrew]

Where is this configuration folder please? I can't find it

[Pierstoval]

Which folder are you talking about exactly? This issue talks about design, are you talking about the app/Resources/easy_admin directory used to override EasyAdmin's template?

[Flushdrew]

Yes. I haven't any default options like the first post

[Pierstoval]

This issue is a proposal, not a final feature. The menu part is not implemented, and the design option may look a bit different.

[rubengc]

The menu part would be awesome

I'm expecting it impatiently ^^

About the theme option would be interesting add support to register themes from bundles (adding theme CSS and js files and overriding the templates by default)

Something about this are planned? Because I'm thinking on doing a admin lte and materialize themes

[javiereguiluz]

Closing it as fixed. The custom menu feature is now ready to use. See https://github.com/javiereguiluz/EasyAdminBundle/blob/master/Resources/doc/tutorials/custom-menu.md