3.3. Working with WebComponent

GUI Composer Component library v3 has been re-written from scratch. Based on the feedback from GCv2, there are a number of signification improvements made to the library such as

  • Utilized standard WebComponent technology, migrated away from the legacy Polymer library

  • All core component development is done with Typescript and JSX, greatly reducing runtime errors and code maintenance effort.

  • Adopted StencilJS framework to generate WebComponent

  • GCv3 widget library shares the same base widget library as ti.com

  • Reduced startup time of an application

    • Merged widgets with common functionality together to reduce number of widget to load

    • Bundle application with Rollup/Webpack before publishing to the Gallery (on the road map)

  • Improved theming support for widgets, application can provide custom theme file in addition to the built-in themes

WebComponent in general can be mutated in the following ways, with HTML markup, Javascript, or CSS stylesheet

  • Setting an attribute and/or property

  • Calling a method to perform an action

  • Setting a CSS property to change the look and feel of the component

Each WebComponent contains a Javascript (tsx) that implements the behavior of the component, it also has a CSS counter part to style look and feel. This is a high level of a custom button definition and how it is used in the index.gui file. The button has a property buttonLabel *and a method *setLabel, as well as the CSS style variables. The index.gui illustrated how to style the button using the CSS variables, how to set the attributes, how to call a method, and how to set the property.

![](images/web-components-classes.png”Classes”)

3.3.1. Setting property vs attribute

The terms property and attribute for a WebComponent are inter-changeable. They mean the same thing in terms of the underline storage, but are represented differently in HTML and Javascript. Attribute can be set in HTML markup (index.gui) and Javascript, but property can only be set in Javascript.

Important: When defining an attribute descriptively in HTML, the attribute needs to have a dash before any uppercase character. For example, the property buttonLabel can be represent with button-label using html attribute.

Attribute can be set in the Designer using the Properties panel or by switching to the index.gui file to source mode and manually add the attribute name and value to the HTML tag. Another method for setting attribute is at runtime using Javascript i.e document.querySelector(‘my-button’).setAttribute(‘button-label’, ‘FooBar’) as above.

To set a component property using Javascript, query select the element as previously and set the property value. It is important to not set the property before the WebComponent is defined as a HTML custom element, so an additional step must be done before using the query selected element. The method GcWidget.querySelector is a helper method that returns a Promise and wait for the the custom element my-button to be defined (registered) in the browser domain.

For example,

const init = () => {

GcWidget.querySelector(‘#btn’).then(element => {

element.buttonLabel = ‘FooBar’;

});

};

document.readState = ‘complete’ ? init() : document.addEventListener(‘DOMContentLoaded’, init);

3.3.2. Calling a method

This is very similar to setting a property of a WebComponent, it needs to wait until the component is defined in the browser domain. For example,

const init = () => {

GcWidget.querySelector(‘#btn’).then(element => {

element.setLabel(‘FooBar’);

});

};

document.readState = ‘complete’ ? init() : document.addEventListener(‘DOMContentLoaded’, init);

3.3.3. Styling a WebComponent

There are two different methods to style a component, decoratively with Stylesheet or inline, or programmatically at runtime with Javascript. Here are examples how to style a component:

// inline

<my-button style=”–label-color: #333” />

// stylesheet

<style>

–label-color: #333;

<style>

// programmatically

<script>

document.querySelector(‘#btn’).setProperty(‘–label-color’, ‘#333’); // note: –label-color is a CSS variable

document.querySelector(‘#btn’).color = ‘#333’; // setting standard CSS value

</script>