Overview

✨Twilight comes with a JavaScript SDK for the Salla storefront APIs. This is to provide the developers with helper methods, or REST API endpoints, that allow communication between the frontend and backend. As a result, developers may use these methods to make merchants' stores dynamic after using the API features and data. In this documentation, we will be referring to it as Twilight JS SDK for short.

:::info[Information]
SDK stands for "software development kit," and it refers to a library for interacting with a specific REST API using JavaScript.
:::

In this article, we will explore the different parts of the Twilight JS SDK.

📙 What you'll learn

• SDK main APIs.
• Use cases.
• Installation.
  • Initialization.
• Usage
  • Basic configuration.

SDK's main APIs

The main parts of the Twilight JS SDK includes REST API endpoints that ease the actions related to the APIs request, such as:

Use cases

Following are some of the possible uses of the Twilight JS SDK:

Installation

Twilight JS SDK can be used without the need to be downloaded or installed; instead it needs to be included as a short piece of regular JavaScript in the HTML that will asynchronously load the SDK into the Twilight theme. 

<script src="https://cdn.jsdelivr.net/npm/@salla.sa/twilight@latest/dist/@salla.sa/twilight.min.js"></script>

<script>
  salla.init({
    debug: true, // disbale it in prod
    language_code: 'ar', // en
    store: {
      id: 1305146709, // The store id can found via store pages.
      url: "https://the-best-store-ever.sa"
    }
  });
</script>

npm install @salla.sa/twilight --save

yarn add @salla.sa/twilight

import '@salla.sa/twilight';

<script>
  salla.init({
    debug: true, // disbale it in prod
    language_code: 'ar', // en
    store: {
      id: 1305146709, // The store id can found via store pages.
      url: "https://the-best-store-ever.sa"
    }
  });
</script>

Usage

As a result of the SDK initialization, the developer will be able to use any of the SDK's main APIs. For example, the method addItem adds an item into the cart, the developer may call the method addItem as follows:

salla.cart.addItem({
    id: 1234,
    quantity: 1,
    notes: "please i need to get the red color"
}).then((response) => {
    /* add your code here */
});

In addition to the above example, the method addItem may add an item with multiple options to the carts as follows:

salla.cart.addItem({
    id: 1234,
    quantity: 1,
    options: {
      117414452: 11232214, // option value id (select choice)
      117416632: "http://option-value-as-url-of-image.com",
      117411132: "option value as string"
    },
    notes: "please i need to get the red color"
}).then((response) => {
    /* add your code here */
});

Furthermore, a large number of store events will be available for use. Thus, the developer's Theme may be configured to respond automatically to a variety of activities, such as:

• The user requested an Access Code to perform a login, however, the code was not sent. For this scenario, using the method salla.event.auth.onCodeNotSent((error, type) => console.log(error, type)) can be used.

• A new item has been added to the cart via the salla.cart.event.onItemAdded((response, product_id) => console.log(response, product_id)) method.

• The user added a new item to the Wishlist using the method salla.event.wishlist.onAdded((response, product_id) => console.log(response, product_id)).

Full example for that would be the event onItemAdded which is triggered when adding an item to the cart is done without having any errors coming back from the backend:

salla.cart.event.onItemAdded((response, product_id) => {
  console.log(response)
});

On the other hand, the event onItemAddedFailed is triggered when adding an item to the cart is not completed and an error has occurred. For example, the id of the product to be added to the cart was not found.

salla.cart.event.onItemAddedFailed((errorMessage) => {
  console.log(errorMessage)
});

Basic configuration

Aside from calling the APIs, the developer has the ability to configure the Twilight engine to meet the needs of his theme.

This list of the available configurations can be found in this article.

For this purpose, the method `salla.config.get()` is used to retrieve a configuration value, while `salla.config.set()` is used to set a configuration value.

Set configuration value

The developer may set the debug mode to be activated. That is to state, the theme will be run in a debugger. This means that the debugger keeps track of everything that happens while the theme is running.

salla.config.set('debug', true)

Get configuration value

Similarly, the developer can use the method salla.config.get() to get any value from the configuration file. To retrive simaple value such as the user Id, the following syntax can be followed:

salla.config.get('user.id’)

Furthermore, if the required value is nested inside an inner value, such as a currency code, the following syntax can be followed:

salla.config.get('currencies.SAR.code’)