Overview

So before we start, what are we going to do? We are going to create a basic application, and in doing so, create things we need to help us develop, publish and maintain our application. We need to make the basic structure, which can be in any way you wish. this way is simple and clean, adapt it to your on needs.

• Install dependencies.
• Housekeeping (NPM package changes for running, building).
• Simple server for local development.
• Build file, for generating fallback bundles (IE). We also copy files for production to make it simple to deploy
• Hello World first application.

Whilst we do have a build process, when developing we run from root and develop in route. You can skip the build process if you do not want to support IE and are happy collating files for production (also removing babel/browserify stuff from package.json). You could also create a deploy script, just to copy files so you don't have to cherry pick NPM packages etc. For ease we combine the two, so we generate IE11 builds just incase, and copy files so when we deploy, we take the contents of a folder and push to production. We like to make things simple, building can be complex, modern browsers do not need builds anymore!

Installation

First of all we need to install Custom Web Components into your system or starter application. you can do this with NPM. You may also do this via downloading the project from GitHub, but this will mean havingto download all the dependencies manually too, so use NPM.

npm install custom-web-component --save
					

This will install custom web component and all dependencies at correct versions. Should you need to install all of them manually, you can opt for this command...

npm install custom-web-component \
@webcomponents/custom-elements @webcomponents/shadycss @webcomponents/webcomponentsjs \
es7-object-polyfill \
lit-html \
promise-polyfill \
reflect-constructor --save
					

Lets explain smoe of this. The web components stuff is polyfilling for the browser. Why polyfill? well this adds in missing standards the browsers are yet to adopt. We only polyfill and use those standards that are excepted and to be adopted; we just wan to use them now. As the browser upgrades they are dropped automatically by the browser. This approach means as browsers age, yur code improves due to native support. We then have some back filling of missing functionality, some written by us too, some just for IE11.

We also have development dependencies to add, these are to make development easier, to help build fall back bundles for old browsers and a way to run your code on a simple JS server; we will get to this in a moment. For now this will get us what we need. We will assume you have some level of familularity with NPM and JS/HTML at this point, if not we would suggest reading a bit on these topics.

Server File

We are going to create a server file, this will help us serve the files from our project. Why do we need to do this? Well you could just hit the local files directly from the browser, but this can mess with relative paths, default landing files too. We wan to be able to hit the root URL and serve the index.html page without the need for /index.html. Also if we want to do hash based routing, common in JS UI land for single page apps, we don't wnat to hash the index.html address, we want to hash the root address.

So we are going to create a real simple express server setup to basically just serve files (and index.html if root is accessed). This is only for development use and should not be used for deploying code in production. Express is good for this too, but requires more work and thought for this.

Example Express Server

// Config
var PORT = 8888;
var express = require('express');
var app = express();

// Start
app.use(express.static('./'));
app.listen(PORT);
console.log('Running on http://localhost:' + PORT);
					

Save this file in the application root folder, next to index.html, then you will be able to run this command through NPM to start the server from the CLI Once run, visit the address (with port number) to access the index.html file without the need to add /index.html.

npm start
					

Hello World

We are going to create out first application now. By using a single entry application custom web component, we create a simple application we can add to a static file with ease. In time you will see you can build whole single page applications from a single HTML file and a bucket of web components.

• Create a new file application bootstrap called index.mjs inside src - ./src/index.mjs
• Create a new folder called HelloWorld, inside src - ./src/HelloWorld
• Create a new file called hello-world.mjs inside HelloWorld - ./src/HelloWorld/hello-world.mjs
• Create a new file called index.html inside your web root - ./index.html

We use mjs files, these are modular javascript files. They load differently. the only JS files we have are the build/server files and the bundle generated from the build script. The first file is the bootstrap file, we use this to load in all application logic, from there all other files are pulled in via imports in the JS files. We add the bootstrap file to the index.html page in a bit to load the bootstrap file and all other dependencies automatically via ES6 imports (thi sis why IE needs a bundle, no module import support) The HelloWorld folder houses the HelloWorld application which also happens to be our main application. The hello-world.js file is our application. All other components will be used form this file or the children of this file.

Bootstrap File

import '../node_modules/reflect-constructor/reflect-constructor.js'; // for IE11 support
import './HelloWorld/hello-world.mjs'; // your application entry point

// optional... set your service worker file!
// if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js');

// optional... any runtime message to console
console.log('Powered by Custom Web Component');
					

This file loads an IE11 polyfill, then continues to pull in the application class. From here you can do other things too. Setup any service workers, configurations, polyfills and more to make the HTML work easier.

Application File

import { CustomHTMLElement, html } from "../node_modules/custom-web-component/index.js";

/**
 * HelloWorld
 * A sample Custom HTML Element, to be used in any system that is capable of outputting HTML
 * Build on Web Standards and polyfilled for legacy browsers, using a simple clean lite HTML template rendering called lit-html
 */
class HelloWorld extends CustomHTMLElement {

	/**
	* @public constructor()
	* Invoked when instantiation of class happens
	* NOTE: Call super() first!
	* NOTE: Declare local properties here... [this.__private, this._protected, this.public]
	* NOTE: Declarations and kick starts only... no business logic here!
	*/
	constructor() {
		super();

		this.foo = 'FOO!!';
		this.bar;
	}

	/**
	* template()
	* Return html TemplateResolver a list of observed properties, that will call propertyChanged() when mutated
	* @return {TemplateResult} Returns a HTML TemplateResult to be used for the basis of the elements DOM structure
	*/
	static template() {
		return html`
		<style>
			/* Style auto encapsulates in shadowDOM or shims for IE */
			:host { display: block; }
			
			div {
				display: block;
				padding: 20px;
				color: #222;
				background: #f5f2f0;
				border: 1px solid #ccc;
				border-radius: 3px;
			}

			button {
				border: none;
				background: #444;
				color: white;
				padding: 10px;
			}
		</style>

		<div>
			<p>
			<slot name="main">Default text if no slot for main</slot>
			<br />
			<strong>FOO:</strong> ${this.foo}
			<br />
			<strong>BAR:</strong> ${this.bar}
			<br />
			<slot name="footer">Default text if no slot for footer</slot>
			<button @click="${this._clicked.bind(this, 'something')}">Boo</button>
			</p>
		</div>
		`;
	}

	/**
	* @static @get observedProperties()
	* Return a list of observed properties, that will call propertyChanged() when mutated
	* @return {Array} List of properties that will promote the callback to be called on mutation
	*/
	static get observedProperties() { return ['foo', 'bar']; }

	/**
	* @public propertyChanged()
	* Invoked when an observed instantiated property has changed
	* @param {String} property The name of the property that changed
	* @param {*} oldValue The old value before the change
	* @param {*} newValue The new value after the change
	*/
	propertyChanged(property, oldValue, newValue) {
		console.log(this.tagName, 'propertyChanged', property, oldValue, newValue);

		this.updateTemplate();
	}

	/**
	* @static @get observedAttributes()
	* Return a list of observed attributes, that will call attributeChanged() when mutated
	* @return {Array} List of attributes that will promote the callback to be called on mutation
	*/
	static get observedAttributes() { return ['bar']; }

	/**
	* @public attributeChanged()
	* Invoked when an observed node attribute has changed
	* @param {String} attribute The name of the attribute that changed
	* @param {*} oldValue The old value before the change
	* @param {*} newValue The new value after the change
	*/
	attributeChanged(attribute, oldValue, newValue) {
		console.log(this.tagName, 'attributeChanged', attribute, oldValue, newValue);

		if (attribute === 'bar') this.bar = newValue;

		this.updateTemplate();
	}

	/**
	* @public connected()
	* Invoked when node is connected/added to the DOM
	*/
	connected() {
		console.log('connected');
	}

	/**
	* @public disconnected()
	* Invoked when node is disconnected/removed from the DOM
	*/
	disconnected() {
		console.log('disconnected');
	}

	/**
	* @public update() [parent class]
	* Update the view, pushing only changes for update in shadow DOM
	*/
	templateUpdated() {
		console.log(this.shadowRoot, this.tagName, 'updated');
	}

	_clicked(text, ev) {
		alert(text);
	}
}

customElements.define('hello-world', HelloWorld);
					

This is your main application file. here you can load whole user interfaces, perform authentication to back ends, configure message systems and much more. Now all we need to do is add an index.html file, and add our new web component to it. We can use it many times too in the HTML file!

Index HTML File

<!DOCTYPE html>
<html>
<head>
	<title>Boom!</title>
	<!-- Polyfill -->
	<script src="/node_modules/promise-polyfill/dist/polyfill.min.js"></script>
	<script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
	<!-- Bootstrap App -->
	<script type="module" src="./index.mjs"></script>
	<script nomodule src="./index.js"></script>
</head>
<body>
	<h1>Example View</h1>
	<p>Show a component in action below...</p>
	<hello-world bar="bar!">
		<p slot="main">Hello</p>
		<p slot="footer">World</p>
	</hello-world>
	<p>We have pre built components, npm install razilocomponents (with an 's';)</p>
</body>
</html>
					

Thats it... We may now start your server, and see your web component in action. Once you are happy, run a build, copy the files form your build folder to your production environment.