Adventure Documentation

9.a. Server-side render

  1. Introduction
  2. Asynchronous fetching of server-side rendering

Introduction

With Adventure we decided to use the same rendering principle for all kinds of requests, even if they are asynchronous. This means that if we have JavaScript functionality requiring an updated component, it will also be rendered with Smarty and returned from the backend as HTML. There are many reasons for this, but the most important ones are.

  • To keep Smarty as the only template language and template rendering framework.
  • To simplify the stack, no additional JavaScript framework is required to render components, although you can add one if desired.

  • To simplify state management, much like the HATEOAS architecture, the server/backend is the source of truth.

    Hypermedia as the engine of application state (HATEOAS) is a constraint of the REST software architectural style that distinguishes it from other network architectural styles.

    With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through hypermedia. A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.

Any component or component composit written in Smarty can be rendered server-side and returned as HTML. This is done through the /ssr/ endpoint, which returns the HTML with the Content-Type: text/html; charset=utf-8 representation header. The component supports all the properties you'd expect, when rendering thru Smarty. To make fetching and rendering a bit easier in Javascript we have written a small module.

Asynchronous fetching of server-side rendering

Every Smarty component can be fetched asynchronously in JavaScript. This can be done through the /ssr/ endpoint with a component parameter: ?component=SomeComponentFileName.

In JavaScript there are already tools you can import to make this process easier:

import { parseHTML, render } from '@root/elements/serverRender.js'

async function updateSomeComponent() {

    // Fetches SSR component with a page parameter
    // Request: /?component=SomeComponent&page=2
    const updatedComponent = await render('SomeComponent', {page: 2})

    // Parse response text to HTML
    const updatedEl = parseHTML(updatedComponent)

    // Assign new HTML to the DOM
    someElement.innerHTML = updatedEl.innerHTML
}

The only caveat for the /ssr/ endpoint is the fact that all responses are as hypermedia, with the Content-Type: text/html; charset=utf-8 representation header. In other words, the content returned is HTML. This design choice ensures that server-side rendering remains focused on delivering fully-rendered HTML components, which are ready to be inserted into the DOM without additional processing. If you need JSON data for client-side processing or dynamic rendering, you should use the /json/ endpoint instead. The /json/ endpoint is specifically designed to return structured data in JSON format, making it suitable for applications that require raw data for further manipulation or rendering.

Search results