# Embedded / Application

# Shopfront Embedded Bridge Application API

Whilst most of the time you'll be using the Embedded API in a reactive fashion (through the use of events),
we also support a few methods that can be called at anytime.

## Events
Most of the Embedded API gets used through the event system, you can find out about the events [here](/documentation/Embedded/Receivable%20Events).

### addEventListener

| Field | Type | Description |
| --- | --- | --- |
| type | string | The type of event to listen for |
| callback | `(data) => void` | The callback to fire when the event occurs (the callback is dependant upon event type) |

*Returns*

- void

**Add Event Listener**

```javascript
application.addEventListener("REQUEST_BUTTONS", (context) => {
    // Handle the request here
});
```

### removeEventListener

| Field | Type | Description |
| --- | --- | --- |
| event | string | The event this is being listen for |
| callback | `(data) => void` | The callback to remove |

*Returns*

- void

**Remove Event Listener**

```javascript
const listener = () => {};

application.addEventListener("REQUEST_BUTTONS", listener);
application.removeEventListener("REQUEST_BUTTONS", listener);
```

## Loading
You can show a loading screen on Shopfront by calling the `load` method, we would highly suggest only doing this
in response to an event as you can't be sure what screen is currently open

### load

Calling the load function shows a loading screen on Shopfront and returns a callback, to stop loading, call the returned
callback.

*Returns*

- `() => void`

**Load**

```javascript
const stopLoading = application.load();
setTimeout(stopLoading, 10000);
```

## Sending Components & Events to Shopfront

You can send "components" to Shopfront to do things like display dialogs, redirect the page, etc. For information
about the components to send, [look here](/documentation/Embedded/Components).

There are also events that you can send to Shopfront which allow you to control the user interface without having to
wait for user interaction. For information about the events available to be emitted, 
[look here](/documentation/Embedded/Emitable%20Events).

### send

| Field | Type | Description |
| --- | --- | --- |
| componentOrEvent | Component / EmitableEvent | The component or event to send |

**Send**

```javascript
const toast = new Toast("success", "You've done well!");
application.send(toast);
```

## Retrieving & Modifying the Current Sale

You can retrieve and modify the current sale if the device your application is embedded on is a register.
You can do things like add and remove products, payment methods and the customer.

In order to modify the sale, you must first retrieve it through the `getCurrentSale` method on the `application`.

This method returns the current sale which has a number of functions to modify and retrieve details about the sale, more
documentation can be found [here](/documentation/Embedded/Sale). 

### getCurrentSale

Get the current sale from Shopfront

*Returns*

- `Promise<Sale>`

**Sale**

```javascript
const currentSale = await application.getCurrentSale();
```

## Modifying the Sell Screen Display Mode

Shopfront's sell screen is divided into two sections or 'containers'. The 'action' container is on the left, and the 'summary' 
container is on the right.

Each container has a `mode` that determines what content it displays.

## Modifying the Action Display Mode

### changeSellScreenActionMode

Changes the display mode of the sell screen's 'action' container

| Field | Type       | Description                         |
|-------|------------|-------------------------------------|
| mode  | ActionMode | The action mode you wish to display |

*Returns*

- `void`

<br />

The 'action' container is responsible for displaying the following modes

| ActionMode        | Description                                                       |
|-------------------|-------------------------------------------------------------------|
| keys              | Displays a search bar on top, and the register's sales keys below |
| search            | Displays a search bar on top, and the search results below        |
| held-sales        | Displays a list of all the vendor's parked sales                  |
| payment           | Displays a number pad and all available payment methods           |
| customers         | Displays a list of all the vendor's current Shopfront customers   |
| promotions        | Displays a filter bar on top, and all relevant promotions below   |
| back-orders       | Displays a list of all the vendor's back-orders                   |
| fulfilment-orders | Displays a list of all the vendor's fulfilment orders             |

Changing the `ActionMode` may also force the SummaryMode to change as well. The following `ActionModes` will force a 
`SummaryMode` change

| ActionMode | SummaryMode |
|------------|-------------|
| payment    | payments    |

**Change Sell Screen Action Mode**

```javascript
application.changeSellScreenActionMode('keys')
```

## Modifying the Summary Display Mode

### changeSellScreenSummaryMode

Changes the display mode of the sell screen's 'summary' container

| Field | Type        | Description                          |
|-------|-------------|--------------------------------------|
| mode  | SummaryMode | The summary mode you wish to display |

*Returns*

- `void`

<br />

The 'summary' container is responsible for displaying the following modes

| Mode             | Description                                                   |
|------------------|---------------------------------------------------------------|
| transaction      | Displays the sale transaction summary (products, total, etc.) |
| payments         | Displays a list of all payments attached to the current sale  |
| receipts         | Displays the receipt for the previous sale                    |

**Change Sell Screen Summary Mode**

```javascript
application.changeSellScreenSummaryMode('transaction')
```