<include-fragment> element

A Client Side Includes tag.

Installation

Available on Bower as include-fragment-element.

$ bower install include-fragment-element

This component is built on the Web Component stack. Specifically, it requires a feature called Custom Elements. You'll need to use a polyfill to get this feature today. Either the Polymer or X-Tag frameworks supply a polyfill, or you can install the standalone CustomElements polyfill.

Legacy browsers require other generic polyfills. See examples/index.html for details.

<script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-hi-ce.js"></script>

Usage

All include-fragment elements must have a src attribute from which to retrieve an HTML element fragment.

The initial page load should include fallback content to be displayed if the resource could not be fetched immediately.

Original:

<div class="tip">
  <include-fragment src="/tips">
    <p>Loading tip…</p>
  </include-fragment>
</div>

On page load, the include-fragment element fetches the URL, the response is parsed into an HTML element, which replaces the include-fragment element entirely.

Result:

<div class="tip">
  <p>You look nice today</p>
</div>

The server must respond with an HTML fragment to replace the include-fragment element. It should not contain another include-fragment element or the server will be polled in an infinite loop.

Errors

If the URL fails to load, the include-fragment element is left in the page and tagged with an is-error CSS class that can be used for styling.

Options

Attribute	Options	Description
src	URL string	Required URL from which to load the replacement HTML element fragment.

Patterns

Deferring the display of markup is typically done in the following usage patterns.

• A user action begins a slow running background job on the server, like backing up files stored on the server. While the backup job is running, a progress bar is shown to the user. When it's complete, the include-fragment element is replaced with a link to the backup files.

• The first time a user visits a page that contains a time-consuming piece of markup to generate, a loading indicator is displayed. When the markup is finished building on the server, it's stored in memcache and sent to the browser to replace the include-fragment loader. Subsequent visits to the page render the cached markup directly, without going through a include-fragment element.

Relation to Server Side Includes

This declarative approach is very similar to SSI or ESI directives. In fact, an edge implementation could replace the markup before its actually delivered to the client.

<include-fragment src="/github/include-fragment/commit-count" timeout="100">
  <p>Counting commits…</p>
</include-fragment>

A proxy may attempt to fetch and replace the fragment if the request finishes before the timeout. Otherwise the tag is delivered to the client. This library only implements the client side aspect.

Browser Support

• Chrome
• Firefox
• Safari 9+
• Internet Explorer 11+
• Microsoft Edge