@salla.sa/twilight-components v2.13.43

Overview

Twilight comes with a ready-designed and styled set of web components for Salla stores. For example, ready components to display the login form, product availability section, search bar, localization menu, and many more. Twilight JS Web Components are a collection of high-level building blocks and reusable web components that can be built together to swiftly develop the UI for custom Salla Themes, governed by clear guidelines.

Getting Started

JS Web Components were built from the ground up to be simple to learn and use, with various thoughtfully constructed user interface components. Its complete compatibility with the themes' structure and architecture makes it easy to customize, as the documentation explains.

List of Twilight JS Web Components

Below is a list of the ready-made Twilight JS Web Components which can be used easily. Following, in this part of the document, each component is explained in detail.

Every web component comes with a list of properties and events that make that component customizable. Besides, each web component uses methods from the Twilight JS SDK to fetch any needed data from the backend.

Benefits

Clean, simple, and standardized.

Developers will follow standards and let users fall in love with the user experience with ready-made components and beautiful (yet changeable) themes. Developers can use a stylistic guideline and functional designs to create huge Themes with UI Component modules.

Using Twilight JS SDK

Twilight Web Components are using the Twilight JS SDK, which allows communication between the frontend and backend using specific REST API.

Ecosystem

Twilight Web Components are maintained by a full-time core team and a large community of developers and contributors. This is because Twilight helps developers collaborate.

Things to know:

It's worth noting that the Tailwind CSS Framework is the default foundation for the Twilight web components.There is a possibility that future plans may include other CSS frameworks.

Installation

To use the components, developers need to load a CSS file and some JavaScript. The CSS file includes the fonts and design tokens.

Twilight Themes

In case of using the Twilight web components inside the Twilight themes, the developer doesn't need to includes the Twilight web components in your bundle or inside the html, Twilight theme engine will inject the latest version of Twilight web components in the page

Bundler/ES modules

The developer needs to install both of the node.js and Tailwind CSS, then installing the Twiligh web components by performing one of the following commands:

npm install @salla.sa/twilight-components --save

yarn add @salla.sa/twilight-components

After that, inside the javascript codebase, developer may do import as follows:

import {
  applyPolyfills, 
  defineCustomElements as TwilightWebComponents
} from '@salla.sa/twilight-components/loader';

applyPolyfills().then(() => {
    TwilightWebComponents(window);
});

HTML/CDN

Another approach for loading the Twilight Web Components isby using the version hosted on the CDN. The components can be loaded via <script> tags in the head of the HTML document

<script
  type="module"
  src="https://unpkg.com/@salla.sa/twilight-components@latest/dist/twilight-components/twilight-components.esm.js"
></script>

JIT Enabled

Tailwind added a just-in-time compiler, which generates styles as the developer writes the theme rather than generating everything in advance at initial build time.

Since JIT mode generates your CSS on-demand by scanning your template files, it’s crucial that you configure the content option in your tailwind.config.d.ts file with all of your template paths, otherwise your CSS will be empty

...
  content: [
    // theme views
    "views/**/*.twig",
    // list of classes which required by twilight web components
    "node_modules/@salla.sa/twilight-tailwind-theme/safe-list-css.txt"
  ],
...

Previously, as mentioned that the file tailwind.config.d.ts is already bundled with the Twilight starter theme files.

Usage

After installation, Components can be easily added in the basic HTML markup, as shown in the following example:

// Salla Button component
<salla-button fill="outline" color="dark">Hello World 👋</salla-button>

// Salla Telephone Input component
<salla-tel-input onclick="telInput.isValid()" country-code="sa"
   country-key="+966" mobile="555555555">

// Salla Product Availability component
<salla-product-availability channels="sms,mobile,email" is-subscribed="false">
</salla-product-availability>

Events

We recommend using DOM events, but we also provide custom events to help with specific event kinds. All custom events are always documented on their own documentation page for each component.

// Save reference to the modal component below
var modal = document.querySelector("salla-modal");

// Listen for open events
modal.addEventListener("modalVisibilityChanged", function (isOpened) {
    console.log("Modal Opened");
});

Moreover, developers can detect when a component has been loaded, as Twilight registers its components using the standard Web Components API's CustomElementsRegistry object. This object also provides a whenDefined function, which takes a component name and returns a promise. When the component is defined, the promise will be fulfilled:

window.customElements.whenDefined("salla-button").then(() => {
    console.log("Salla Button is defined!");
});

Support

The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on Github using the Issue Tracker. If you still have any questions, please contact us via the Telegram Bot or join in the Global Developer Community on Telegram.

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Credits

• Salla
• All Contributors

License

The MIT License (MIT). Please see License File for more information.