{"id":13656942,"url":"https://github.com/gustafnk/h-include","last_synced_at":"2025-04-07T10:19:24.745Z","repository":{"id":46306496,"uuid":"57243705","full_name":"gustafnk/h-include","owner":"gustafnk","description":"Declarative client-side inclusion for the Web, using Custom Elements V1","archived":false,"fork":false,"pushed_at":"2024-09-10T20:18:45.000Z","size":511,"stargazers_count":251,"open_issues_count":3,"forks_count":18,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-31T09:03:15.560Z","etag":null,"topics":["webcomponents"],"latest_commit_sha":null,"homepage":"https://gustafnk.github.io/h-include/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gustafnk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-27T19:58:34.000Z","updated_at":"2025-03-02T04:50:52.000Z","dependencies_parsed_at":"2024-09-24T16:02:00.366Z","dependency_job_id":null,"html_url":"https://github.com/gustafnk/h-include","commit_stats":{"total_commits":268,"total_committers":19,"mean_commits":"14.105263157894736","dds":0.541044776119403,"last_synced_commit":"0fd97f999afaeeb863092b8dd30bea6628d91bda"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustafnk%2Fh-include","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustafnk%2Fh-include/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustafnk%2Fh-include/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustafnk%2Fh-include/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gustafnk","download_url":"https://codeload.github.com/gustafnk/h-include/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247631834,"owners_count":20970069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["webcomponents"],"created_at":"2024-08-02T05:00:34.680Z","updated_at":"2025-04-07T10:19:24.711Z","avatar_url":"https://github.com/gustafnk.png","language":"HTML","readme":"# h-include.js\n\nDeclarative client-side transclusion, using [Custom Elements V1](https://developers.google.com/web/fundamentals/web-components/customelements). Perfect for [Microfrontend architectures](https://micro-frontends.org/), in combination with server-side transclusion technologies like [Edge-Side Includes](https://en.wikipedia.org/wiki/Edge_Side_Includes).\n\nBased on [hinclude.js](https://github.com/mnot/hinclude) by [@mnot](https://github.com/mnot/).\n\n*Breaking changes in version 4.0.0*:\n\nRename `alt` attribute to `when-false-src` to support future feature for error handling.\n\n*Breaking changes in version 3.0.0*:\n\n- Because h-include is now using Custom Elements V1, we recommend that you update your polyfill (i.e. [document-register-element](https://github.com/WebReflection/document-register-element)) to the latest version.\n- If you have created your own custom elements that inherit from h-include, they too need to be based on Custom Elements V1. See [EXTENDING.md](EXTENDING.md) for an example how to extend h-include.\n- The `navigate` attribute is broken out into the separate element `\u003ch-include-navigate\u003e`, located in `lib/h-include-extensions.js`.\n- Changes to @src attribute don't automatically refresh an h-include element anymore\n\n## Usage\n\nInclude an HTML resource like this:\n\n```\n\u003ch-include src=\"/url/to/fragment.html\"\u003e\u003c/h-include\u003e\n```\n\nEach `\u003ch-include\u003e` element will create an AJAX request to the URL and replace the `innerHTML` of the element with the response of the request.\n\nSee [the demo page](http://gustafnk.github.com/h-include/) for live examples.\n\n## Installation\n\nInstall using npm:\n\n```shell\n$ npm install h-include\n```\n\n## Rendering Mode\n\nBy default, each include is fetched in the background and the page is updated only when they all are available.\n\nThis is bounded by a timeout, by default 2500 ms. After the timeout,\nh-include will show what it has and keep on listening for the remaining responses.\n\nHowever, it's also possible to have responses from `\u003ch-include\u003e` elements become visible as they become available, by providing configuration:\n\n```\nHIncludeConfig = { mode: 'async' };\n```\n\nWhile this shows the included content quicker, it may be less visually smooth.\n\n## Custom Elements polyfill\n\nYou need to use a polyfill for enabling [W3C Custom Elements](http://w3c.github.io/webcomponents/spec/custom/) for browsers not supporting Custom Elements V1.\n\nWe recommend using [document-register-element](https://github.com/WebReflection/document-register-element) (5KB minified and gzipped) as the polyfill for [W3C Custom Elements](http://w3c.github.io/webcomponents/spec/custom/).\n\nExample:\n\n```\n\u003chead\u003e\n  \u003cscript\u003ethis.customElements||document.write('\u003cscript src=\"//unpkg.com/document-register-element\"\u003e\u003c\\x2fscript\u003e');\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"/path/to/h-include.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  ...\n  \u003ch-include src=\"\u003e\n  ...\n\u003c/body\u003e\n```\n\n## Extensions\n\nAdditional extensions are located in [`lib/h-include-extensions.js`](https://github.com/gustafnk/h-include/blob/master/lib/h-include-extensions.js) and have `lib/h-include.js` as a dependency:\n\n```\n\u003cscript type=\"text/javascript\" src=\"/lib/h-include.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"/lib/h-include-extensions.js\"\u003e\u003c/script\u003e\n```\n\nAll extensions inherit h-include's base behavior, when applicable.\n\nTo create your own elements that inherit from `\u003ch-include\u003e`, see [EXTENDING.md](EXTENDING.md).\n\nExample usage, in summary:\n\n| Resource fragments  | Content fragments  | Example |\n|---|---|---|\n| ESI | ESI | Short static pages |\n| ESI | h-include  | Dynamic web app with static content fragments (i.e. search) |\n| ESI | ESI + h‑include‑lazy | Pages with *homogeneous* lists, lazy loaded on scroll below the fold |\n| ESI + h‑import‑lazy | ESI + h‑include‑lazy | Pages with *heterogeneous* content, lazy loaded on scroll below the fold together with resource fragments |\n| h‑import | h‑include (etc) | Sites without access to ESI |\n\n### h-include-lazy\n\nOnly includes the HTML resource if the element is about to enter the viewport, by default 400 pixels margin, using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) (which needs to be polyfilled).\n\nAfter page load, elements in the DOM need to registered to the Intersection Observer:\n\n```\n\u003cscript src=\"https://polyfill.io/v2/polyfill.min.js?features=IntersectionObserver\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"/lib/h-include.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"/lib/h-include-extensions.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nwindow.addEventListener('load', function() {\n  HInclude.initLazyLoad();\n});\n\u003c/script\u003e\n```\n\nExample:\n\n```\n\u003ch-include-lazy src=\"fragment.html\"\u003e\u003c/h-include-lazy\u003e\n\n...\n\n\n\u003ch-include-lazy src=\"lazy-loaded-fragment.html\"\u003e\u003c/h-include-lazy\u003e\n```\n\nExample repo using plain h-include (without lazy) and the Intersection Observer API to pull in content on ‘in-view’ scroll interaction can be found [here](https://github.com/nicolasdelfino/iobserver-h-include).\n\n### h-import\n\nRequest an HTML resource and include all found script and stylesheet references.\n\nExample:\n\n```\n\u003ch-import src=\"resource-fragment.html\"\u003e\u003c/h-import\u003e\n```\n\nIf possible, use [Edge-Side Includes](https://en.wikipedia.org/wiki/Edge_Side_Includes) (or similar) to import statically loaded resource fragments, due to performance reasons.\n\nTo load resources, h-import and h-import-lazy call `HInclude.loadResources` with an array of urls to resources. By default, this method delegates the resource loadin to [loadjs](https://github.com/muicss/loadjs), which needs to be on the `window` object. However, `HInclude.loadResources` can be replaced with a loader of your choice.\n\n### h-import-lazy\n\nWhen lazy loading fragments, it might be the case that additional style and script resources need to be loaded as well. For example, think of a lazy loaded footer with rather specific styling. For these scenarios, use h-import-lazy.\n\nAfter page load, elements in the DOM need to registered to the Intersection Observer:\n\n```\n\u003cscript src=\"https://polyfill.io/v2/polyfill.min.js?features=IntersectionObserver\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"/lib/h-include.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"/lib/h-include-extensions.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nwindow.addEventListener('load', function() {\n  HInclude.initLazyLoad();\n});\n\u003c/script\u003e\n```\n\nExample:\n\n```\n\u003ch-include-lazy src=\"fragment.html\"\u003e\u003c/h-include-lazy\u003e\n\n...\n\n\n\u003ch-import-lazy src=\"lazy-loaded-resource-fragment.html\"\u003e\u003c/h-import-lazy\u003e\n```\n\n## h-include-navigate\n\nUse `\u003ch-include-navigate\u003e` to let link navigation events be captured by the element itself, which changes the `src` attribute and triggers a refresh.\n\nUse `target=\"_top\"` to let link inside `h-include` behave as a normal link.\n\n\n#### Helper function: HInclude.initLazyLoad\n\nBy default, the selector for `HInclude.initLazyLoad` is `'h-include-lazy, h-import-lazy'` and the Intersection Observer `rootMargin` and `threshold` default values are `400px 0px` and `0.01` respectively. These can be overridden:\n\n```\nHInclude.initLazyLoad('css style selector', {rootMargin: '200px 0', threshold: 0.2});\n```\n\n#### Helper function: HInclude.loadResources\n\nLoad an array of script and stylesheet resources (to be overridden).\n\n## Advanced usage\n\n### Conditional inclusion using when\n\nWhen offers a way of using a predicate for inclusion. It also features an optional `when-false-src` attribute that functions as the source of inclusion given that the predicate fails.\n\n```\n\u003ch-include src=\"logged-in.html\" when=\"org.project.predicateFunction\" when-false-src=\"log-in.html\"\u003e\u003c/h-include\u003e\n```\n\nThe method specified in the when attribute may be namespaced and needs to return true for the inclusion of the url specified in the src attribute to occur.\n\n### Request errors and alternative inclusion using alt\n\nThe alt attribute functions as an alternative source of inclusion should the url result in a request error.\n\n```\n\u003ch-include src=\"unavailable.html\" alt=\"alternative.html\"\u003e\u003c/h-include\u003e\n```\n\n### Refresh method\n\nRefresh an element by using the `refresh()` method:\n\n```js\nconst element = document.getElementsByTagName('h-include')[0];\nelement.refresh();\n```\n\n### Media queries\n\nUse media queries to have different fragments for different devices:\n\n```\n\u003ch-include media=\"screen and (max-width: 600px)\" src=\"small.html\"\u003e\u003c/h-include\u003e\n\u003ch-include media=\"screen and (min-width: 601px)\" src=\"large.html\"\u003e\u003c/h-include\u003e\n```\n\n`\u003ch-include\u003e` will not listen to changes to screen orientation or size.\n\n### Fragment extraction\n\nInclude an HTML resource and extract a fragment of the response by using a selector:\n\n```\n\u003ch-include src=\"...\" fragment=\".container\"\u003e\u003c/h-include\u003e\n```\n\n### XMLHttpRequest.withCredentials\n\nEnable [XMLHttpRequest.withCredentials](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials):\n```\n\u003ch-include src=\"...\" with-credentials\u003e\u003c/h-include\u003e\n```\n\n## Configuration\n\nSet buffered include timeout (default is `2500` ms):\n\n```js\nHIncludeConfig = { timeout: 10000 };\n```\n\nSet include mode to `async` (default is `buffered`):\n\n```js\nHIncludeConfig = { mode: 'async' };\n```\n\nThrow if caught in an infinite include loop (default is `false`):\n\n```js\nHIncludeConfig = { checkRecursion: true };\n```\n\nIf `checkRecursion` is `true`, h-include will traverse the DOM upwards to find another h-include element with the same src attribute, until the root node. This operation takes a few CPU cycles per h-include, which is why it's not enable by default.\n\n\n## Error Handling\n\nIf 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.\n\n## Browser support\n\nAll modern browsers and IE down to IE10 are supported. If you find something quirky, please file an issue.\n\n## HTTP/2 improves XHR performance\n\nBrowsers with HTTP/2 are [using HTTP/2 for xhr requests as well](http://stackoverflow.com/questions/32592258/do-current-xhr-implementations-take-advantage-of-http-2). So, if both the server and the current browser supports HTTP/2, all requests made with h-include will go through the same TCP connection, given that they have the same origin.\n\n## Bundler \n\n### Parcel\n\nWith this plugin, Parcel searches and optimizes all h-include tags\n[https://github.com/joserochadocarmo/parcel-plugin-h-include](https://github.com/joserochadocarmo/parcel-plugin-h-include)\n\n\n## FAQ\n\nPlease see the [FAQ](FAQ.md) for some frequently asked questions.\n\n","funding_links":[],"categories":["JavaScript","HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgustafnk%2Fh-include","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgustafnk%2Fh-include","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgustafnk%2Fh-include/lists"}