Implement support for dynamic partials

This PR introduces the support of dynamic partial on fully cached static pages:

Usage: Inject uncached partials as part of cached pages

Wouldn't it be fine if you could utilize Statamic's full caching strategy while displaying dynamic content on your pages?

Look no further -- you've found the solution. With the help of uncached partials inside your cached pages you can get the best out of both worlds.

Setting it up

To enable injecting of custom partials make sure to add the {{ cache_evader_scripts }} tag right before the closing </body> tag. Add it either on every page on which you'll use the {{ cache_evader_partial }} tag or add it to your layout globally:

<!doctype html>
<html>
    <head>
        ...
    </head>
    <body>
        {{ template_content }}
        ...
        {{ cache_evader_scripts }}
    </body>
</html>

The tag will load a script which will fetch the contents of your uncached partials by sending an immediate fetch request for each partial. The fetch request will evade the cache and load any dynamic content you specifiy in your partials.

Basic Usage

First things first: Create a simple partial which contains dynamic content: partials/user.antlers.html.

<!-- Your partial with dynamic content -->
{{ if logged_in }}
    Welcome {{ current_user:email }}
{{ else }}
    Please login.
{{ /if }}

Now simply include the partial in your template using the {{ cache_evader_partial }} tag:

<!-- Your template -->
{{ cache_evader_partial:user }}
<!--                    ^^^^ -> This is the file name of the partial. -->

That's it. Your fully cached page will now always display your user's email!

Parameters

You can add any number of parameters to your partial. You can access the parameters as regular variables in your partial.

Important: \ Keep in mind, parameters are publicly visible -- don't share secrets using parameters!

<!-- Your partial with dynamic content -->
{{ if logged_in }}
    Welcome {{ current_user:email }}
{{ else }}
    Please <a href="{{ login_url }}">login</a>.
{{ /if }}

<!-- Your template -->
{{ cache_evader_partial:user login_url="/login" }}

Displaying a loading message

You can display a loading message or an indicator. Simply wrap your loading indicator in the tag pair:

<!-- Your template -->
{{ cache_evader_partial src="user" login_url="/login" }}
    Loading login state ...
{{ /cache_evader_partial }}

Placeholder element

When you include a partial using the {{ cache_evader_partial }} tag, a placeholder div will be rendered instead of the partial. The placeholder is eventually swaped out with the content of your partial.

You can change the placeholder by adding a wrap parameter: {{ cache_evader_partial src="..." wrap="span" }}.

Wrapping of your partial's content

Your partial's content will be wrapped in a div element. You can avoid this behaviour by rendering a single root element in your partial.

This will be wrapped in a div:

<span>
    Welcome {{ current_user:email }}!
</span>
<a href="{{ logout_url }}">Not {{ current_user:email }}?</a>

This will NOT be wrapped in a div:

<p>
    <span>
        Welcome {{ current_user:email }}!
    </span>
    <a href="{{ logout_url }}">Not {{ current_user:email }}?</a>
</p>

Script tags

Yes! You can include script tags in your partials. They'll be executed.

<!-- Your partial with dynamic content -->
{{ if logged_in }}
    Welcome {{ current_user:email }}
{{ else }}
    Please <a href="{{ login_url }}">login</a>.
{{ /if }}

<script src="{{ mix src='/js/user.js' }}"></script>

JavaScript Hooks

Before a fetch request is sent

Before each fetch request is sent to your server the cacheEvaderBeforeInject event is triggered on the placeholder element. You can cancel the fetch request by invoking preventDefault() on the event.

window.addEventListener('cacheEvaderBeforeInject', ev => {
  ev.preventDefault(); // No fetch request is sent.
  // ev.target -- The placeholder element
  // ev.detail -- See below which properties are available. 
});

The event will have a detail property which contains the url to which the request is sent and also all the parameters you've supplied to the partial.

Name	Type	Purpose
url	`string`	The URL which will render the partial's contents
params	`object`	An object which contains all the parameters you've supplied to the partial
params.view	`string`	The path to the partial
params.signature	`string`	Laravel's URL signature

After the content was injected

After the dynamic content of your partial was fetched & injected into the DOM the cacheEvaderAfterInject event is triggered on the injected element.

window.addEventListener('cacheEvaderAfterInject', ev => {
  // ev.target -- See below what the target will be.
  // ev.detail -- See below which properties are available.
});

The value of the event target will be the wrapping element of your partial. If your partial does have a single root element, the value of target will be your root element. Otherwise it'll be a wrapping div.

The event will have a detail property which contains the url to which the request was sent to, all the parameters you've supplied to the partial and the server's response.

Name	Type	Purpose
response	`Response`	The response object
url	`string`	The URL which will render the partial's contents
params	`object`	An object which contains all the parameters you've supplied to the partial
params.view	`string`	The path to the partial
params.signature	`string`	Laravel's URL signature

How do dynamic partials work in detail?

When using the {{ cache_evader_partial }} tag, a placeholder will be rendered with no actual content.
The JavaScript you add to the browser using the {{ cache_evader_scripts }} tag will iterate over each placeholder and will send a fetch request to the server
Your server renders the partial and sends it to the browser
The placeholder will be swaped with the actual content

alpshq / statamic-cache-evader