How to Embed Asynchronous Content with hinclude.js

How to Embed Asynchronous Content with hinclude.js

Embedding controllers in templates is one of the ways to reuse contents across multiple templates. To further improve performance you can use the hinclude.js JavaScript library to embed controllers asynchronously.

First, include the hinclude.js library in your page linking to it from the template or adding it to your application JavaScript using Webpack Encore.

As the embedded content comes from another page (or controller for that matter), Symfony uses a version of the standard render() function to configure hinclude tags in templates:

  1. {{ render_hinclude(controller('...')) }}
  2. {{ render_hinclude(url('...')) }}

Note

When using the controller() function, you must also configure the fragments path option.

When JavaScript is disabled or it takes a long time to load you can display a default content rendering some template:

  • YAML

    1. # config/packages/framework.yaml
    2. framework:
    3.     # ...
    4.     fragments:
    5.         hinclude_default_template: hinclude.html.twig

  • XML

    1. <!-- config/packages/framework.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xmlns:framework="http://symfony.com/schema/dic/symfony"
    6.     xsi:schemaLocation="http://symfony.com/schema/dic/services
    7.         https://symfony.com/schema/dic/services/services-1.0.xsd
    8.         http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    10.     <!-- ... -->
    11.     <framework:config>
    12.         <framework:fragments hinclude-default-template="hinclude.html.twig"/>
    13.     </framework:config>
    14. </container>

  • PHP

    1. // config/packages/framework.php
    2. $container->loadFromExtension('framework', [
    3.     // ...
    4.     'fragments' => [
    5.         'hinclude_default_template' => 'hinclude.html.twig',
    6.     ],
    7. ]);

New in version 4.3: The framework.fragments.hinclude_default_template option was introduced in Symfony 4.3. In previous Symfony versions it was called framework.templating.hinclude_default_template.

You can define default templates per render() function (which will override any global default template that is defined):

  1. {{ render_hinclude(controller('...'),  {
  2.     default: 'default/content.html.twig'
  3. }) }}

Or you can also specify a string to display as the default content:

  1. {{ render_hinclude(controller('...'), {default: 'Loading...'}) }}

Use the attributes option to define the value of hinclude.js options:

  1. {# by default, cross-site requests don't use credentials such as cookies, authorization
  2.    headers or TLS client certificates; set this option to 'true' to use them #}
  3. {{ render_hinclude(controller('...'), {attributes: {'data-with-credentials': 'true'}}) }}
  5. {# by default, the JavaScript code included in the loaded contents is not run;
  6.    set this option to 'true' to run that JavaScript code #}
  7. {{ render_hinclude(controller('...'), {attributes: {evaljs: 'true'}}) }}

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.