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. |

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.