Timber/TWIG for Wordpress - Questions about some basics - php

Question

For instance in the Timber Documentation we have lots of examples like the following:
{% for item in menu.items %}
{{ post.author.name }}
Now the "item" and the "menu" etc. are all predefined, and nowhere defined by a user in the files (otherwise by my understanding Timber and TWIG would not make much sense).
What I do not understand is where I can find out a list these. In the Docs of Timber, there are a bunch of examples, then when I compare them to the Timber Starter Theme for Wordpress, I see a bunch of them, which aren't even mentioned in the documentations.
Where do I find a list of all available items?
What is the logic behind these items?

Answer 1

Don’t feel dumb, because you’re not! We’ve all been there. I had the same questions, when I started out with Timber. We’re trying to improve the documentation constantly, so questions like these help us to find out what we can do better 👍.
Whenever you see a variable in Twig, it can actually come from a couple of different places:
Variables from the global context
There’s a filter that most of us use to make a variable globally available whenever you set up your context through Timber::get_context(). When you see {% for item in menu.items %}, then it’s probably from the section of the docs about «Setting up a menu globally». I have to admit that we explain the filter through this example only, which is not ideal. But we’re changing this. In the next version of Timber, we try to explain the global context better (make sure to only read the section about the global context, because the part about «Template Contexts» describes functionality that is not available yet.)
Variables from the template
Consider the following example:
$context = Timber::get_context();
$context['post'] = new Timber\Post();
Timber::render( 'single.twig', $context );
Here you set up your context through Timber::get_context(). When you use Timber::get_context(), you’ll get a bunch of variables that make sense globally, but not for every template.
The $context variable is an array, holding all the variables you want to pass to your Twig template, in this case single.twig. When can add our own variables, like in the example above, where we add post that hold a Timber\Post object of the currently displayed post.
Variables from Timber’s classes
In the template, when you see {{ post.author.name }}, then author can be different things:
A property of the Timber\Post object that holds a value. These are all the variables that you’d see when you do {{ dump(post) }}.
A method of the Timber\Post object, that will be excecuted. This might be confusing at first, because in PHP, you always need to add braces to call a function, but in Twig, you don’t need to. When you call $post->author() in PHP, you would use post.author in Twig. To see a list of all the methods that are available for Timber\Post, you need to look into the Reference section for Timber\Post in the docs.
So if you would write the example {{ post.author.name }} in PHP, it would look like this:
$post->author()->name()
So author is a method of Timber\Post, which returns a Timber\User object. The Timber\User object has a method called name, which returns «the human-friendly name of the user».
But! When you just look at {{ post.author.name }}, it could also be a multi-dimensional array that you defined yourself:
$context['post'] = array(
'author' => array(
'name' => 'Tom Riddle',
),
);
You wouldn’t know that just from looking at it in Twig.
Variables from the Twig syntax
When you see {% for item in menu.items %}, then you’re looping over the variable menu.items. The variable menu probably comes from the global context (a Timber\Menu object), and items is a property of this object. The item variable is a new variable that is created to access the current loop item in the for loop. In this example, it’s the current menu item. You can choose any name for item you want.
Variables from includes
You can pass down a variable in Twig through the include statement. For example, if you defined post through your template file and wanted to use a different name in the template that you include, you could use it like this:
{% include 'teaser.twig' with { teaser: post } %}
Coming back to your specific questions:
Where do I find a list of all available items?
What is the logic behind these items?
I’m afraid there isn’t a definitive list, because what a variable is can be very dynamic. It’s mostly a combination of the global context, variables you set from the template, methods and properties from Timber’s classes as well as variables you define yourself in Twig.
If you have more question, add the to this answer as comments and I can update this answer accordingly.