link-import! AMD plugin for loading any WebComponents locally or over CDN
as AMD dependencies list and implementation of WebComponent via AMD define()
The code sniplet for AMD configuration sample from HTML page which uses Vaadin & Polymer Elements and custom af-branches WebComponent:
The af-branches WebComponent is using AMD define():
The require() which immediately follows define() is needed to enforce WebComponent registration.
Why AMD for WebComponent?
AMD is a module loader which allows to switch module location just by config and does not require any transpilation. I.e. you will be working in browser without any source mapping making it a IDE for editing and debugging on native level.
Why not alternatives?
- ES6 class imports does not have configuration for switching the path to dependencies.
- Transpiling is the way around missing config API in ES6, It is the source substitution on imports strings or even switching the source to runtime loader like AMD or System JS. WebPack, bower, etc are the samples.
In all work around the sources are moved into compiled bundle or generated in runtime, leaving developer to deal with extra complexity of mapping to original sources.
Unlike work around AMD stands for KISS principle during development, still permitting the transpiling and bundling options. With HTTP2 and gzip compressing by web server the bundling is not actual anymore.
stripping comments in source. The author's opinion the code should be readable
by developer and structured in a way to make comments unnecessary. The complimentary
comments and docs should be served in project documentation like this one rather
embedded into code.
There are some solutions which allow to outsource the documentation to wiki like ApiFusion. The source parsing and IDE integration are in progress there.
There is only one file
link-import.js you need.
You could pull it from NPM by
npm install --save link-import or simply copy from github into your project.
Then use as dependency prefix. For example the following link
Since it is too verbose it is advised to make an alias in AMD config
aliases: [ [ "link-import" , "af/ui/AMD/link-import" ]...
which shorten it to
Further aliasing and package definitions will allow to trim the dependency string
to bare minimum
(see config sample in intro)
link-import! prefix is resolved when
onload event is fired.
The WebComponent HTML loading is not necessary a final stage as AMD could be still
in loading progress. To assure the WebComponent is completely ready to use, append
|whenDefined to its URL:
af-branches is implemented with AMD, it will wait for dependencies resolving
and registering WebComponent, finally notifying the browser page over
!whenDefined suffix will resolve
the module on this event.
The resolved value will be a module value returned by AMD define callback.
test-element it is
TestElement class which could be used for element
new operator or as a parent for another class.
AMD resolved value
The module returns the tag name guessed out of HTML name.
rundemo.sh. It will open
- This project
test-componentdemo page on CDN
- For now it is tested against Dojo Toolkit 1.x AMD loader.
- RequireJS seems does not support the named define() in SCRIPT tag resulting in not invoking the callback, i.e. web component defined in HTML via RequireJS define implementation will not be instantiated. Absence of errors and console warnings preventing discover the cause. We are looking for help in following the issue and fix for RequireJS.
- Please create the ticket if your AMD environment does not support define() in HTML script section. Or upvote if ticket already created in "add reaction" smile button next to ticket title.
- IE does not support ES6 syntax which this plugin is written in.
test/demo/index.html and run in browser
( IntelliJ IDEA allows to "open in browser" opened html, ALT-F2 on Windows)
Multi-browser test. Prepare project and run test by
Keep in mind the
polymer test by default will run the test on all registered
browsers in your OS.
-l key allows to define the browser to test against.
It is also quite slow and looks like frozen, to see the progress use:
polymer test --verbose -l chrome