Merge pull request #5 from ezsystems/feat/configuredThemePaths

EZP-24765: Give possibility to set additional paths for a given theme

bundle/DependencyInjection/Compiler/TwigThemePass.php

@@ -69,6 +69,10 @@ public function process(ContainerBuilder $container)
             }
         }
 
+        // Now merge with already configured template theme paths
+        // Template theme paths defined via config will always have less priority than convention based paths
+        $themesPathMap = array_merge_recursive($themesPathMap, $container->getParameter('ezdesign.templates_path_map'));
+
         // De-duplicate the map
         foreach ($themesPathMap as $theme => &$paths) {
             $paths = array_unique($paths);

bundle/DependencyInjection/Configuration.php

@@ -29,7 +29,16 @@ public function getConfigTreeBuilder()
                         ->prototype('scalar')->end()
                     ->end()
                 ->end()
-                ->arrayNode('template_override_paths')
+                ->arrayNode('templates_theme_paths')
+                    ->useAttributeAsKey('theme')
+                    ->example(['some_theme' => ['/var/foo/some_theme_dir', '/another/theme/dir']])
+                    ->info('Collection of template paths by theme.')
+                    ->prototype('array')
+                        ->info('Each path MUST exist')
+                        ->prototype('scalar')->end()
+                    ->end()
+                ->end()
+                ->arrayNode('templates_override_paths')
                     ->info('Directories to add to the override list for templates. Those directories will be checked before theme directories.')
                     ->prototype('scalar')->end()
                 ->end()

bundle/DependencyInjection/EzPlatformDesignEngineExtension.php

@@ -45,7 +45,8 @@ private function configureDesigns(array $config, ConfigurationProcessor $process
         // Always add "standard" design to the list (defaults to application level & override paths only)
         $config['design_list'] += ['standard' => []];
         $container->setParameter('ezdesign.design_list', $config['design_list']);
-        $container->setParameter('ezdesign.templates_override_paths', $config['template_override_paths']);
+        $container->setParameter('ezdesign.templates_override_paths', $config['templates_override_paths']);
+        $container->setParameter('ezdesign.templates_path_map', $config['templates_theme_paths']);
         $container->setParameter('ezdesign.asset_resolution.disabled', $config['disable_assets_pre_resolution']);
 
         // PHPStorm settings

doc/templates.md

@@ -41,12 +41,31 @@ Default fallback order is the following:
 
 > Bundle fallback order is the instantiation order in `AppKernel`.
 
+### Additional theme paths
+In addition to the convention described above, it is also possible to add arbitrary Twig templates directories to a theme
+from configuration. This can be useful when you want to define templates from third-party bundles as part of one of your
+themes, or when upgrading your application in order to use eZ Platform design engine, and that your existing templates
+are not yet following the convention.
+
+```yaml
+ezdesign:
+    design_list:
+        my_design: [my_theme, some_other_theme]
+    templates_theme_paths:
+        # FOSUserBundle templates will be part of "my_theme" theme
+        my_theme:
+            - '%kernel.root_dir%/../vendor/friendsofsymfony/user-bundle/Resources/views'
+```
+
+> **Paths precedence**: Directories following the convention will **always** have the precedence over the ones defined
+> in config. This ensures that it is always possible to override a template from the application.
+
 ### Additional override paths
 It is possible to add addition global override directories, similar to `app/Resources/views/`.
 
 ```yaml
 ezdesign:
-    template_override_paths:
+    templates_override_paths:
         - "%kernel.root_dir%/another_override_directory"
         - "/some/other/directory"
 ```