@salla.sa/twilight-components

Twilight JS Web Components

A ready-designed and styled set of js web components for Salla stores.
Explore our blogs »

Report Bug · Request Feature . </Salla Developers> . Offical Documentation

Table of Contents

1. Overview
2. Getting Started
   • List of Twilight JS Web Components
   • Benefits
3. Installation
4. Usage
5. Events
6. Support
7. Contributing
8. Credits
9. License

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.

Component	Code Tag	Description
Advertisement	salla-advertisement	Shows all the details about product advertisements.
Apps Icons	salla-apps-icons	Shows clickable labels of Google Play Store and Apple Store for the Store's application.
Add Product	salla-add-product-button	Allows controllability over button text labels and behaviors based on the product-status and product-type properties.
Breadcrumb	salla-breadcrumb	Helps users navigate by showing their path through pages, allowing them to easily go back by clicking on links.
Button	salla-button	Shows a customizable button, in terms of size, color, style, status, position, etc.
Cart Summary	salla-cart-summary	Shows the icon of the shopping cart with a small circle badge indicating the number of items in the cart.
Color Picker	salla-color-picker	Allows selection of a color using a variety of input methods.
Comments	salla-comments	Displays a comment form for specific products or pages.
Contacts	salla-contacts	Shows the store's contact information details.
Conditional Fields	salla-conditional-fields	Allows for hiding/displaying certain features in a product, such as size.
Conditional Offer	salla-conditional-offer	Enables dynamic presentation of offers and discounts based on the customer's cart status.
Count Down	salla-count-down	Shows the amount of time left until a given date.
Datetime Picker	salla-datetime-picker	Allows users to select both date and time with the same control.
File Upload	salla-file-upload	Allows the user to upload a file or a number of files.
Filters	salla-filters	Allows the user to filter the data in a variety of ways.
Gifting	salla-gifting	Displays items as gifts, which can be used after the customer has completed a purchase.
Infinite Scroll	salla-infinite-scroll	Allows for infinite scrolling to load content continuously as the user scrolls down a page.
Installment	salla-installment	Shows a block area for the available installment payment options provided for a specific product.
List Tile	salla-list-tile	Used to display listing items in a tile form.
Loading	salla-loading	Used to convey that some data is currently loading to the user.
Localization	salla-localization-modal	Shows the menu for the store's available languages and currencies.
Login	salla-login-modal	Displays the login form, which prompts a user for their credentials in order to authenticate their access.
Loyalty	salla-loyalty	Displays a popup that represents the Loyalty program.
Map	salla-map	Displays geographical maps from various sources with multiple layers and interaction through events.
Menu	salla-menu	Shows nested list items that either appear on the header section or footer section.
Metadata	salla-metadata	Shows detailed specifications for a product, displaying one or multiple sections of information like links, and text, etc.
Modal	salla-modal	Displays a dialog box or pop-up window on top of the current page.
Offer	salla-offer	Displays offers, categories, products, banks, and discount information.
Offer Modal	salla-offer-modal	Shows a list of products with an offer given by the store admin.
Orders	salla-orders	Shows a table with order details, such as order ID, product total, order status, and more.
Payments	salla-payments	Shows the available payment options as labeled footer items.
Placeholder	salla-placeholder	Reserves space for content that soon will appear in a layout.
Product Availability	salla-product-availability	Shows the "Notify availability" option as a button for the registered customer.
Product Card	salla-product-card	Contains content and actions about a single subject in a card display mode.
Product List	salla-product-list	Displays a group of related products with some information, such as products' names, prices, and other relevant information in an organized way.
Product Options	salla-product-options	Shows customizable product fields before proceeding to ordering.
Product Size Guide	salla-product-size-guide	Enables the merchant to add product measurements of height, weight, depth and other metrics.
Products Slider	salla-products-slider	Navigates horizontally through a group of related products.
Progress Bar	salla-progress-bar	Displays a progress bar indicating that data processing is underway.
Quantity Input	salla-quantity-input	Allows the customer to use a counter to specify the needed quantity of a specific product.
Quick Buy	salla-quick-buy	Allows for placing the Quick Buy button for a quickly checkout and pay for products.
Quick Order	salla-quick-order	Allows the customer to quickly checkout and pay for products.
Rating Stars	salla-rating-stars	Displays a form of rating scale using a star glyph.
Rating Modal	salla-rating-modal	Displays the rating scale for a store, product, or shipping company.
Reviews	salla-reviews	Displays vertically scrollable reviews, which can its data source can be customized.
Reviews Summary	salla-reviews-summary	Allows users to display the general rating out of 5 stars on the product details page.
Scopes (Branches)	salla-scopes	Shows a list of scopes (branches) owned by the store.
Search	salla-search	Shows a search box, field, or bar.
Sheet	salla-sheet	Baseline layout foundation for other components to be set on.
Skeleton	salla-skeleton	Displays an indication to the user that something is coming but not yet available.
Slider	salla-slider	Gathers numerical user data by reflecting a range of values along a bar.
Social	salla-social	Displays a list of the store's social media account.
Social-share	salla-social-share	Displays a menu with social media platforms.
Swiper	salla-swiper	Modern touch slider to display a list of items.
Tabs	salla-tabs	Makes it possible to have several panes inside a single view.
Tel Input	salla-tel-input	Shows a field for entering a telephone number, with country key/code prefix.
User Menu	salla-user-menu	Shows a navigation menu list with links.
User Profile	salla-userprofile	Displays user profile detailed information.
User Settings	salla-user-settings	Allows the user to manage their account settings.
Verify	salla-verify	Shows fields for verifying email/mobile of users by sending OTP verification code.

(back to top)

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.

(back to top)

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.

(back to top)

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!");
});

(back to top)

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.

(back to top)

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

(back to top)

Credits

• Salla
• All Contributors

(back to top)

License

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

(back to top)