smart-html-elements

Base Element - Documentation | www.HtmlElements.com

Introduction

The Smart.BaseElement class extends the native HTMLElement class adding additional features like Data Binding, Cross-Browser and Device compatible event system, Localization, Property Change notifications, Typed properties, Templates, Lifecycle callbacks and additional useful properties, methods and events.

Basic Custom Element definition

See the Pen SMART HTML ELEMENTS by SmartHTMLElements (@SmartHTMLElements) on CodePen.

More Complex Custom Element definition

See the Pen SMART HTML ELEMENTS by Boyko Markov (@boyko-markov) on CodePen.

A basic button element definition looks like this:

	Smart('smart-button', class Button extends Smart.ContentElement {  
	 // Button's properties.  
	 static get properties() {  
	   return {  
		 'value': {  
		   type: 'string'  
		 },  
		 'name': {  
		   type: 'string'  
		 },  
		 'type': {  
		   type: 'string'  
		 },  
		 'clickMode': {  
		   allowedValues: ['hover', 'press', 'release'],  
		   type: 'string',  
		   value: 'release'  
		 }  
	   };  
	 }  
	 /** Button's template. */  
	 template() {  
	   return '<button class=\'smart-button\' inner-h-t-m-l=\'[[innerHTML]]\' id=\'button\' type=\'[[type]]\' name=\'[[name]]\' value=\'[[value]]\' disabled=\'[[disabled]]\' role=\'button\'></button>';  
	 }  
	 static get listeners() {  
	   return {  
		 'button.mousedown': '_mouseDownHandler',  
		 'button.mouseenter': '_mouseEnterHandler',  
		 'button.click': '_clickHandler'  
	   };  
	 }  
	 _clickHandler(event) {  
	   const that = this;  
	   if (that.clickMode !== 'release') {  
		 event.preventDefault();  
		 event.stopPropagation();  
	   }  
	 }  
	 _mouseDownHandler() {  
	   const that = this;  
	   if (that.clickMode === 'press') {  
		 that.$.fireEvent('click');  
	   }  
	 }  
	 _mouseEnterHandler() {  
	   const that = this;  
	   if (that.clickMode === 'hover') {  
		 that.$.fireEvent('click');  
	   }  
	 }  
	 });

The base custom element class is called BaseElement and is accessible through Smart.BaseElement. Most elements derive from Smart.BaseElement. Smart.ContentElement extends the Smart.BaseElement by adding content and innerHTML properties to it. It is useful when you need to append a child element by setting a single property.

Register a Custom Element

To register a custom element, use the Smart function and pass in the element’s tag name and class. By specification, the custom element’s name must contain a dash (-). The library internally checks whether Custom Elements v1 is supported and uses its lifecycle callbacks and customElements.define. Otherwise, it uses document.registerElement and the v0 lifecycle callbacks. To use custom elements, you will need a browser which natively supports Custom Elements or you will need to load polyfills such as webcomponentsjs.

Resources:

https://developer.mozilla.org/en-US/docs/Web/Web_Components
https://developers.google.com/web/fundamentals/getting-started/primers/customelements
http://webcomponents.org/
webcomponentsjs polyfill:
- https://github.com/webcomponents/webcomponentsjs
- https://www.npmjs.com/package/@webcomponents/webcomponentsjs
  - The files webcomponents-lite.js and webcomponents-loader.js have to be referenced (in this order).

Lifecycle callbacks

created - Called when the element has been created, but before property values are set and local DOM is initialized.
Use for one-time set-up before property values are set.
attached - Called after the element is attached to the document. Can be called multiple times during the lifetime of an element.
ready - Called when the element is ready. Use for one-time configuration of your element.
detached - Called after the element is detached from the document. Can be called multiple times during the lifetime of an element.

Properties

To add properties on your custom element, you can use the properties object. All properties part of the properties object are automatically serialized and deserialized by the element and can also be set through attributes by using the dash(-) syntax in the HTML markup. Each property can have the following members:

reflectToAttribute - Type: Boolean. Set to true to cause the corresponding attribute to be set on the host node when the property value changes. If the property value is Boolean, the attribute is created as a standard HTML boolean attribute (set if true, not set if false). For other property types, the attribute value is a string representation of the property value. The default value of this member is true.
defaultReflectToAttribute - Type: Boolean. Set to true when we want a default attribute value to be set on the host node.
readOnly - Type: Boolean. Determines whether the property is readyonly. if true the property can’t be set by the user.
type - Type: String. Used for deserializing from an attribute.
- any - allows assigning any value to a property.
- string - allows assigning a String to a property.
- string? - allows assigning a ‘String’ or null to a property.
- boolean or bool - allows assigning a Boolean to a property.
- boolean? or bool? - allows assigning a ‘Boolean’ or null to a property.
- number or float - allows assigning a ‘Number’ to a property.
- number? or float? - allows assigning a ‘Number’ or null to a property.
- int or integer - allows assigning an ‘Integer’ to a property.
- int? or integer? - allows assigning an ‘Integer’ or null to a property.
- date - allows assigning a ‘Date’ to a property.
- date? - allows assigning a ‘Date’ or null to a property.
- array - allows assigning an ‘Array’ to a property.
- object - allows assigning an ‘Object’ to a property.
allowedValues - Type: Array. Used for defining a set of values which are allowed to be set. For other values, an exception is thrown.
notify - Type: Boolean. Determines whether an event is raised when a property is changed. The event name is: property’s attribute name + - ‘changed’. Example: Property’s name is ‘clickMode’, the event’s name will be ‘click-mode-changed’.
Example:

	<!DOCTYPE html>  
	 <html lang="en">  
	 <head>  
	   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />  
	   <meta name="viewport" content="width=device-width, initial-scale=1" />  
	   <link rel="stylesheet" href="./../../source/styles/smart.base.css" type="text/css" />  
	   <link rel="stylesheet" href="../styles/demos.css" type="text/css" />  
	   <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.1.0/webcomponents-lite.js"></script>  
	   <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.1.0/webcomponents-loader.js"></script>  
	   <script type="text/javascript" src="./../../source/smartelement.js"></script>  
	   <script type="text/javascript" src="../../source/smartbutton.js"></script>  
	   <script type="text/javascript" src="../../source/smartscrollbar.js"></script>  
	   <script type="text/javascript" src="./../../source/smartlistbox.js"></script>  
	   <script type="text/javascript" src="./../../source/smartcheckbox.js"></script>  
	   <script type="text/javascript" src="./../../source/smartradiobutton.js"></script>  
	   <script>  
		 window.onload = function () {  
		   var list = document.getElementById('list');  
		   var data = [  
			 {  
			   label: "Andrew",  
			   value: 1,  
			   group: "A"  
			 },  
			 {  
			   label: "Natalia",  
			   value: 5,  
			   group: "B"  
			 },  
			 {  
			   label: "Michael",  
			   value: 4,  
			   group: "B"  
			 },  
			 {  
			   label: "Angel",  
			   value: 2,  
			   group: "A"  
			 },  
			 {  
			   label: "Hristo",  
			   value: 6,  
			   group: "C"  
			 },  
			 {  
			   label: "Peter",  
			   value: 3,  
			   group: "A"  
			 },  
			 {  
			   label: "Albert",  
			   value: 4,  
			   group: "A"  
			 },  
			 {  
			   label: "Boyko",  
			   value: 8,  
			   group: "A"  
			 },  
			 {  
			   label: "Dimitar",  
			   value: 9,  
			   group: "B"  
			 },  
			 {  
			   label: "George",  
			   value: 10,  
			   group: "C"  
			 }  
		   ];  
		   list.dataSource = data;  
		   list.addEventListener('disabled-changed', function (event) {  
			 if (event.target === list) {  
			   alert('disabled changed');  
			 }  
		   });  
		   document.getElementById("disabled").onclick = function () {  
			 list.disabled = !list.disabled;  
		   }  
		   list.properties['disabled'].notify = true;  
		 }  
	   </script>  
	 </head>  
	 <body>  
	   <smart-list-box style="float:left;" selection-mode="checkBox" id="list"></smart-list-box>  
	   <div style="float: left; margin-left:100px;">  
		 <smart-button style="width:auto;" id="disabled">Enable/Disable</smart-button>  
	   </div>  
	 </body>  
	 </html>

value - Default value for the property.
observer - Type: String. A name of a function called within the Element when the property is changed. The arguments passed to your observer are the property’s oldValue and newValue.
validator - Type: String. A name of a function called within the Element when the property is changing. The arguments passed to your validator are the property’s oldValue and newValue. The function returns the updated value. If it returns undefined, the newValue remains unchanged.

propertyChangedHandler(propertyName, oldValue, newValue) method is called when a property is changed by the user. This method is useful for updating the element when the user makes some changes.

The user may watch for property changes by using the element’s instance. watch(propertiesArray, propertyChangedCallback). The arguments passed to the propertyChangedCallback function are propertyName, oldValue, newValue.

Template

The template object determines the internal HTML structure of the Element. Within that structure you can data bind properties by using two-way or one-way data binding.

	 template() {  
		 return '<button class=\'smart-button\' inner-h-t-m-l=\'[[innerHTML]]\' id=\'button\' type=\'[[type]]\' name=\'[[name]]\' value=\'[[value]]\' disabled=\'[[disabled]]\' role=\'button\'></button>';  
	   }

Text surrounded by double curly bracket ({{ }}) or double square bracket ([[ ]]) delimiters. Identifies the host element’s property being bound.

Double-curly brackets (}) is used for two-way data flow.
Double square brackets ([[ ]]) is used for one-way downward from host element to target element data flow.

Two-way binding to a Native HTML element.

nativeElementProperty="{{hostElementProperty::nativeElementEvent}}"

	Smart('my-element', class MyElement extends Smart.BaseElement {  
	   static get properties() {  
		 return {  
		   'check': {  
			 type: 'boolean'  
		   }  
		 };  
	   }  
	   template() {  
		 return '<div><input type="checkbox" checked="{{check::change}}" /></div>';  
	   }  
	 });

Full example:

	<!DOCTYPE html>  
	 <html lang="en">  
	 <head>  
	   <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />  
	   <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.1.0/webcomponents-lite.js"></script>  
	   <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.1.0/webcomponents-loader.js"></script>  
	   <script type="text/javascript" src="../../source/smartelement.js"></script>  
	   <script type="text/javascript" src="../../source/myelement.js"></script>  
		<script>  
		  window.onload = function () {  
			var myElement = document.querySelector('my-element');  
			myElement.onchange = function () {  
			  console.log(myElement.check);  
			}  
		  }  
	   </script>  
	 </head>  
	 <body>  
	   <my-element></my-element>  
	 </body>  
	 </html>

Content insertion point determines where the HTML elements which are within the custom element's html body, go during the initialization. By default that is the Custom Element itself, but you can specify a custom content insertion point. You can define a content tag within the template's structure as in the below example:

	template() {  
	   return `<div>  
		 <svg width="100%" height="100%" viewPort="0 0 100 100" viewBox="0 0 100 100">  
		   <circle id="value" class ="smart-value" r="50" cx="50" cy="50" transform="rotate(270 50 50)"></circle>  
		 </svg>  
		 <div class="smart-label-container"><content></content><div id="label" class="smart-label"></div></div>  
	   </div>`;  
	 }

After the template is parsed, each element of the HTML Structure is accessible via its id and the $ symbol. Note the checkboxInput element in the below example:

	 * CheckBox custom element.  
	 */  
	 Smart('smart-checkbox', class CheckBox extends Smart.ToggleButton {  
	   // CheckBox's properties.  
	   static get properties() {  
		 return {  
		   'enableContainerClick': {  
			 value: true,  
			 type: 'boolean'  
		   }  
		 };  
	   }  
	   /** Checkbox's Html template. */  
	   template() {  
		 return `<div id='container' class='smart-container'>  
			  <div id='checkboxAnimation' class ='smart-animation'></div>  
			  <span id='checkboxInput' class ='smart-input'></span>  
			  <span id='checkboxLabel' inner-h-t-m-l='[[innerHTML]]' class ='smart-label'><content></content></span>  
			 </div>`;  
	   }  
	   static get listeners() {  
		 return {  
		   'click': '_clickHandler'  
		 };  
	   }  
	   /** Called when the element is ready. Used for one-time configuration of the Checkbox. */  
	   ready() {  
	   }  
	   /** Changes the check state wneh widget container is clicked. */  
	   _clickHandler(event) {  
		 const that = this;  
		 if (that.disabled) {  
		   return;  
		 }  
		 const isInputClicked = event.target === that.$.checkboxInput;  
		 if ((that.enableContainerClick === true && !isInputClicked) || isInputClicked) {  
		   that._changeCheckState('pointer');  
		   that.focus();  
		 }  
	   }  
	 });

A set of utility functions is accessible throught the $ symbol. The syntax is element.$.The utilify functions are:

addClass(className) - adds a class or classes to the element separated by space.
removeClass(className) - removes a class or classes separated by space.
isNativeElement - returns true if the element is native HTML Element. Otherwise returns false.
fireEvent(eventType, detail, options) - fires a Custom Event.
- eventType - String. Determines the event’s type.
- detail - Object. Determines custom event object passed to the user.
- options - Object. Determines the event’s options like cancelable or bubbles. Read more on: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent
listen(eventType, handler) - adds an event listener to the element. A set of Mobile-friendly events are supported by default. By passing any of these event types: down, up, move, tap, taphold, swipeleft, swiperight, swipetop, swipebottom, you will be notified when the user taps, swipes or touches with finger or mouse the element. If you listen to the resize event, you will be notified whenever the element’s boundaries are changed.
unlisten(eventType) - removes event listener by type.
getAttributeValue(attributeName, type) - gets the attribute’s typed value.
setAttributeValue(attributeName, value, type) - sets the attribute’s value by using a typed value.

By invoking Smart.Utilities.Extend(element) you can extend any element with the above utility functions.

In order to add a custom utility class, you can use Smart.Utilities.Assign(classDefinition).

	Smart.Utilities.Assign('BaseNumericProcessor', class BaseNumericProcessor {  
	}

To access that class, you can use Smart.Utilities.BaseNumericProcessor.

Events

The listeners object allows you to add and map events to event handlers.

In the below example, the listeners object defines that a method called _clickHandler is called when the element is clicked. To listen to an event of an element from the template, you can use nodeId.eventName like checkboxInput.click:_clickHandler.

	 * CheckBox custom element.  
	 */  
	 Smart('smart-checkbox', class CheckBox extends Smart.ToggleButton {  
	   // CheckBox's properties.  
	   static get properties() {  
		 return {  
		   'enableContainerClick': {  
			 value: true,  
			 type: 'boolean'  
		   }  
		 };  
	   }  
	   /** Checkbox's Html template. */  
	   template() {  
		 return `<div id='container' class='smart-container'>  
			  <div id='checkboxAnimation' class ='smart-animation'></div>  
			  <span id='checkboxInput' class ='smart-input'></span>  
			  <span id='checkboxLabel' inner-h-t-m-l='[[innerHTML]]' class ='smart-label'><content></content></span>  
			 </div>`;  
	   }  
	   static get listeners() {  
		 return {  
		   'click': '_clickHandler'  
		 };  
	   }  
	   /** Called when the element is ready. Used for one-time configuration of the Checkbox. */  
	   ready() {  
	   }  
	   /** Changes the check state wneh widget container is clicked. */  
	   _clickHandler(event) {  
		 const that = this;  
		 if (that.disabled) {  
		   return;  
		 }  
		 const isInputClicked = event.target === that.$.checkboxInput;  
		 if ((that.enableContainerClick === true && !isInputClicked) || isInputClicked) {  
		   that._changeCheckState('pointer');  
		   that.focus();  
		 }  
	   }  
	 });

Binding to events within the Element’s template.

	 Smart('my-element', class MyElement extends Smart.BaseElement {  
	   static get properties() {  
		 return {  
		   'check': {  
			 type: 'boolean'  
		   }  
		 };  
	   }  
	   template() {  
		 return '<div><input id="checkbox" (change)="_changeHandler" type="checkbox" checked="{{check::change}}" /></div>';  
	   }  
	   _changeHandler() {  
		 alert('Checkbox State Changed');  
	   }  
	 });

By using the utility functions described in the previous section, you can dynamically add and remove event listeners.

Modules

To add a missing feature or override a feature of a Custom Element, you can define a Module. The module represents a javascript class. By defining its properties object, you can add new properties or override existing properties of the custom element. Methods defined within that class also extend or override custom element methods. The lifecycle callback functions usage is the same as in the element. To add a module to a custom element, you can use the addModule function. The owner element is accessible through a property called ownerElement.

	window.Smart.Elements.whenRegistered('smart-button', function (proto) {  
	   proto.addModule(ColorModule);  
	 });

Custom Module which adds a new color property to the smart-button custom element.

	 <!DOCTYPE html>  
	 <html lang="en">  
	 <head>  
	   <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />  
	   <link rel="stylesheet" href="../styles/demos.css" type="text/css" />  
	   <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.1.0/webcomponents-lite.js"></script>  
	   <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.1.0/webcomponents-loader.js"></script>  
	   <script type="text/javascript" src="../../source/smartelement.js"></script>  
	   <script type="text/javascript" src="../../source/smartbutton.js"></script>  
	   <script>  
		 class ColorModule {  
			static get properties() {  
			  const properties =  
			  {  
				'color': {  
				  value: 'red',  
				  type: 'string',  
				  observer: 'setColor'  
				}  
			  }  
			  return properties;  
			}  
		   attached() {  
		   }  
		   detached() {  
		   }  
		   created() {  
		   }  
		   ready() {  
			 this.ownerElement.$.button.style.color = this.color;  
		   }  
		   setColor(oldColor, color) {  
			 this.ownerElement.$.button.style.color = this.color;  
		   }  
		 }  
		 window.Smart.Elements.whenRegistered('smart-button', function (proto) {  
		   proto.addModule(ColorModule);  
		 });  
	   </script>  
	   <script>  
		 function clickMe(event) {  
		   let button = document.getElementById("button");  
		   button.color = 'green';  
		 }  
	   </script>  
	 </head>  
	 <body>  
	   <smart-button id="button" onclick="clickMe(event)">Click Me</smart-button>  
	 </body>  
	 </html>

Inheritance

You can create a new Custom Element which extends an existing one. When you call the Smart function, pass a class as a second argument which determines which element should be extended. All elements are registered within the Smart global namespace and are accessible through their class name.

The below example demonstrates how to create a new element called smart-repeat-button which extends the smart-button element.

	 * Repeat Button.  
	 */  
	 Smart('smart-repeat-button', class RepeatButton extends Smart.Button {  
	   // button's properties.  
	   static get properties() {  
		 return {  
		   'delay': {  
			 value: 50,  
			 type: 'number'  
		   },  
		   'initialDelay': {  
			 value: 150,  
			 type: 'number'  
		   }  
		 };  
	   }  
	   static get listeners() {  
		 return {  
		   'button.mousedown': '_startRepeat',  
		   'button.mouseenter': '_updateInBoundsFlag',  
		   'button.mouseleave': '_updateInBoundsFlag',  
		   'document.mouseup': '_stopRepeat'  
		 };  
	   }  
	   _updateInBoundsFlag(event) {  
		 const that = this;  
		 that._isPointerInBounds = true;  
		 if (event.type === 'mouseleave') {  
		   that._isPointerInBounds = false;  
		 }  
	   }  
	   _startRepeat(event) {  
		 const that = this;  
		 if (!that._initialTimer) {  
		   that._initialTimer = setTimeout(function () {  
			 that._repeatTimer = setInterval(() => {  
			   if (that._isPointerInBounds) {  
				 const buttons = ('buttons' in event) ? event.buttons : event.which;  
				 that.$.fireEvent('click', { buttons: buttons });  
			   }  
			 }, that.delay);  
			 that._initialTimer = null;  
		   }, that.initialDelay);  
		 }  
	   }  
	   _stopRepeat() {  
		 const that = this;  
		 if (that._repeatTimer) {  
		   clearInterval(that._repeatTimer);  
		   that._repeatTimer = null;  
		 }  
		 if (that._initialTimer) {  
		   clearTimeout(that._initialTimer);  
		   that._initialTimer = null;  
		 }  
	   }  
	 });

Working with Transpiled ES5 Files

When using ES5/minified files, you would also need to include a reference to the file native-shim.js (it can be found alongside smartelement.js and smartelement-polyfills.js in the @smartelements/smart-element npm package).

smart.element.js and any custom element scripts referenced in a page (or an automated test) have to be either the original, ES6 (ES.Next), files or transpiled ES5/minified files. The ES5/minified smart.element.js is not compatible with ES6 custom elements.

Complex Components

Core Components