Static rendering

Static rendering is a built-in feature shipped since Wordless 5. It allows you to statically compile a template into HTML and serve it. Successive rendering requests will directly serve the static HTML if present.

You can compile any template into static HTML simply by using the render_static() function in place of any render_template() PHP function or any PUG’s include into you views.

This way you have control on having a completely static template or just some partial contents; so you can isolate and make static a specific partial with heavy queries, or the whole page.

This is the definition of render_static() function:

render_helper.php
163
164
165
166
167
168
169
170
    function render_static($name, $locals = array()) {
        $template_found = $this->template_info($name, 'pug');
        if (isset($template_found->path)) {
            $fileInfo = new SplFileInfo($template_found->path);
            $extension = $fileInfo->getExtension();
        }
        if (!isset($extension) || 'pug' !== $extension) {
            render_error("Static rendering only available for PUG templates", "<strong>Ouch!!</strong> It seems you required a <code>render_static</code> for a PHP template, but this render method is supported only for PUG. Use <code>render_partial</code> or <code>render_template</code> instead.");

Warning

Using static rendering could lead to undesired effects by design (not specifically with Wordless). Be sure to know what you’re doing. It’s not alwas just a matter to be faster.

Static template example

Given this into index.php

if (is_front_page()){
  render_static("templates/static");
}

and given this views/templates/static.pug

extends /layouts/default.pug

block yield
  h2 Archive (static example)

  ul.archive
    while (have_posts())
      - the_post()

      li
        include /partials/post.pug

visiting your home page will produce a static HTML into theme’s tmp/ dir similar to static.8739602554c7f3241958e3cc9b57fdecb474d508.html (template name + sha + extension).

The first time the template will be evaluated and compiled. Reloading the page the HTML will be served without re-compiling.

Static partial example

Given this into index.php

if (is_front_page()){
  render_template("templates/archive");
}

and given this views/templates/static.pug

extends /layouts/default.pug

block yield
  h2 Archive (static example)

  ul.archive
    while (have_posts())
      - the_post()

      li
        - render_static('partials/post')

visiting your home page will produce a static HTML into theme’s tmp/ dir similar to post.8739602554c7f3241958e3cc9b57fdecb474d508.html (template name + sha + extension).

Invalidating the cache

You have 3 way to handle this:

  • manually deleting one or more .html files from theme’s tmp/ folder
  • blank tmp/ folder with wp wordless theme clear_tmp
  • from the “Cache management” menu within the admin panel

The “Cache management” menu needs to be activated decommenting this line

backend.php
85
86
87
88
89
90
91
/*
 * Create Cache management menu & render cache management page
 *
 * A default page is rendered, but you can make your own function and replace it instead of Wordless::render_static_cache_menu
 * Enable cache management by uncommenting line below.
 */
// add_action('admin_menu', 'cache_management');

Manually manage cache SHA

The cache policy of static generated views is based on the view’s name + the SHA1 of serialized $locals. As it stands the best way to introduce business logic in the expiration logic is to pass ad hoc extra variables into the $locals array. For example having

render_static('pages/photos', $locals = [ 'cache_key' => customAlgorithm() ])

when customAlgorithm() will change its value, it will invalidate the static cache for this template

Known limitations

render_static creates hashes using the serialized $locals array; since it’s possible to pass a Closure in $locals but it’s impossible to serialize closures in PHP you cannot use Wordless’s render_static if you’re passing in closures.