Template API

Renders individual templates outside of a page context.

The Template API allows developers to request the rendered output of a page or section template with more control than the Resources API. The request specifies the template as well as the prop queries in JSON that are required to satisfy the template’s schema. This allows for dynamic frontends to continue to leverage the templating and rendering engine of a custom site.

All requests can be made relative to your published site host name.

Example

The following fetch call renders an example section that then uses the response to update an HTML node’s inner HTML:

fetch('/s/api/v1/template', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		template: 'components/sections/example',
		props: {
			product: {
				filters: {
					id: 2
				}
			},
			input: 'abc'
		},
	})
})
	.then((response) => response.text())
	.then((text) => {
		node.innerHTML = text;
	});

Loading uncacheable resources

Loading resources to be used in templates is done by defining a schema key and filters in the page JSON. The resource data is loaded at render time and provided as variables to the page’s template. Our rendering engine takes this output and caches the result. The cached result is served the next time the same page is visited. The cache is cleared upon certain events like site re-publishing or catalog updates.

However, there are resources that are deemed uncacheable. If any of these resources are used during a page render, the output can’t be cached and benefit from quicker subsequent page loads.

• Uncacheable resources
  • Cart
  • CustomerAccount
  • LoyaltyProgram
  • ScheduleTimes
  • ScheduleDays

For cases like this, we recommend asynchronously rendering the templates that contain or require an uncacheable resource. This way, the initial page render contains only cacheable contents and it will be served from cache. The asynchronous template will then render the sections that contains the uncacheable resource(s), after the initial page load.

Uncacheable resource loading example

The parent template is responsible for providing a placeholder element that is injected with the Cart template response from the getTemplate API.

In this case, the render of the parent template is cacheable while the uncacheable Cart resource is deferred until after the DOMContentLoaded browser event.

// parent.html.twig
<div id="cart-placeholder">
    Loading...
</div>

<script>
    document.addEventListener('DOMContentLoaded', async () => {
        const text = await window.SquareWebSDK.template.getTemplate({
            template: 'components/partials/cart'
        });

        document.getElementById('cart-placeholder').innerHTML = text;
    });
</script>

{% schema %}
{
	"item": {
		"type": "item"
	},
    "aboutUs": {
        "type": "string"
    }
}
{% endschema %}

// components/partials/cart.html.twig

{% if cart.created %}
   <p>{{ cart.id }}</p>
{% else %}
    <p>Cart not created</p>
{% endif %}

{% schema %}
{
	"cart": {
		"type": "cart"
	}
}
{% endschema %}

Dealing with scripts

When using the template API, your rendered template may contain script tags that do not automatically execute when inserting the contents into the DOM placeholder.

// Template API response
<script type="application/javascript" src="/themes/modal-handler.js"></script>

<button class="item-modal">
    Open Item Modal
</button>

Depending on your theme’s needs, you may want to execute the javascript before, after, or at the same time as when the content is applied to the page. The script handling will be the theme developer’s responsibility as our platform cannot anticipate what the theme developer’s contextual needs are.

Here is an example of Brisk’s utility helper that waits until the template contents are present on the DOM before the scripts are appended and loaded.