Custom Elements Documentation

Custom Elements

Custom Elements is a capability for creating your own custom HTML elements. They can have their own scripted behavior and CSS styling. They are a part of web components, but can also be used by themselves. jQWidgets Custom Elements are based on the Custom Elements technology and can be used as native HTML Elements. For example, to put a jqxButton on your web page, you have to add a tag, called jqx-button - <jqx-button>Click Me</jqx-button>


Prerequisites

  • WebComponents polyfills - custom elements are still not widely supported by all web browsers and you may need to use a polyfill.
  • Browser Support for jQWidgets Custom Elements: Internet Explorer 11, Edge, Chrome(latest), Firefox(latest), Safari(latest)

Required files:

  1. webcomponents-lite.min.js
  2. jqxcore.js
  3. jqxcore.elements.js
  4. (Elements script files)

Getting Started

  • The first step is to create html page and add links to the javascript files and css dependencies to your project. For example, the jqxBarGauge custom element requires the following files: 

    <script type="text/javascript" src="../scripts/webcomponents-lite.min.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxcore.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxdraw.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxcore.elements.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxbargauge.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxtooltip.js"></script>
  • The next step is to add the html element within the body of the html page. 
    <jqx-bar-gauge settings="elementSettings"></jqx-bar-gauge>
  • The last step is to initialize the element settings. 
    <script type="text/javascript">
    JQXElements.settings["elementSettings"] =
    {
        colorScheme: "scheme02", values: [102, 115, 130, 137], max: 150,
        tooltip: {
            visible: true,
            formatFunction: function (value)
            {
                var realVal = parseInt(value);
                return ('Year: 2016<br/>Price Index:' + realVal);
            }
        }
    }
    </script>

Invoking methods

To invoke a method, get the element's instance and use the method's name. 
<script>
window.onload = function () {
    var barGauge = document.querySelector('jqx-bar-gauge');
    barGauge.val([115,130,140]);
}
</script>
To get the result of a function after calling it, you can use the following syntax: 
<script>
window.onload = function () {
    var barGauge = document.querySelector('jqx-bar-gauge');
    var values = barGauge.val();
}
</script>

Set and get properties

To set a property(option), you need to pass the property name and value(s) in the jqxBarGauge's instance. 
<script>
window.onload = function () {
    var barGauge = document.querySelector('jqx-bar-gauge');
    barGauge.values = [115,130,140];
}
</script>
You can also set properties of HTML Elements by using Attributes. Traditionally, attributes are used to set the initial state of an element. Properties with camelCase naming have dash-based attributes. For example: A property "dataSource" will have an attribute called "data-source". To get a property(option), you need to use the property name along with the jqxBarGauge's instance. 
<script>
window.onload = function () {
    var barGauge = document.querySelector('jqx-bar-gauge');
    var values = barGauge.values;
}
</script>

Events

Event binding can be defined in the HTML as an attribute. The syntax is: 'on-' and the event's name. Event Names with camelCase naming have dash-based attributes. The attribute's value is the event handler's name. The example code below demonstrates how to bind to the valueChanged event of jqxBarGauge. 

<script>
window.onload = function () {
    var barGauge = document.querySelector('jqx-bar-gauge');
    barGauge.addEventListener('valueChanged', function(event){
        // Your code here
    });
}
</script>

Events example:

<!DOCTYPE html>
<html lang="en">
<head>
    <title id='Description'>BarGauge Custom Element</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="viewport" content="width=device-width, initial-scale=1 maximum-scale=1 minimum-scale=1" />
    <link rel="stylesheet" href="../jqwidgets/styles/jqx.base.css" type="text/css" />
    <script type="text/javascript" src="../scripts/webcomponents-lite.min.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxcore.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxdraw.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxcore.elements.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxbargauge.js"></script>
    <script type="text/javascript" src="../jqwidgets/jqxtooltip.js"></script>
    <script type="text/javascript">     
	var barGaugeValues = [11, 22, 33, 55, 88, 143];
	 
	JQXElements.settings["barGaugeSettings"] =
	{
		values:"values",width:600,height:600,max:150
	}
	window.onload = function() {
		document.querySelector("jqx-bar-gauge").addEventListener("valueChanged", function(event) {
			// Your code here.
		});
	};
    </script>
</head>
<body>
    <jqx-bar-gauge settings="barGaugeSettings"></jqx-bar-gauge>
</body>
</html>

Example

<!DOCTYPE html>
<html lang="en">
<head>
    <title id='Description'>BarGauge Custom Element Demo</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="viewport" content="width=device-width, initial-scale=1 maximum-scale=1 minimum-scale=1" />
    <link rel="stylesheet" href="../../jqwidgets/styles/jqx.base.css" type="text/css" />
    <link rel="stylesheet" href="../../styles/demos.css" type="text/css" />
    <script type="text/javascript" src="../../scripts/webcomponents-lite.min.js"></script>
    <script type="text/javascript" src="../../jqwidgets/jqxcore.js"></script>
    <script type="text/javascript" src="../../jqwidgets/jqxdraw.js"></script>
    <script type="text/javascript" src="../../jqwidgets/jqxcore.elements.js"></script>
    <script type="text/javascript" src="../../jqwidgets/jqxbargauge.js"></script>
    <script type="text/javascript" src="../../jqwidgets/jqxtooltip.js"></script>
    <script type="text/javascript">     
        JQXElements.settings["barGaugeSettings"] =
        {
            colorScheme: "scheme02", values: [102, 115, 130, 137], max: 150,
            tooltip: {
                visible: true, formatFunction: function (value) {
                    var realVal = parseInt(value);
                    return ('Year: 2016<br/>Price Index:' + realVal);
                }
            }
        }
    </script>
</head>
<body>
    <jqx-bar-gauge settings="barGaugeSettings"></jqx-bar-gauge>
</body>
</html>