[FEATURE] Allow fallback paths in FLUIDTEMPLATE
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-61361-FallbackTemplatePathsForFluidStandaloneView.rst
1 ===================================================================================
2 Feature: #61361 - Template Path Fallback for Fluid StandaloneView and FLUIDTEMPLATE
3 ===================================================================================
4
5 Description
6 ===========
7
8 StandaloneView
9 --------------
10
11 Earlier in the development of Fluid, a template fallback was introduced
12 in the TemplateView, providing the possibility to pass a set of possible
13 file locations to the View Configuration, where Templates, Layouts and Partials
14 can be found.
15
16 The same functionality is now in the StandaloneView. It is possible to
17 let the system look up the fitting paths for Partials and Layouts. It is
18 in the nature of the StandaloneView to get a specific template file set, so
19 for Templates there is no lookup requirement.
20
21 As a developer or integrator, you can configure your View as follows:
22
23 ::
24 $view = $this->objectManager->get('TYPO3\\CMS\\Fluid\\View\\StandaloneView');
25 $view->setFormat('html');
26 $view->setTemplatePathAndFileName(ExtensionManagementUtility::extPath('myExt') . 'Resources/Private/Templates/Email.html');
27 $view->setLayoutRootPaths(array(
28 'default' => ExtensionManagementUtility::extPath('myExt') . 'Resources/Private/Layouts',
29 'specific' => ExtensionManagementUtility::extPath('myTemplateExt') . 'Resources/Private/Layouts/MyExt',
30 ));
31 $view->setPartialRootPaths(array(
32 'default' => ExtensionManagementUtility::extPath('myExt') . 'Resources/Private/Partials',
33 'specific' => ExtensionManagementUtility::extPath('myTemplateExt') . 'Resources/Private/Layouts/MyExt',
34 'evenMoreSpecific' => 'fileAdmin/templates/myExt/Partials',
35 ));
36 ..
37
38 With this, the View will first look up the requested layout file in the path with the key
39 _specific_, and in case there is no such file, it will fall back to _default_. For the partials the
40 sequence would be _evenMoreSpecific_, then _specific_, then fall back to _default_.
41
42 You are free in the naming
43 of the keys. The paths are searched from bottom to top.
44 In case you choose for numeric array keys, the array is ordered first, then reversed for the lookup, so
45 the highest index is accessed first.
46
47 FLUIDTEMPLATE
48 -------------
49
50 Additionally the TypoScript Content Object FLUIDTEMPLATE, which is based on StandaloneView, also supports this
51 kind of fallback mechanism.
52 Two new TypoScript options are added for this purpose:
53
54 * partialRootPaths
55 * layoutRootPaths
56
57 Example usage:
58
59 ::
60 page.10 = FLUIDTEMPLATE
61 page.10.file = EXT:sitedesign/Resources/Private/Templates/Main.html
62 page.10.partialRootPaths {
63 10 = EXT:sitedesign/Resources/Private/Partials
64 20 = EXT:sitemodification/Resources/Private/Partials
65 }
66 ..
67
68 In case you're using the old options (partialRootPath, layoutRootPath) together with the new options, the content of
69 the old options will be placed at the first position (index zero) in the fallback list.
70
71
72 Impact
73 ======
74
75 In order to change the skin of an extension output, provided by the Fluid StandaloneView, you are no longer required to
76 copy the whole Resources folder into fileadmin or to some specific location, but you can pick only the files you want
77 to change. Those need to be organized in folders, which are then configured for the view. The system will fall through
78 all the provided locations, taking the first fitting file it finds.