https://github.com/bahrus/xtal-pattern
Create single file html Polymer web components without HTML Import
https://github.com/bahrus/xtal-pattern
Last synced: 3 months ago
JSON representation
Create single file html Polymer web components without HTML Import
- Host: GitHub
- URL: https://github.com/bahrus/xtal-pattern
- Owner: bahrus
- License: mit
- Created: 2018-01-07T13:38:36.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-07-13T19:13:47.000Z (almost 6 years ago)
- Last Synced: 2025-01-31T23:05:11.307Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 93.8 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.webcomponents.org/element/bahrus/xtal-pattern)
# \
\ is a dependency free web component, though its mission is intimately tied with Polymer. And what is that mission? To create high level, application specific web components with as little fuss as possible. (More, detailed, ambitious goals are listed later in this document). In particular, webcomponents that are mostly markup, with very little script, compositions consisting of lower level web components glued together declaratively. Web components that are only used one time in a specific application / web site.
\ weighs 920B minified and gzip'd.
\, though it is markup centric, allows the javascript to be defined in the same file as the markup.
Although the current implementation is done using Polymer 2, the hope is that when Polymer 3 is released, this helper library will provide a nice counterpoint to the JavaScript-oriented direction Polymer 3 is moving towards.
# Defining a xtal-pattern based web component
Step 1:
To create a web component, create an html file, and give it a name matching the name of the component you wish to define, for example: my-component.html
Inside my-component.html, define some markup, for example:
```html
Hello, {{entity}}
```
Step 2:
To register this as a web component, use \ in the containing component markup:
```html
The component that is mine, which I possess the sole ownership, and which belongs to me.
```
The text inside the anchor tag is optional. It will display as a hyperlink until xtal-pattern has loaded enough content from my-component.html to display something.
xtal-pattern will autogenerate a Polymer web component with name "my-component." It will look for tokens of the form: {{xyz}} automatically declare a property with that name.
To specify specific settings for the property, use notation as demmonstrated below:
```html
{{entity|type:String, reflectToAttribute: true, observer:'onPropsChange', value: ''}}
```
Note that references to images, etc, within my-component.html will all be relative to the base url of the web site / page open in the browser.
Step 4.
Wait for the world to say hi back.
## Custom JavaScript
In the markup above, we defined an observer, "onPropsChange." Such observers, as well as computed properties and event handlers will need to be defined in a script tag between //{ and //}:
```html
//{
function onPropsChange(){
this.doStuff();
}
function ready(){
super.ready();
...
}
function connectedCallback(){
super.connectedCallback();
...
}
//}
```
### What are we trying to achieve here?
This, for now, is a bit of a research project. Things are likely to change rapidly, as I don't yet see my way to a completely satisfying solution. I'm trying to achieve something that is easy with iframes (maybe goal 2b is a stretch if there are lots of them on the page):
1) Allow the html file to serve not only as a web component but also as a standalone page.
2) Load the content a) progressively and b) quickly
3) Search engines can easily index the contents of the web component even with minimal JavaScript / webcomponent support.
4) Low learning curve
5) Be usable anywhere
I'm pretty sure to achieve goal 1) above, it will require help on the server (puppeteer, maybe?).
## Progressive enhancement
xtal-pattern provides a number of tricks to minimize boot up time.
1) The core file for xtal-pattern begins working importing the (default) content before the entiity of the code for the web component is downloaded.
2) The imported file can contain a section of "light children" to display while the web component loads.
Why would we want to do this?
Say you want to present a slide show "10 Lobotomies gone horribly wrong." You want the initial, particularly gruisome slide, to display immediately, in order to invite the user to become engaged, while waiting for the supporting files (e.g. Polymer, other case studies, and the slide / carousel logic) to download.
So say the markup looks like this:
```html
10 Lobotomies Gone Horribly Wrong!!!
```
For fastest results, we could include the top slide as a light child of \. But that could be complicated. Botched-lobotomies.html would need to have the other 9 of them (or possibly duplicate the first one as well).
and my-component.html looks like:
```html
light children go here
```
## Install the Polymer-CLI
First, make sure you have the [Polymer CLI](https://www.npmjs.com/package/polymer-cli) installed. Then run `polymer serve` to serve your element locally.
## Viewing Your Element
```
$ polymer serve
```
## Running Tests
```
$ polymer test
```
Your application is already set up to be tested via [web-component-tester](https://github.com/Polymer/web-component-tester). Run `polymer test` to run your application's test suite locally.