Create TimberView object to handle view rendering

[jarednova]

This is from the discussion in #248 and the #259 epic. Create a new object to better organize how templates are rendered and locations are chosen. This will deprecate (but not eliminate) the current static-based approach to data and rendering.

Acceptance

• Existing functionality for Timber::render and Timber::compile still work
• Themes and multiple plugins can set different rules for the location of twig files
• New methods are documented in wiki
• Method for populating context for template is documented
• Functionality for caching is preserved, new syntax/method is documented
• Review API with 2 collaborators for sanity-check
• Reference of files within twig (extension, inclusion) is considered
• Reference of files within twig (extension, inclusion) is documented

... this work is currently in: https://github.com/jarednova/timber/tree/timber-view. Here's a sample of the API that someone might use in single.php:

Basic theme example with standard locations

$view = new TimberView();
$view->context['post'] = new TimberPost();
$view->cache(600);
$view->render('single.twig');

Plugin example with custom locations

$view = new TimberView('my-plugin-context');
$view->cache(600);
$view->context['days'] = my_plugin_get_days_or_something();
$templates = array(
    get_template_directory(),
    get_template_directory().'/templates',
    __DIR__.'/templates'
);
return $view->compile('calendar-overview.twig', $templates);

[bryanaka]

I really like the idea behind this API. How do you feel about TIMBER_TEMPLATES_PATH constant holding the possible template locations? I feel this is more similar to configuration than anything. The only problem is that a array constant would have to be serialized and unserialized 😒

[jarednova]

@bryanaka, yeah, I think it's wise to have a constant like that. In my thinking, the use-case is for when you want to easily prepend or append a custom path before/after the default locations. Did you have another use-case in mind?

[bryanaka]

No, that is exactly the use-case in mind. sounds fair enough to me.

So I am basically mimicking this API in a project I just started (thus my re-entry to Timber 😉 ), the only thing I changed was exposed a set function which would then set variables on the context assoc. array, which was not a public variable. So like $view->set('post', new TimberPost());. I like it as a personal preference, but not sure if that is just Ember speaking or if this idea would feel natural to PHP devs.

[roopemerikukka]

Hi,

Is there any plans to complete this feature? I'm trying to use Timber in a plugin and would like it to work with both themes that use Timber and themes that don't. Is there any current solutions how I can bypass the fact that I cannot change the locations after first initialisation? Would it be safe to use absolute uris in the plugin and not to set the locations at all so the theme can do that if wanted?

[palmiak]

@jarednova - are there any plans about this?

[palmiak]

I wanted to use Timber in a plugin and investigated how all this works. What surprised me is the fact that we almost have the working functionalaty to use separate templates even for each plugin / theme.

There is something like $paths = apply_filters('timber/loader/paths', $paths); with this we can do something like this:

function filter_paths() {
    return [__DIR__.'/front'];
}

add_filter('timber/loader/paths', 'filter_paths');
Timber::render('admin.twig', $context);
remove_filter('timber/loader/paths', 'filter_paths');

I know it's not pretty, but it's a quite well functioning workaround to problem with $locations which was mentioned for years.

I think it solves all the problems mentioned in #248. Or maybe it's too late and I don't see some obvious problem :)

[jarednova]

I'm closing all 2+ year old issues. If someone wants to pick this up, let's make it a fresh issue