Fork me on GitHub

hinclude.js

Tired of regenerating HTML pages from templates? Want more from Web caches? HInclude makes one thing very easy; including other bits of HTML into your Web page, using the browser.

See also Gustaf Nilsson Kotte's h-include - it uses Web Components to do the same thing.

The Basics

Hinclude adds one element to HTML; hx:include. When the browser encounters this element, it will include the document at the end of the src attribute.

To use it, first download a copy of the library and make it available on your site;

Download: hinclude.js

Now, in each page where you want to use HInclude, add a namespace declaration and a script tag to the top (changing the script tag to point to your copy):

  <html xmlns:hx="http://purl.org/NET/hinclude">
    <head>
      <script src="/lib/hinclude.js"
       type="text/javascript"></script>
  ...

Then, wherever you want to include something, do this:

  <hx:include src="/other/document/here.html"></hx:include>

Where /other/document/here.html is the document you want to include. Note that because of limitations in the JavaScript security model, it must be on the same server.

For example, . You can include any HTML markup that would be valid in context.

Rendering Mode

By default, each one is fetched in the background, and the page is updated only when they all are available.

This is bounded by a timeout, by default five seconds. After the timeout, HInclude will show what it has and keep on listening for the remaining responses. The timeout is configurable; e.g.,

  <meta name="include_timeout" content="2" />

in the document's head section will set the timeout to two seconds.

However, it's also possible to have HIncludes become visible as they're available, using the include_mode meta element with a value of "async". While this shows the included content quicker, it may be less visually smooth.

For example, including this in the head section of your HTML:

  <meta name="include_mode" content="async" />

will instruct HInclude to show included sections as soon as they're available.

Default Content

Before the included content is displayed, anything inside the include element (hereafter, default content) will be visible. For example, this:

  <hx:include src="new">
    this content will be overwritten by the included content
  </hx:include>

Looks like this: this content will be overwritten by the included content.

Since HTML instructs browsers to ignore elements they don’t understand, default content is also shown by those that have JavaScript turned off.

Of course, you can have no default content, in which case nothing will show up until the include is successful. Which brings up…

Enable crossdomain call

if you want to use crossdomain hinclude with credentials like session or cookies you have to update your hinclude html tag to set data-with-credentials.
Or in symfony : 
     {{ render_hinclude(url('here_route'), {id: 'my-id', attributes: {"data-with-credentials": "true"} }) }}

Advanced Error Handling

Hinclude will also show default content if there is some problem with loading the include.

That's adequate for typical applications. However, for debugging and other specialised purposes, HInclude allows you to control the display of errors through CSS, by changing the class of the include element based on the result of inclusion.

For example, if fetching the included URL results in a 404 Not Found status code, the class of the include element will be changed to include_404. Likewise, a 500 Server Error status code will result in the include element’s class being changed to include_500.

For example, this content is shown because there was a 404this content is shown because there was a 500.

View the source of this page to see how that worked…