@hapiness/custom-elements-loader
CUSTOM-ELEMENTS-LOADER
This module exposes a factory to use ElementsLoaderService inside JavaScript's applications like React.js
, Vue.js
or just standalone
.
THIS MODULE IS ONLY USED IN JiT (Just-in-Time) MODE AND THE BUILD WON'T BE THE MOST OPTIMIZED - TO HAVE THE BEST WAY AND THE BEST OPTIMIZED CUSTOM ELEMENTS INTEGRATION WITH AoT (Ahead-of-Time) MODE, CHECK HERE
DON'T USE THIS MODULE FOR ANGULAR APPLICATION
Installation
$ yarn add @hapiness/custom-elements-loader or $ npm install --save @hapiness/custom-elements-loader
All required dependencies will be automatically installed : @angular/animations
, @angular/common
, @angular/core
, @angular/compiler
, @angular/elements
, @angular/platform-browser
, @angular/platform-browser-dynamic
, @hapiness/ng-elements-loader
, @webcomponents/webcomponentsjs
, core-js
, document-register-element
, rxjs
and zone.js
.
If your custom element module must have more dependencies, you must install them by yourself
Usage
Before to use ElementsLoader
exposed by @hapiness/custom-elements-loader
, you must create your own custom-elements
modules.
To create a new library with Angular-CLI
, follow this guide.
1) made-with-love custom element
- Component
This component will be the final custom-element
interpreted in your browser.
projects/made-with-love/src/lib/made-with-love.component.ts:
;
Note: Your component must have encapsulation equals to ViewEncapsulation.ShadowDom
if you want to have shadowdomv1 support else you can delete this line to have original support.
projects/made-with-love/src/lib/made-with-love.component.html:
{{ name }} Made with ♥ by {{ name }}
- Module
projects/made-with-love/src/lib/made-with-love.module.ts:
;;;;
Note: Your module must implement WithCustomElementComponent
interface exposed by @hapiness/ng-elements-loader
and, component must be declared inside entryComponents
and declaration
meta-data of NgModule
.
- Dependencies
The minimum package.json
file for your module is described below:
projects/made-with-love/package.json:
If your module has to have others dependencies not installed automatically by @hapiness/custom-elements-loader
like explained in installation, you must add them in dependencies section.
- Publish your module
Your custom-element
module is now ready to be used so you have to publish it before use it in your application.
2) made-with-love custom element in your JavaScript application
Create a JavaScript
application with your module and @hapiness/custom-elements-loader
in dependencies.
Install all dependencies
your module must have if not already installed.
- Application contains made-with-love custom element
We create a HTML
file with our custom element
inside.
index.html:
Web Component
main.js
file contains all JavaScript
elements to use ElementsLoader
and it's built with webpack.
main.ts
// POLYFILLS;; /** In browsers that don't support Custom Elements natively **/// import 'document-register-element'; /** You must add this if your application will be compiled in es5 because the specification requires developers use ES2015 classes to define Custom Elements **/ // import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter'; ;; ElementsLoader.loadContainingCustomElements .subscribeundefined, console.errore;
- Explanation
The creation of the custom element happens directly inside HTML
file with all attributes we want to display:
Loading of the component happens inside main.ts
file.
- Add required polyfills
;;
- Additional polyfills can be added if needed:
/** In browsers that don't support Custom Elements natively **/// import 'document-register-element'; /** You must add this if your application will be compiled in es5 because the specification requires developers use ES2015 classes to define Custom Elements **/ // import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter'; /** IE9, IE10 and IE11 requires all of the following polyfills. **/// import 'core-js/es6/symbol';// import 'core-js/es6/object';// import 'core-js/es6/function';// import 'core-js/es6/parse-int';// import 'core-js/es6/parse-float';// import 'core-js/es6/number';// import 'core-js/es6/math';// import 'core-js/es6/string';// import 'core-js/es6/date';// import 'core-js/es6/array';// import 'core-js/es6/regexp';// import 'core-js/es6/map';// import 'core-js/es6/weak-map';// import 'core-js/es6/set'; /** IE10 and IE11 requires the following for NgClass support on SVG elements */// import 'classlist.js'; // Run `npm install --save classlist.js`. /** IE10 and IE11 requires the following for the Reflect API. */// import 'core-js/es6/reflect'; /** * Web Animations `@angular/platform-browser/animations` * Only required if AnimationBuilder is used within the application and using IE/Edge or Safari. * Standard animation support in Angular DOES NOT require any polyfills (as of Angular 6.0). **/// import 'web-animations-js'; // Run `npm install --save web-animations-js`.
- We call
loadContainingCustomElements
method ofElementsLoader
from@hapiness/custom-elements-loader
. This method takes in parameterCustomElementModuleSelector
orCustomElementModuleSelector[]
from@hapiness/ng-elements-loader
.
Selector is the custom tag
of your custom element
and module is the Angular
module contains the component.
- Show the result
Launch your application and you will see your custom element
displayed inside your JavaScript
application:
Made with ♥ by Hapiness Framework
3) Custom element with custom event
In the previous component we have created only @Input
properties but sometimes, you'll want to emit event from your custom element
to the DOM
with @Ouput
properties.
- Custom element
Here an example of a component emits event to its parent:
projects/hello-world/src/lib/hello-world.component.ts:
;
projects/hello-world/src/lib/hello-world.component.html:
Say Hello with Event
- Use it in your application
To use it and receive event, you must do this:
index.html:
Web Component
We set a listener to catch sayHello
event and do what we want:
main.ts
// POLYFILLS;; /** In browsers that don't support Custom Elements natively **/// import 'document-register-element'; /** You must add this if your application will be compiled in es5 because the specification requires developers use ES2015 classes to define Custom Elements **/ // import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter'; ;; ElementsLoader.loadContainingCustomElements .subscribeundefined, console.errore; document.querySelector'hello-world'.addEventListener'sayHello',alertevent.detail;
Change History
- v7.2.0 (2018-11-27)
Angular v7.1.0+
- Add
ElementsLoaderService.registerContainingCustomElements()
method to be used for AoT compiler ElementsLoaderService.loadContainingCustomElements()
method must be used only for JiT compiler- Explain how to create an optimized
webcomponent
bundle with this tutorial - Documentation
- v7.1.0 (2018-11-09)
Angular v7.0.3+
document-register-elements v1.13.1
latest version of thepolyfill
only require if your browser doesn't supportcustomElement
@webcomponents/webcomponentsjs v2.1.3
to fix issue withes5
compilation outsideAngular
application like explain here- Allow custom elements registration in browser even if tag isn't yet present in the
DOM
like this, it can be created or loaded asynchronously after registration - Documentation
- v7.0.0 (2018-11-02)
Angular v7.0.2+
- Documentation
- v6.4.2 (2018-10-18)
- v6.4.1 (2018-09-26)
- Fix version to
Angular v6.1.7
to avoid the bug reported in this issue - Documentation
- Fix version to
- v6.4.0 (2018-07-26)
Angular v6.1.0+
- Documentation
Maintainers
Julien Fauville | Antoine Gomez | Sébastien Ritz | Nicolas Jessel |
License
Copyright (c) 2018 Hapiness Licensed under the MIT license.