[RFC] Custom backend routes

[sheeep]

One of the problems when developing custom applications with a CMS part is the fact that you'll end up using two different backends. The one for your application and the one for the Contao part. Having a possibility to uniform these two would help application developer to create an application backend rapidly as they could use all sort of already existing stuff; like form templates, error messages, log viewer and the like. Currently the Contao backend is optimised for DCA views (even though it certainly allows for custom backend views, eg. Isotope). This pull request enables you to easily create custom backend views and feed them data from Symfony controllers.

This is a PoC and RFC. So comment away.

Problems

• The CustomBackendViewListener is used to append the controller response to the backend templates' main attribute. But this should not be done if it is not a custom backend route. Otherwise the base template will be loaded twice. This is why there is a new request parameter _custom_backend_view. Could be named better.
• There is currently no way to overwrite the headline attribute of the base template to set a custom title. This needs to be fixed somehow. (Same goes for <title></title>)
• TL_SCRIPT is always set to the current _route. This is not /contao anymore when using a custom backend route. One place where this failed was in the navigation method of the BackendUser, where the list of linked modules was built. It previously relied on TL_SCRIPT which I briefly replaced with a $router->generate call. Are there any other places you could think of where this could be a problem?

How to test this

In order to create a backend route, create a standard controller and add the following parameters to the Route annotation (you could also configure this in a YML/XML file)

• _custom_backend_view: This parameters distinguishes custom from already exsting backend calls.
• _backend_module: Not necessarily needed, but we determine the active backend module through this.

// src/AppBundle/Controller/BackendController.php
namespace AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

/**
 * @Route("/contao", defaults={
 *     "_scope" = "backend",
 *     "_token_check" = true,
 *     "_custom_backend_view" = true,
 *     "_backend_module" = "test"
 * })
 */
class BackendController extends Controller
{
    /**
     * @Route("/test", name="backend.test")
     * @Template("AppBundle::test.html.twig")
     */
    public function testAction()
    {
        return [
            'content' => 'Content'
        ];
    }
}

For reference: Here is the test template.

{# src/AppBundle/Resources/views/test.html.twig #}
{% extends "@ContaoCore/Backend/be_page.html.twig" %}

{% block panel %}
    Panel
{% endblock %}

{% block errors %}
    An error occured
{% endblock %}

{% block content %}
    {{ content }}
{% endblock %}

Create a backend module and insert it to the list of active backend modules. The previously added parameter _backend_module is now used to determine if the module is active or not.

// src/AppBundle/EventListener/UserNavigationListener.php
namespace AppBundle\EventListener;

use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\Routing\RouterInterface;

class UserNavigationListener
{
    protected $requestStack;
    protected $router;

    public function __construct(RequestStack $requestStack, RouterInterface $router)
    {
        $this->requestStack = $requestStack;
        $this->router = $router;
    }

    public function onGetUserNavigation($arrModules, $blnShowAll)
    {
        $arrModules['content']['modules']['test'] = [
            'title' => 'A backend route test module',
            'label' => 'Test',
            'class' => 'navigation test',
            'href'  => $this->router->generate('backend.test')
        ];

        if ($this->requestStack->getCurrentRequest()->attributes->get('_backend_module') === 'test') {
            $arrModules['content']['modules']['test']['class'] .= ' active';
        }

        return $arrModules;
    }
}

Add it as a service and enable it to be executed by the Hook.

# app/config/config.yml
services:
    app.user_navigation_listener:
        class: "AppBundle\\EventListener\\UserNavigationListener"
        arguments:
            - "@request_stack"
            - "@router"

// src/AppBundle/Resources/contao/config/config.php
$GLOBALS['TL_HOOKS']['getUserNavigation'][] = ['app.user_navigation_listener', 'onGetUserNavigation'];

The whole thing looks like this in the end.

[aschempp]

You should take a look at #444 that uses a Symfony controller to render a Contao backend view.

[leofeyer]

I like the PR. We should definitely discuss the open topics and the implementation details at the next core meeting.

[leofeyer]

@sheeep What's the status on this one?

[discordier]

Current implementation is at a different branch: https://github.com/sheeep/core-bundle/commits/features/refactor-backend-modules
It depends on https://github.com/sheeep/core-bundle/issues/1, where we wrote the TODO list.

[sheeep]

Since 3c06d92 the supported blocks changed. A current example of a backend view template would look like this:

{% extends "@ContaoCore/Backend/be_page.html.twig" %}

{% block headline %}
    Not only the content of the `title`-tag but also the title of the content section.
{% endblock %}

{% block error %}
    Will be placed within the error block.
{% endblock %}

{% block main %}
    Main Content.
{% endblock %}

Also, you don't need to specify a backend route with the route attribute custom_backend_route = true anymore.

[leofeyer]

Shouldn't this be contao.twig.base_template_extension?

[leofeyer]

Big thanks @sheeep!

[aschempp]

You should use the ScopeMatcher service instead

[fritzmg]

Question: do I need to set the _locale manually within a custom back end controller? I have a custom back end route where I use the translator, e.g.

$framework = $this->get('contao.framework');
$framework->initialize();
$translator = $this->get('translator');
$goBack = $translator->trans('MSC.goBack', [], 'contao_default');

However, some users report that they do not see any translations. They only see MSC.goBack in this example. Thus I am wondering if may be simply the _locale is missing from the request.

[ausi]

This seems weird. The Contao translator uses $GLOBALS['TL_LANGUAGE'] and always falls back to en. At least the english message should be shown in all cases.

[fritzmg]

Yeah I thought so as well. Also I cannot reproduce it locally.

[dmolineus]

However, some users report that they do not see any translations.

@fritzmg Hint: The integrated contao translator is a Contao 4.5 feature. I experienced the missing labels on Contao 4.4 LTS.

There are some backports available, f.e. as part of https://github.com/contao-community-alliance/translator

[fritzmg]

Oh, haha. I did not know that :)