docs: Update v2 caching docs

docs/v2/guides/performance.md

@@ -15,6 +15,10 @@ You can still use plugins like [W3 Total Cache](https://wordpress.org/plugins/w3
 
 ## Cache the Entire Twig File and Data
 
+With Timber you can cache the full Timber render/compile calls. When you do this, the whole template you render and it's data will be cached. This results in faster page rendering by skipping queries and twig compilations. But here’s the cool part: Timber hashes the fields in the view context. This means that **as soon as the data changes, the cache is automatically invalidated**. Yay!
+
+`Timber::render()` and `Timber::compile()` will use the default cache mode which by default is the transient cache mode.
+
 When rendering, use the `$expires` argument in [`Timber::render`](https://timber.github.io/docs/v2/reference/timber-timber/#render). For example:
 
 ```php
@@ -23,19 +27,12 @@ $context['posts'] = Timber::get_posts();
 Timber::render('index.twig', $context, 600);
 ```
 
-In this example, Timber will cache the template for 10 minutes (600 / 60 = 10). But here’s the cool part: Timber hashes the fields in the view context. This means that **as soon as the data changes, the cache is automatically invalidated**. Yay!
+In this example, Timber will cache the template for 10 minutes (600 / 60 = 10) with the default cache mode which is "transient". 
 
 This method is very effective, but crude - the whole template is cached. So if you have any context dependent sub-views (eg. current user), this mode won’t do.
 
-### Set cache mode
-
-As a fourth parameter for [Timber::render()](https://timber.github.io/docs/v2/reference/timber-timber/#render), you can set the `$cache_mode`.
-
-```php
-Timber::render($filenames, $data, $expires, $cache_mode);
-```
-
-The following cache modes are available:
+### Timber cache modes
+Timber has 5 cache modes that it can use for the Timber `Timber::render()` and `Timber::compile()` methods. The following cache modes are available:
 
 | Mode | Description |
 | --- | --- |
@@ -45,69 +42,19 @@ The following cache modes are available:
 | `Timber\Loader::CACHE_SITE_TRANSIENT` | Network wide transients |
 | `Timber\Loader::CACHE_USE_DEFAULT` | Use whatever caching mechanism is set as the default for `Timber\Loader`, the default is `CACHE_TRANSIENT`. |
 
-## Cache _Parts_ of the Twig File and Data
-
-If you want to use [`cache` tag](https://twig.symfony.com/doc/3.x/tags/cache.html) in Twig, you’ll have to install the `twig/cache-extra` package:
-
-```bash
-composer require twig/cache-extra
-```
-
-And register it in Timber like this:
-
-**functions.php**
-
-```php
-use Symfony\Component\Cache\Adapter\FilesystemAdapter;
-use Symfony\Component\Cache\Adapter\TagAwareAdapter;
-use Twig\Extra\Cache\CacheExtension;
-use Twig\Extra\Cache\CacheRuntime;
-use Twig\RuntimeLoader\RuntimeLoaderInterface;
-
-class RunTimeLoader implements RuntimeLoaderInterface
-{
-    public function load($class)
-    {
-        if (CacheRuntime::class === $class) {
-            return new CacheRuntime(new TagAwareAdapter(new FilesystemAdapter()));
-        }
-    }
-}
-
-add_filter('timber/twig', function ($twig) {
-    $twig->addExtension(new CacheExtension());
-    $twig->addRuntimeLoader(new RunTimeLoader());
-
-    return $twig;
-});
-```
-
-You can then use it like this:
-
-```twig
-{% cache 'index;content' %}
-    {% for post in posts %}
-        {% include ['tease-' ~ post.post_type ~ '.twig', 'tease.twig'] %}
-    {% endfor %}
-{% endcache %}
-```
+By default the cache mode is set to transients. You can change the default cache mode globally by using a filter or on a per method basis. We will go over them both.
 
-Read more about it in [Twig’s `cache` documentation](https://twig.symfony.com/doc/3.x/tags/cache.html).
+#### Set Timber cache mode globally
+hier een verhaal over de glogale cache mode.
 
-If you want to use something meaningful for the cache key, you can also generate a cache key from the variables that you use. In the following example, we generate a cache key from `$posts` and then generate a key from it:
+#### Set Timber cache mode per compile or render method
+As a fourth parameter for [Timber::render()](https://timber.github.io/docs/v2/reference/timber-timber/#render), you can set the `$cache_mode`.
 
+For example:
 ```php
-$generator = new Timber\Cache\KeyGenerator();
-$key = $generator->generateKey($posts);
+Timber::render($filenames, $data, 600, Timber\Loader::CACHE_OBJECT);
 ```
 
-### Extra: TimberKeyGeneratorInterface
-
-Instead of hashing a whole object, you can specify the cache key in the object itself. If the object implements `TimberKeyGeneratorInterface`, it can pass a unique key through the method `get_cache_key`. That way a class can for example simply pass `'last_updated'` as the unique key.
-If arrays contain the key `_cache_key`, that one is used as cache key.
-
-This may save yet another few processor cycles.
-
 ## Cache the Twig File (but not the data)
 
 Every time you render a `.twig` file, Twig compiles all the HTML tags and variables into a big, nasty blob of function calls and echo statements that actually gets run by PHP. In general, this is pretty efficient. However, you can cache the resulting PHP blob by turning on Twig’s cache via:
@@ -140,7 +87,7 @@ Thus, during development, you should enable the option for `auto_reload`:
 
 ```php
 add_filter('timber/twig/environment/options', function ($options) {
-    $options['cache'] = true;
+    $options['cache']       = true;
     $options['auto_reload'] = true;
 
     return $options;
@@ -158,6 +105,69 @@ $loader = new Timber\Loader();
 $loader->clear_cache_twig();
 ```
 
+
+## Cache _Parts_ of the Twig File and Data
+
+If you want to use [`cache` tag](https://twig.symfony.com/doc/3.x/tags/cache.html) in Twig, you’ll have to install the `twig/cache-extra` package:
+
+```bash
+composer require twig/cache-extra
+```
+
+And register it in Timber like this:
+
+**functions.php**
+
+```php
+use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+use Symfony\Component\Cache\Adapter\TagAwareAdapter;
+use Twig\Extra\Cache\CacheExtension;
+use Twig\Extra\Cache\CacheRuntime;
+use Twig\RuntimeLoader\RuntimeLoaderInterface;
+
+add_filter('timber/twig', function ($twig) {
+		$twig->addRuntimeLoader(new class implements RuntimeLoaderInterface
+		{
+			public function load($class)
+			{
+				if (CacheRuntime::class === $class) {
+					return new CacheRuntime(new TagAwareAdapter(new FilesystemAdapter('', 0, TIMBER_LOC . '/cache/twig')));
+				}
+			}
+		});
+		$twig->addExtension(new CacheExtension());
+
+    return $twig;
+});
+```
+
+You can then use it like this:
+
+```twig
+{% cache 'index;content' %}
+    {% for post in posts %}
+        {% include ['tease-' ~ post.post_type ~ '.twig', 'tease.twig'] %}
+    {% endfor %}
+{% endcache %}
+```
+
+Read more about it in [Twig’s `cache` documentation](https://twig.symfony.com/doc/3.x/tags/cache.html).
+
+If you want to use something meaningful for the cache key, you can also generate a cache key from the variables that you use. In the following example, we generate a cache key from `$posts` and then generate a key from it:
+
+```php
+$generator = new Timber\Cache\KeyGenerator();
+$key = $generator->generateKey($posts);
+```
+
+### Extra: TimberKeyGeneratorInterface
+
+Instead of hashing a whole object, you can specify the cache key in the object itself. If the object implements `TimberKeyGeneratorInterface`, it can pass a unique key through the method `get_cache_key`. That way a class can for example simply pass `'last_updated'` as the unique key.
+If arrays contain the key `_cache_key`, that one is used as cache key.
+
+This may save yet another few processor cycles.
+
+
 ## Cache the PHP data
 
 Sometimes the most expensive parts of the operations are generating the data needed to populate the twig template. You can of course use WordPress’s default [Transient API](http://codex.wordpress.org/Transients_API) to store this data.
@@ -213,3 +223,6 @@ Timber::render('single.twig', $context, 600);
 // This reports the time diff by passing the $start time
 echo Timber\Helper::stop_timer($start);
 ```
+## Important notices
+
+- Never use `{% spaceless %}` tags to minify your HTML output. These tags are only meant to control whitespace between html tags.