Glossary

...

Attribute

It's a notation inside the HTML tag that provides additional information about HTML element. For the names of the attributes, we will always use kebab-case to follow the standard.

An example:

<z-button icon="close:line"></z-button>

There are some attributes that are considered flags and some that are considered complex.

For more information, check the MDN documentation.

Complex attribute

It's an attribute that represents an object or an array. In order to properly write them down, the regular double quotes (") can be written with simple ones (') an the value of the attribute needs to be in JSON format.

<z-select options='[{"value": "a", "text": "Option A"}, {"value": "b", "text": "Option B"}]'></z-select>

They can be injected from the JavaScript side, but it's sometimes more comfortable to use the slotted configuration if you are using a plain WebComponent without a framework wrapper. Using JS to inject the attribute can be done like this:

const select = document.querySelector('z-select');
select.options = [
  {"value": "a", "text": "Option A"}, 
  {"value": "b", "text": "Option B"}
];

For more information, check the MDN documentation and the specific documentation of ZDS.

Flag

It's an attribute that represents a boolean, but can only be set to true. It's considered false when the attribute is not present. A good example of this is checked in HTML <input> tags.

All these examples consider wide as true, so the wide variant will be applied:

<z-button wide />
<z-button wide="" />
<z-button wide="true" />
<z-button wide="false" />
<z-button wide="❌" />

If you're using a framework, make use that the type of the flag is true | undefined, since false will still set the attribute, and HTML will consider it as an active flag. You can set the fallback with an OR (||) in the assignation of the attribute or when you are assigning the bound variable.

An example for the three main frameworks:

<z-text-input [invalid]="isInvalid || undefined"/> <!-- Angular -->

<z-text-input .invalid="isInvalid || undefined"/> <!-- Vue -->

<z-text-input invalid={isInvalid || undefined}/> {/* React */}

Property

It's the attribute but the JavaScript class instance. Setting the value of the attribute will change the property, but not the other way around. Acting on a component, like an <input>, changes the property, but not the attribute. The pseudo-classes of CSS will follow the property and not the attribute, and that's why it is important to keep internal consistency in the components.

For example, the value property of an <input> tag:

<input value="Hello" />

const input = document.querySelector('input');
console.log(input.value); // Hello

For more information, check the MDN documentation.

Shadow DOM

Provides a way to attach a hidden, separate DOM to an element. This shadow DOM tree starts with a shadow root, under which any element can be attached. This encapsulation allows the styling and scripting of web components to be isolated from the rest of the document, preventing conflicts and ensuring encapsulation.

For more information, check the MDN documentation.

HTML Templates

(<template> and <slot> elements). The <template> tag is used to declare fragments of HTML that can be cloned and inserted in the document by script. <slot> elements are placeholders inside your component that can be filled with any markup fragment that the user of your component provides.

For more information, check the MDN documentation.

Custom Elements

This allows developers to define their own custom HTML elements along with their behavior. This is a key part of the Web Components standard, which enables the creation of reusable and encapsulated components in web development.

Key Features of Custom Elements:

• Custom Tag Names: You can create new HTML tags that are not part of the standard HTML specification.
• Encapsulation: Custom elements can encapsulate their structure, style, and behavior, preventing conflicts with other parts of the application.
• Lifecycle Callbacks: Custom elements have lifecycle callbacks that allow you to run code at specific points in the element's lifecycle, such as when it is added to or removed from the DOM.

Example of a Custom Element:

class MyCustomElement extends HTMLElement { // Define a class for the new element
  constructor() {
    super();
    // Element's initialization code
  }
  
  connectedCallback() { // Called when the element is added to the DOM
    this.innerHTML = '<p>Hello, I am a custom element!</p>';
  }

  disconnectedCallback() { // Called when the element is removed from the DOM
    console.log('Custom element removed from the DOM');
  }

  attributeChangedCallback(name, oldValue, newValue) { // Called when an attribute is added, removed, or changed
    console.log(`Attribute ${name} changed from ${oldValue} to ${newValue}`);
  }

  static get observedAttributes() { // Specify observed attributes so that attributeChangedCallback will work
    return ['my-attribute'];
  }
}

customElements.define('my-custom-element', MyCustomElement); // Define the new element

Usage in HTML:

<my-custom-element my-attribute="value"></my-custom-element>

For more information, check the MDN documentation.

WebComponent

Web Components are a set of web platform APIs that allow developers to create custom, reusable, encapsulated HTML tags for use in web pages and web applications.

Web Components enable a modular approach to web development by allowing developers to create new elements that extend the HTML language itself, encapsulating the functionality and styling of these elements, and reusing them across different web applications.

They are based on four main technologies:

1. Custom Elements: Define your own HTML elements with custom behavior.
2. Shadow DOM: Encapsulate the internal structure and style of your components, preventing conflicts with the rest of the document.
3. HTML Templates: Declare fragments of HTML that can be cloned and inserted into the document by script.
4. HTML Imports (deprecated): Include and reuse HTML documents in other HTML documents.

Key features of WebComponents:

• Reusability: Create components that can be reused across different web applications.
• Encapsulation: Encapsulate the functionality and styling of components, preventing conflicts with other parts of the application.
• Modularity: Enable a modular approach to web development by allowing developers to create new elements that extend the HTML language itself.

Defining a Custom Element with Shadow DOM:

class MyWebComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <style>
        p {
          color: blue;
        }
      </style>
      <p>Hello, I am a Web Component!</p>
    `;
  }
}

customElements.define('my-web-component', MyWebComponent);

Using the Web Component in HTML:

<my-web-component></my-web-component>

For more information, check the MDN documentation.

JS Framework

A JavaScript framework is a collection of JavaScript code libraries that provide developers with pre-written code for routine programming tasks. These frameworks offer a structured and organized way to build web applications, making development faster and more efficient. They typically include tools and libraries for handling common tasks such as:

• DOM Manipulation: Simplifying the process of interacting with the Document Object Model (DOM).
• Event Handling: Managing user interactions and events.
• State Management: Keeping track of the application's state and ensuring consistency.
• Routing: Handling navigation and URL management within single-page applications (SPAs).
• Data Binding: Synchronizing data between the model and the view.

Examples of Popular JavaScript frameworks that we provide support to:

1. Angular

   • Developed and maintained by Google.
   • Uses TypeScript, a superset of JavaScript.
   • Provides a comprehensive solution for building SPAs with features like dependency injection, two-way data binding, and a powerful CLI.

2. React

   • Developed and maintained by Facebook.
   • Focuses on building user interfaces, particularly for SPAs.
   • Uses a component-based architecture and a virtual DOM for efficient rendering.
   • Often paired with other libraries for state management (e.g., Redux) and routing (e.g., React Router).

3. Vue

   • Developed by Evan You and maintained by the open-source community.
   • Known for its simplicity and ease of integration.
   • Uses a component-based architecture and a reactive data-binding system.
   • Suitable for both small and large-scale applications.

Wrapper

They are re framework-specific components that wrap a WebComponent and eases the use of these, making them usable as a framework native component.

Each components' package has its own wrapping components.

• Angular has it's own package.
• React has wrappers for WebComponents and CSS components
• Vue also has wrappers for WebComponents and CSS components

CSS Custom Property

CSS Custom Properties, commonly referred to as CSS variables or CSS Tokens, are entities defined by CSS authors that contain specific values to be reused throughout a document. They follow the syntax --name: value;, where --name represents the custom property name, and value is the value assigned to it.

These properties can be accessed using the var(--name) function in other CSS properties. CSS Custom Properties enable more flexible and dynamic styling by allowing values to be changed or updated in multiple places by altering a single definition. This feature significantly enhances the maintainability and scalability of CSS code.

An example about how to define a CSS Custom Property:

:root {
  --z-button--bg: red;
}

For more information, check the MDN documentation.

::part selector

The ::part pseudo-element selector is used to style the internal parts of a Web Component. It allows developers to select and style specific elements inside a shadow tree, providing a way to customize the appearance of a component.

An example:

z-button::part(button) {
  color: red;
}

For more information, check the MDN documentation.

Slot

A slot is a placeholder inside a web component that users can fill with their own markup. Slots are used to create flexible and reusable components that can be customized by users without modifying the component's internal structure.

Key features of slots:

• Content Projection: Allows users to insert their own content into predefined placeholders within a web component.
• Named Slots: Multiple slots can be defined with different names, allowing for more complex content distribution.
• Default Content: If no content is provided for a slot, default content can be specified.

Defining a slot in a WebComponent:

<template id="my-component-template">
  <style>
    /* Styles for the component */
  </style>
  <div>
    <slot name="header"></slot>
    <slot></slot> <!-- Default slot -->
    <slot name="footer"></slot>
  </div>
</template>

<script>
  class MyComponent extends HTMLElement {
    constructor() {
      super();
      const template = document.getElementById('my-component-template').content;
      this.attachShadow({ mode: 'open' }).appendChild(template.cloneNode(true));
    }
  }

  customElements.define('my-component', MyComponent);
</script>

Using the slots in HTML:

<my-component>
  <div slot="header">This is the header content</div>
  <p>This is the default slot content</p>
  <div slot="footer">This is the footer content</div>
</my-component>

For more information, check the MDN documentation or earn more about this ZDS feature in here

Slotted configuration

It's a way to define the some of the attributes that a WebComponent has (normally complex ones) by using HTML tags placed inside the component's default slot. This way, the user can define the configuration of the component without the need of using JavaScript of JSON objects in the HTML.

An example. Instead of using the following:

<z-select options='[{"value": "a", "text": "Option A"}, {"value": "b", "text": "Option B"}]'></z-select>

You can use the following:

<z-select>
  <option value="a" text="Option A"></option>
  <option value="b" text="Option B"></option>
</z-select>

Learn more about this ZDS feature in here