github / include-fragment-element

A client-side includes tag.

<include-fragment> element

A Client Side Includes tag.

Installation

$ npm install --save @github/include-fragment-element

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.

import '@github/include-fragment-element'

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.

Other Attributes

accept

This attribute tells <include-fragment/> what to send as the Accept header, as part of the fetch request. If omitted, or if set to an empty value, the default behaviour will be text/html. It is important that the server responds with HTML, but you may wish to change the accept header to help negotiate the right content with the server.

loading

This indicates when the contents should be fetched:

• eager: Fetches and load the content immediately, regardless of whether or not the <include-fragment/> is currently within the visible viewport (this is the default value).
• lazy: Defers fetching and loading the content until the <include-fragment/> tag reaches a calculated distance from the viewport. The intent is to avoid the network and storage bandwidth needed to handle the content until it's reasonably certain that it will be needed.

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.

Events

Request lifecycle events are dispatched on the <include-fragment> element.

• loadstart - The server fetch has started.
• load - The request completed successfully.
• error - The request failed.
• loadend - The request has completed.
• include-fragment-replace (cancelable) - The success response has been parsed. It comes with event.detail.fragment that will replace the current element.
• include-fragment-replaced - The element has been replaced by the fragment.

const loader = document.querySelector('include-fragment')
const container = loader.parentElement
loader.addEventListener('loadstart', () => container.classList.add('is-loading'))
loader.addEventListener('loadend', () => container.classList.remove('is-loading'))
loader.addEventListener('load', () => container.classList.add('is-success'))
loader.addEventListener('error', () => container.classList.add('is-error'))

Options

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

Deferred loading

The request for replacement markup from the server starts when the src attribute becomes available on the <include-fragment> element. Most often this will happen at page load when the element is rendered. However, if we omit the src attribute until some later time, we can defer loading the content at all.

The <details-menu> element uses this technique to defer loading menu content until the menu is first opened.

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.

CSP Trusted Types

You can call setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null) from JavaScript to set a CSP trusted types policy, which can perform (synchronous) filtering or rejection of the fetch response before it is inserted into the page:

import IncludeFragmentElement from "include-fragment-element";
import DOMPurify from "dompurify"; // Using https://github.com/cure53/DOMPurify

// This policy removes all HTML markup except links.
const policy = trustedTypes.createPolicy("links-only", {
  createHTML: (htmlText: string) => {
    return DOMPurify.sanitize(htmlText, {
      ALLOWED_TAGS: ["a"],
      ALLOWED_ATTR: ["href"],
      RETURN_TRUSTED_TYPE: true,
    });
  },
});
IncludeFragmentElement.setCSPTrustedTypesPolicy(policy);

The policy has access to the fetch response object. Due to platform constraints, only synchronous information from the response (in addition to the HTML text body) can be used in the policy:

import IncludeFragmentElement from "include-fragment-element";

const policy = trustedTypes.createPolicy("require-server-header", {
  createHTML: (htmlText: string, response: Response) => {
    if (response.headers.get("X-Server-Sanitized") !== "sanitized=true") {
      // Note: this will reject the contents, but the error may be caught before it shows in the JS console.
      throw new Error("Rejecting HTML that was not marked by the server as sanitized.");
    }
    return htmlText;
  },
});
IncludeFragmentElement.setCSPTrustedTypesPolicy(policy);

Note that:

• Only a single policy can be set, shared by all IncludeFragmentElement fetches.
• You should call setCSPTrustedTypesPolicy() ahead of any other load of include-fragment-element in your code.
  • If your policy itself requires asynchronous work to construct, you can also pass a Promise<TrustedTypePolicy>.
  • Pass null to remove the policy.
• Not all browsers support the trusted types API in JavaScript. You may want to use the recommended tinyfill to construct a policy without causing issues in other browsers.

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

Browsers without native custom element support require a polyfill. Legacy browsers require various other polyfills. See examples/index.html for details.

• Chrome
• Firefox
• Safari
• Microsoft Edge

Development

npm install
npm test

License

Distributed under the MIT license. See LICENSE for details.

include-fragment-element's Issues

Feature Request: Add `refetch`

We have some specific use cases for include-fragment where we want to re-fetch the content, such as include fragments with polling or a refresh button. Previously this was done with something like the following:

const url = el.getAttribute('src')
el.setAttribute('src', '')
el.setAttribute('src', url)

Unfortunately this approach is currently blocked by #90. Even if that is fixed, it would still be really nice if this was a feature with built in support. For example, it would be much nicer to be able to simple call el.refresh() or something along those lines.

URI Fragments

Where src="issue.html#title"

<body>
  <h1 id="title">Fragments</h1>
  <p>Other stuff</p>
</body>

The #title element is extracted from the response and replaces the element.

Mirrors media URI fragments.

CLI test suite is broken

$ make test
./node_modules/.bin/jshint *.js test/*.js
node ./node_modules/.bin/node-qunit-phantomjs ./test/test.html

Just hangs.

include-fragment-replaced triggered twice

Under some conditions, the 'include-fragment-replaced' and 'include-fragment-replace' events are triggered twice.

Fiddle: https://jsfiddle.net/36koL2mb/1/

Fiddle code:

<script type="module" src="https://unpkg.com/@github/include-fragment-element@latest?module"></script>
<include-fragment id="suggest-as-template" src="https://github.github.io/include-fragment-element/examples/pull.html">
  <p>'Loading...</p>
</include-fragment>

$('include-fragment').on('include-fragment-replaced', function () {
	console.log('hello');
})

In this example, "hello" is printed to the console twice, and it should only be triggered once, because the fragment is only replaced once. I do not know why this is happening. In other places it does seem to only trigger once.

Src can no longer be changed

In #79, a new #busy check was added to ensure we wait for the current fetch to complete before allowing another fetch to happen. Unfortunately #busy is never set back to false, so only a single fetch can ever be made per include fragment. We should be able to reliably change src and have the contents update accordingly

Rename?

I never really loved the name.

Word brainstorm.

• include
• fragment
• partial
• content
• render
• template
• subresource

http://en.wikipedia.org/wiki/Edge_Side_Includes, http://en.wikipedia.org/wiki/Server_Side_Includes, Client Side Includes???

Fetch immediately on src property assignment

Content should be fetch immediately before the element is attached to any document. The replacement step can be deferred till the attach hook is fired.

Depends on #3 to hook into src changes.
Depends on #2 to have a promise to cache.

Prior art

img = document.createElement('img')
img.src = "preload-this.png"
// later...
document.body.appendChild(img)

loadstart sometimes doesn't fire until the load is complete

include-fragment fires its events on a 0-delay timer. At least in Safari, this sometimes results in events not firing until after the load has already completed. I believe this is happening in the case where the load is served from the browser's cache; in that case the load completes so quickly that the timer for firing loadstart hasn't run yet.

SEO impact of the client-side include

since the readme describes the SSI or ESI related stuff, it would be great if it could also mention in a short sentence whether this solution has SEO impact.

will the contents, which gets lazy-loaded by this component be visible to a SEO robot?

Add progress events

• loadstart http://www.w3.org/html/wg/drafts/html/master/index.html#event-loadstart
• loadend http://www.w3.org/html/wg/drafts/html/master/index.html#event-loadend
• load http://www.w3.org/html/wg/drafts/html/master/index.html#event-load
• error http://www.w3.org/html/wg/drafts/html/master/index.html#event-error

Steps for img progress events are pretty clear - http://www.w3.org/html/wg/drafts/html/master/embedded-content.html#the-img-element

Consider not bubbling error event

It seems like error events should not be bubbled. Might interfere with window.onerror.

include-fragment-element/include-fragment-element.js

Line 135 in 9cdc701

fire('error', self);

https://www.w3.org/TR/DOM-Level-3-Events/#event-type-error

---

To: @mislav
CC: @github/js

Support additional fetch-parameters

it would be great if we could define additional parameters for the fetch-api, e.g. in our case we would love to have "X-Requested-With": "XMLHttpRequest" headers, or a different caching strategy.

Publish on webcomponents.org

https://beta.webcomponents.org/

---

CC: @github/js
Requested by @notwaldorf

Re-execute js?

If my fragment have JS code
How re-execute him?

<include-fragment> and Screen Reader Accessibility

I have the following issue.
I'm a totally blind software engineer and use a screen reader. Obviously, in our company we use Github for managing code. I'm used to review pull requests without any hassles, but recently that has started.
In our company larger pull requests are common (that's debatable whether it's good or bad, but it is as it is). I had to review a pull request containing 54 changed files. With my screen reader I could see only 18 first diffs rendered, then there was nothing at all, nada. The remaining diffs were however visible on screen for sighted people.
When inspecting the source code of the page in my browser, I saw that the first 18 diff tables are indeed rendered correctly, then there is an <include-fragment src="..."> element with a link to all of the remaining diffs. I tried to open that link as a separate web page, but of course I had no luck in seeing comments properly and so on.

My question is: Is it incorrect usage pattern of this library on github or is this library inaccessible in its nature?
this is a huge show stopper for my work. Github has always been an extremely accessible and friendly network to work with, but now it's really disappointing.

Calling `load()` on a lazy loaded element doesn't work

I've discovered a bug where calling load() manually on a lazy loaded breaks the element. It triggers the request, but then when the element becomes visible the content isn't replaced. Example below from the examples page:

bug.mov