[TYPO3-mvc] Fluid: Fallback paths for templates

[Bastian Waidelich]

Fellow Fluid users,

as you probably all know, when you want to change a template of a 3rd 
party extension/package in Fluid you currently have to change the path 
to the template directory and copy *all* templates to that location.
Back then we deliberately didn't implement a "fallback" mechanism 
because we feared the system becoming too complex to use. While we still 
think that overly usage of fallbacks would probably produce more 
confusion than convenience we realized the usefulness of such feature in 
the meantime and soon you'll finally be able to override single 
templates, partials and layouts without having to copy more than you need!


Now, there are two approaches to solve this:

Claus has provided a patch[1] for the Fluid extension that supports so 
called "configuration overlays".
To specify a fallback rule for your template root path you would add:
plugin.tx_yourextension.view.overlays.foo.templateRootPath = 
EXT:foo/Resources/Private/Templates/
see [2] for further examples.


In TYPO3 Flow there is currently no defined way to change view options 
at all..
This will change with Marc's patch[3] that will allow us to set all 
kinds of options in a new configuration file called "Views.yaml":

-
   requestFilter: 'isPackage("My.Package")'
   options:
     templateRootPath: 'resource://My.Package/Private/Templates'


The "requestFilter" uses Eel to match arbitrary requests. This adds 
complexity, but it also allows us to cover almost every thinkable 
scenario including modifying a single template depending on the called 
action or on the requested format:

-
   requestFilter: 'isPackage("My.Package") && isController('Product') && 
isAction('list') && isFormat('xml')'
   options:
     templatePathAndFilename: 
'resource://My.Package/Private/Templates/Product/CustomList.xml'

Note: you'll find the complete documentation in the Gerrit change-set, 
soon to be rendered on docs.typo3.org.


Nevertheless it would be quite cumbersome to use this for the regular 
use case of changing some of the templates of a package, because you 
would have to add a lot of conditions. Furthermore we'd like to keep the 
Fluid core in sync with TYPO3 CMS as completely as possible and Eel 
won't make it into CMS in the foreseeable future.


Yesterday we had a meeting with Anja, Christian Müller, Marc & Olly. I 
also had input from Sebastian, Helmut and Claus who couldn't join us 
unfortunately.


We decided (unless you have objections) to go for a simplified version 
of Claus' approach and to integrate that with Marcs Views.yaml change 
for Flow. In practice that means:
Instead of configuration overlays we change the main Fluid options 
"templateRootPath", "layoutRootPath" & "partialRootPath" to be arrays 
rather than strings, so "..RootPath" becomes "..RootPaths" and Fluid 
iterates over all path until a matching template is found.

For the Fluid extension the configuration would then look like:

plugin.tx_yourextension.view.templateRootPaths {
	foo = EXT:foo/Resources/Private/Templates/
	news = EXT:news/Resources/Private/Templates/
}

For Flow a similar configuration would be:

-
   requestFilter: 'isPackage("Vendor.News")'
   options:
     templateRootPaths: ['resource://My.Package/Private/Templates', 
'resource://Vendor.News/Private/Templates']


I'm currently incorporating these changes to the Fluid package. 
Including tests that should be done by next week so we can back port 
those to the Fluid extension and adjust the documentation.


One issue that is not yet completely clear to me is: What to do with the 
existing options "templateRootPath", "layoutRootPath" & "partialRootPath"?
In any case we must keep them for now in order to stay backwards 
compatible. But I even think that we shouldn't deprecate them and only 
map them to their counter-parts.
That means:

$view->setTemplateRootPath('Foo');
is the same as
$view->setTemplateRootPaths(array('Foo'));

Or do you think that's too confusing?


We also briefly discussed how we can keep Fluid package & extension 
generally in sync.
There is a "Google Summer of Code"-project[4] with the goal to have a 
standalone version of Fluid which could be used by Flow, Extbase and 
other PHP frameworks.. Unfortunately Fluid still contains a lot of 
dependencies to Flow. We'd have to split up Flow into smaller packages 
or copy a lot of code currently, so we can't count on that in the near 
future.
Thanks to Tymoteusz, Stefan, Anja the infamous "FluidBackPorter" is 
still (almost) up to date so that we can reflect changes from the 
package to the extension in a reasonable amount of time.


Okaay, this was supposed to become a quick summary of yesterdays 
meeting.. I hope I didn't swamp you with information ;)


[1] https://review.typo3.org/#/c/21580/
[2] https://github.com/FluidTYPO3/view#template-path-overlays
[3] https://review.typo3.org/#/c/16392/
[4] http://wiki.typo3.org/Gsoc2013/Ideas#Cut_dependencies_on_Flow

-- 
Bastian Waidelich
--
Core Developer Team

TYPO3 .... inspiring people to share!
Get involved: typo3.org